chalk-talk v0.2
NEW v0.2: every arrow now has a receipt

Don't read the map. Watch the journey.

Ask your coding agent how something works. Get a step-by-step animated walkthrough of the real code path in one HTML file, where every arrow is traced to a real line of code, or honestly marked as a guess.

/plugin marketplace add oztrkemree/chalk-talk
/plugin install chalk-talk@chalk-talk

Then just ask: how does auth work in this repo?

Works withClaude CodeCodexCursorGemini CLIOpenCodeCopilotvia the Agent Skills standard

Step 1 of the talk How Vite hot-updates a module: you save a file in your editor Step 1 of the talk How Vite hot-updates a module: you save a file in your editor

LIVE How Vite hot-updates a module · vitejs/vite · 7 of 8 hops traced → step  P play  V proof view  click a block for its code Open full page ↗

Proof

Every arrow has a receipt.

Diagram tools draw what might connect. chalk-talk only draws a hop when it can point at the line that makes it. The build opens the cited file, finds the call inside the cited lines, and marks the result on the arrow.

  • Verified ✓

    The file and lines exist, and the call that proves the hop was found in them, like hot.send({ in server/hmr.ts:783-794. Click the arrow and that line is highlighted.

  • Inferred ?

    Some hops have no single line: a network boundary, an OS event, framework magic. The agent says so and says why. In proof view these turn dotted.

  • Broken !

    Cited code that isn't there, or doesn't contain the call. The build prints a warning, the arrow turns red, and the agent fixes the scene before you ever see it.

Proof view of the Vite talk: seven arrows carry a green check, the first hop from you to the file watcher is dotted with a question mark, and a chip reads Proof: 7 traced, 1 inferred Proof view of the Vite talk: seven arrows carry a green check, the first hop from you to the file watcher is dotted with a question mark, and a chip reads Proof: 7 traced, 1 inferred
Proof view (press V). The one guess, “your editor writes the file; the OS event reaches chokidar outside Vite's code”, is labelled as one. Open it live
$ node build.mjs vite-hmr.scene.json
proof: 7/8 hops traced to code (7 verified, 0 cited) · 1 inferred · 0 broken
$ node build.mjs my-talk.scene.json
WARNING proof: edge reply -> calls "res.send(" not found in src/app.js:10-20
New in v0.2

Same talk, on a chalkboard.

One scene file, several looks. Add ?style=chalk to any talk (or "style": "chalk" to the scene) and it is drawn by hand on a green board, proof marks and all. Flip it here:

What git commit writes to disk, drawn in chalk on a green board: every block and arrow sketched by hand What git commit writes to disk, drawn in chalk on a dark board: every block and arrow sketched by hand

LIVE What git commit writes to disk · git/git · 9 of 9 hops traced Open full page ↗

How it works

The agent tells the story. The engine draws it.

Your agent never writes SVG. It writes a short scene file; a dependency-free engine does layout, routing, labels and proof, and hands back one HTML page.

  1. You ask

    “How does a hot update reach the browser?” In plain words, in any language.

  2. The agent reads the code

    It picks one journey and writes scene.json: blocks, arrows, steps, and the file and lines behind each one.

  3. The build checks it

    build.mjs opens every cited range, verifies the calls, embeds the snippets with GitHub permalinks.

  4. One HTML file

    check.mjs screenshots every step so the agent looks before you do. Then it opens for you.

vite-hmr.scene.jsonone edge
{ "id": "send", "from": "hmr", "to": "ws",
  "label": "hot.send", "packet": "update",
  "code": { "file": "packages/vite/src/node/server/hmr.ts",
            "lines": [783, 794] },
  "calls": ["hot.send({", "type: 'update'"] }

{ "id": "save", "from": "you", "to": "watcher",
  "inferred": "the OS file event reaches chokidar
               outside Vite's code" }
  • Builds up. Each step adds one thing and makes one point; the last step replays the whole trip.
  • Shows movement. Named packets like update or SELECT travel the arrows in order.
  • Opens the code. Click a block or an arrow label: highlighted lines, a permalink to the exact commit, open in VS Code or Cursor.
  • Clean by construction. Isometric blocks, routed paths, no overlapping labels, light and dark, portrait on phones.
  • One file. No server, no account, no build step on the reader's side. Send it, commit it, attach it to a PR.
Use it for

Whenever “how does this work?” deserves a better answer than a wall of text.

Onboarding

A new teammate gets the request path, the job queue and the auth flow as walkthroughs they can click into, not a stale wiki diagram.

walk me through what happens when a webhook arrives

Understanding AI-written code

Your agent wrote 2,000 lines this afternoon. Ask it to show you how they fit together, with every claim pinned to a line you can check.

show me how the retry logic you just wrote actually runs

Explaining a PR

Change mode marks what a branch adds, changes and removes on the journey, with a before/after toggle. Attach the file to the review. See Express PR #7459

explain this PR as a chalk talk

Teaching

Step through a protocol, an algorithm or a framework's internals one point at a time, at your pace, in your language, on a projector or a phone.

bu kuyruk sistemi nasıl çalışıyor, çizerek anlat
FAQ

Questions

How accurate is it?

As accurate as the code it cites, and it shows you which is which. Every arrow is either verified (the build found the cited lines and the call inside them), inferred (the agent explains why there's no single line), or broken (flagged red, with a build warning). The page sums it up, for example “7 of 8 hops traced to code · 1 inferred”.

Captions are still written by a model, so read them like a colleague's explanation: the receipts are one click away.

Does my code leave my machine?

No. chalk-talk is a skill your agent runs locally: it reads files from your checkout, the build runs on your machine, and the result is a local HTML file. There is no chalk-talk service, account or telemetry; nothing is uploaded. (Your agent talks to its own model provider as it always does.)

Sharing a talk? CHALK_SHARE=1 leaves your local file paths out of the page; GitHub permalinks stay.

What about big repos?

chalk-talk doesn't map the whole repo, on purpose. Each talk follows one journey (“a request hits the router”, “an order becomes an email”) in six to ten steps. Ask for as many talks as you need; the agent only reads the files on that path.

Which agents and languages work?

Any agent that supports the Agent Skills standard: Claude Code, Codex, Cursor, Gemini CLI, OpenCode, GitHub Copilot and others. The code can be in any programming language, and captions can be in any human language.

Does the page need a server or internet?

No. The output is one self-contained HTML file with the code snippets embedded. It works offline; it only fetches its web fonts when online and falls back to system fonts otherwise.

Can I change a talk after it's made?

Yes. Keep the scene.json next to the HTML and ask for changes (“split step 3”, “show the retry path”); the agent edits the scene and rebuilds. You can also build by hand: node build.mjs my-talk.scene.json.

What does it cost?

Nothing. It's open source under the MIT license. Use it, fork it, ship it.

Ask your agent how something works.

Free, MIT, offline. One install, then ask in your own words.