codechart

See the shape of a change before you read it.
A skill for AI coding agents that turns their plans and change summaries into maps and flowcharts — checked against your code.

Install · Features · Trust · Cost · Configure · Docs

---

The problem

Your agent just finished a change. Its summary reads like this:

Done. Migration 0042 adds coupon_code to orders and changes orders.status; adds refunded to the order_status enum and bank_transfer to payment_method; creates invoices (order_id, method, number) and backfills one invoice per paid order, numbered from INVOICE_PREFIX. OrderStatus and PaymentMethod mirror the new enum values; new Invoice model. POST /orders/{id}/refund sets OrderStatus.REFUNDED, gated by refundsEnabled. Didn't read customers beyond its id. Tests in test_invoice_backfill.py; updated CHANGELOG.md and .env.example.

Every word is correct, and you still don't see it. Which of those are new, and which already existed? What does invoices point at? What does the flag actually gate? You open the diff and trace it by hand. On a 20-file change, that's where your review time goes.

The fix

With codechart, the same reply starts with this:

Map (key: + new ~ changed - removed ◆ config · unmarked = unchanged)

database
~ orders ─customer_id─▶ customers
         ─status──────▶ enum order_status
+ invoices ─order_id─▶ orders
           ─method───▶ enum payment_method
~ enum order_status
~ enum payment_method

