codechart
v1.0.1
Published
Agent skill + CLI: maps and flowcharts of code changes, and of how existing code works, for AI coding agents, in terminal, chat and HTML
Maintainers
Readme
The problem
Your agent just finished a change. Its summary reads like this:
Done. Migration
0042addscoupon_codetoordersand changesorders.status; addsrefundedto theorder_statusenum andbank_transfertopayment_method; createsinvoices(order_id,method,number) and backfills one invoice per paid order, numbered fromINVOICE_PREFIX.OrderStatusandPaymentMethodmirror the new enum values; newInvoicemodel.POST /orders/{id}/refundsetsOrderStatus.REFUNDED, gated byrefundsEnabled. Didn't readcustomersbeyond its id. Tests intest_invoice_backfill.py; updatedCHANGELOG.mdand.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… ─reads─────▶ INVOICE_PREFIX
─backfills─▶ invoices
◆ INVOICE_PREFIX
◆ feature flag refundsEnabl… ─gates─▶ endpoint POST /orders/{id}/refund
12 nodes · 4 new · 5 changed · 2 config · ✓ 10 checked · 2 not checkable
gaps: customers: columns besides id not read
not on map: tests: test_invoice_backfill.py · docs: CHANGELOG.md, .env.exampleOpen 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 (the two enums here) are counted 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-skillInstall 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 inviteWorks 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 checkedor 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. That figure was measured on 2026-10-28 with a skill of 7.1k chars; the skill is now 17.0k chars (about 4.2k tokens), so a diagram costs more than that, and the benchmark has not been re-run. The CLI is a 208.5 kB package. Measured runs: Efficiency.
Safe to run
- No telemetry, no shell except two fixed cases:
npmon Windows duringcodechart update, and the editor you choose with$VISUALor$EDITORforcodechart review.gitis read-only, except the push ofsetup-pr-maps --prand the PR map CI job. 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);codechart update;release-context, through your ownghorglab; 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.