backend
~ model OrderStatus ─mirrors─▶ enum order_status
+ model Invoice ─maps─▶ invoices
+ endpoint POST /orders/{id… ─sets refunded─▶ model OrderStatus
~ model PaymentMethod ─mirrors─▶ enum payment_method

config
+ migration: backfill invoi… ─backfills─▶ invoices
◆ INVOICE_PREFIX ─read by─▶ migration: backfill invoices for paid orders
◆ feature flag refundsEnabl… ─gates─▶ endpoint POST /orders/{id}/refund

12 nodes · 4 new · 5 changed · 2 config · ✓ 10 checked
gaps: customers: columns besides id not read
not on map: tests: test_invoice_backfill.py · docs: CHANGELOG.md, .env.example

Open full map

New things are +, changed ones ~, removed ones -, config ◆; anything unmarked already existed. The block is a diff fence, so Claude Code, OpenCode, Codex, Gemini CLI, Cursor and GitHub colour the new and removed lines on their own. Layers are grouped, every relation is drawn, and ✓ 10 checked counts the claims checked against your files and the git diff; boxes without a file are listed separately as not checkable. It takes ten seconds to read, and gaps tells you what the agent didn't look at.

Open full map opens an interactive page. Click any node for its summary, file, fields — and in a change summary, its diff, read straight from git:

You don't need to ask for any of this. The skill fires when the agent summarizes changes, writes a plan, or explains how code behaves, and stays quiet for typo fixes.

Install

npm i -g codechart && codechart install-skill

Install may edit global files (~/.claude/CLAUDE.md, your agents' AGENTS.md/GEMINI.md, ~/.claude/settings.json) when you accept its extras; Install and agents says what each adds.

That's it. Open your coding agent in any repo and try:

> summarize the uncommitted changes
> plan adding refunds to orders
> show me the flow of accepting an invite

Works with Claude Code, Codex, Gemini CLI, GitHub Copilot, Cursor, OpenCode and any other agent that supports Agent Skills. Reminders that keep agents using it, updating, codechart doctor when no diagram appears, and uninstalling: Install and agents.

Features

Flows Ask how something works and get its decisions, edge cases and outcomes as a flow. Every step is tied to a real line of code; click one on the page to see it. More: Flows
Plans: Now and After A plan that touches existing code opens as two panes side by side. What it removes is red in Now; what it adds is green in After. More: Plans
Plan vs built When the work is done, the summary is compared with the plan. What was dropped, added or built differently is marked, each with the agent's reason. More: Plan vs built
Infrastructure Terraform, OpenTofu, Helm, Kustomize and Kubernetes changes get a map of resources and what they reference. Built in, no rule to write. More: Infrastructure maps
Review on the page Comment on any node, line or arrow, ask a question, or ask for a deletion. Finish review copies your notes; paste them into your agent chat. More: Review on the page
Review in the terminal codechart review opens the map in your editor as a diff. Write notes under any line, save, and tell your agent "review done". More: Review in the terminal
Maps in pull requests PR and MR descriptions end with a collapsed map, and CI redraws it on every push. No AI or tokens in CI. Turn it on once per repo. More: Maps in pull requests
Explain map On request, a map of how an existing area works, for someone new to the project: one box per table, service or endpoint, what each is for, and the neighbours it talks to. A Flows tab walks through its main behaviours step by step, each step linked to its box and to the line of code. Nothing changed, so no diff. More: Explain map
Business map On request, a plain-words page for a product owner with no repo access: journeys, rules, saved data and questions. They answer, confirm and send it back. It can also explain how an area works today, for a product owner, QA or support: one lane diagram of who does what, plus rules and odd cases (read-only). More: Business map
Release map On request, a PDF of what's new in a release, in plain words, for sales: a cover, then a section per feature. It only holds what the agent checked in the code, so nobody has to review it. More: Release map

The full page

Big diagrams also get a self-contained HTML page: click a node for its summary and diff, read straight from git, tick nodes as reviewed, and move around with the keyboard. Nothing is loaded from the internet. More: The full page.

When it fires

When the agent summarizes a change, writes a plan or explains how code behaves: migrations and models, infrastructure, 3+ related files (map), 2+ decisions or edge cases (flow). One-file text, comment, formatting or version-bump changes are skipped. Your own rules run first: Configuration.

Why you can trust the diagram

• The agent writes data, codechart draws. Layout is code, not hand-drawn ASCII.
• Claims are checked against your files and the git diff: each file exists, a quoted line is in it, and a new, changed or removed box matches git's added, modified, deleted or renamed status. A listed field or an arrow the code doesn't mention is a softer warning. Not checked: whether a label, summary or note is true, and boxes without a file (they show as not checkable). A ✓ 10 checked or a ✗ says what matched or didn't.
• Nothing left off quietly: every changed file is on the map or listed as left out.
• Flows are tied to real lines, and whatever the agent didn't read is listed under gaps.

More: Why you can trust the diagram.

Cost

A diagram is about 2–3 extra API calls, roughly 2–3% of a long session's usage, and nothing for trivial changes. The CLI is a 170.0 kB package. Measured runs: Efficiency.

Safe to run

• No telemetry, no shell except two fixed cases: npm on Windows during codechart update, and the editor you choose with $VISUAL or $EDITOR for codechart review. git is read-only. Pages load nothing external and are saved to ~/.cache/codechart, never to your repo. The only network calls: a daily version check, plus that version's changelog from GitHub when there's a newer one (off with one setting), and opt-in PR maps.
• Audited before release across 8 areas, including untrusted repos and prompt-injected specs: SECURITY.md and docs/security-review.md.

Configure

Works with zero config. codechart init writes a commented .codechart.yaml for your own rules, and codechart config shows what's in effect: Configuration, CLI.

FAQ

Will it draw a diagram for every tiny change? No. One-file text, comment, formatting or version-bump changes are skipped. Flows only appear for logic with 2+ decisions or edge cases, or when you ask for one.

Does my code leave my machine? Not because of codechart. The diagram is built from what your agent already read, and the daily version check sends nothing but the request for the newest version number. Only with PR maps on does CI send the map image and description to your own GitHub or GitLab, where the PR already lives.

Where do the HTML pages go? ~/.cache/codechart. It keeps the newest 20 per repo, plus anything under 7 days old.

More questions (permissions prompts, editors that open HTML as text, agents not on the list): Install and agents. All docs: docs/.

License

MIT. Depends on elkjs (EPL-2.0): see THIRD_PARTY_NOTICES.md.