chalk-talk
Health Uyari
- License — License: MIT
- Description — Repository has a description
- Active repo — Last push 0 days ago
- Low visibility — Only 8 GitHub stars
Code Gecti
- Code scan — Scanned 12 files during light audit, no dangerous patterns found
Permissions Gecti
- Permissions — No dangerous permissions requested
Bu listing icin henuz AI raporu yok.
Ask Claude "how does this work?" and get an animated isometric diorama of your system, with every block one click away from its code.
chalk-talk
Don't read the map. Watch the journey.
Ask your coding agent "how does this work?" and get a step-by-step animated walkthrough of the
real code path, in one HTML file, where every arrow is traced to the line of code it happens on
or honestly marked as a guess.
Live site & gallery · Install · Proof · Explain a PR · Scene format
English · 简体中文 · 日本語 · 한국어 · Español · Türkçe

git commit, explained from git's own source. 9 of 9 hops traced to code. Open it live →
Why
Diagrams and knowledge graphs show you what exists. When you're new to a codebase, or staring
at a PR an AI wrote, the question is what happens, in what order, and where in the code.
chalk-talk answers that the way a good engineer at a whiteboard would: one thing at a time. The
first box, one sentence, an arrow, a packet moving along it ("JWT", "order #42",
"SELECT"). Earlier parts fade back; the new part is lit. At the end the whole trip replays.
Click any block or arrow and the exact lines open, with a GitHub permalink.
Your agent writes a tiny scene file. The engine does the layout, routing, 3D drawing and
animation, then screenshots every step so the agent checks its own work before you see it.
Every arrow has a receipt
An animated diagram that's wrong is worse than no diagram: it's a more convincing
hallucination. So in chalk-talk an arrow isn't just drawn. It's cited:
{ "from": "router", "to": "layer", "label": "match(path)",
"code": "router/index.js:230-247", "calls": "matchLayer(layer, path)" }
The build opens the file, reads those lines and checks that matchLayer(layer, path) is really
there. Then every arrow gets a mark:
| mark | means |
|---|---|
| ✓ verified | the cited lines exist and contain the call |
| ? inferred | no line to point at (network boundary, dynamic dispatch), with the reason |
| ! broken | the call isn't in those lines. The build warns, the agent fixes it |
$ node scripts/build.mjs express-request.scene.json
proof: 7/9 hops traced to code (7 verified, 0 cited) · 2 inferred · 0 broken
Press V in any talk to see which hops are proven. The recap says it out loud:
"7 of 9 hops traced to code · 2 inferred".

Gallery
Every talk below was written by an agent from the real source, and every arrow is checked.
| talk | repo | proof |
|---|---|---|
| What git commit writes to disk | git/git | 9/9 traced |
| How Codex CLI runs a shell command | openai/codex | 10/10 traced |
| How Vite hot-updates a module | vitejs/vite | 7/8 traced, 1 inferred |
What Redis does with SET greeting hello |
redis/redis | 8/9 traced, 1 inferred |
| How FastAPI calls your function | fastapi/fastapi | 8/9 traced, 1 inferred |
What happens when a request hits app.get() |
expressjs/express | 7/9 traced, 2 inferred |
| PR #7459: chunked responses get their ETag back | expressjs/express | 5/6 traced, 1 inferred |
| How chalk-talk proves every arrow | this repo | 6/7 traced, 1 inferred |
→ / space steps, P plays, V proof view, T light/dark, click a block or arrow for its code.
Frames: explain anything, not just code
The second skill, frames, turns anything you need to explain into a 60–120 second story in
one HTML file: a pitch, a PRD, a strategy memo, an incident review, a lesson, a code walkthrough.
One idea per frame, each drawn with the lens that fits its question (title, moment, flow,number, whatif, compare, screen, timeline), in one calm ink-on-paper style with a
single accent color. It plays by itself when forwarded, presents live (F, notes with N) and
reflows to a phone.
pitch the split-bill feature to my VP as a story
| story | for |
|---|---|
| Ödeyen kişi cezalandırılmasın | product pitch to a VP (Turkish) |
| Your bedtime voice, wherever you are | seed pitch |
| Free forever ends | strategy memo, all hands |
| One config change stopped checkout | incident review |
| Save swaps one module, not the page | code onboarding (Vite HMR, arrows proven) |
| A vaccine is a practice run | lesson |
| İlk haftan | onboarding a new hire (Turkish) |
The agent writes a small story file (SPEC); the engine draws and lays
it out. node skills/frames/scripts/build.mjs story.json validates and builds,check.mjs renders every frame wide and tall to PNG, record.mjs makes a GIF.
Explain a pull request
explain this PR with a chalk talk
The agent reads the diff and tells the journey as it is after the change, with what changed
lit up: NEW, CHANGED, REMOVED, a PR #7459 · +2 ~4 chip, and D to flip between before
and after. Drop the GIF into the PR description and reviewers see the change before they read it.

Install
Claude Code
/plugin marketplace add oztrkemree/chalk-talk
/plugin install chalk-talk@chalk-talk
Codex, Cursor, Gemini CLI, OpenCode, Copilot and 40+ other agents
npx skills add oztrkemree/chalk-talk
By hand: copy skills/chalk-talk (and skills/frames) into your agent's skills folder (~/.claude/skills/, ~/.codex/skills/, ...).
The scripts need Node 18+ (Windows, macOS, Linux). The visual self-check uses any installed
Chrome, Edge, Brave or Chromium.
Use
Just ask, in any language:
how does auth work in this repo?
walk me through what happens when a webhook arrives
explain this PR with a chalk talk
bu kuyruk sistemi nasıl çalışıyor, çizerek anlat
or call it directly: /chalk-talk the checkout flow.
The agent writes chalk-talks/<name>.scene.json, builds chalk-talks/<name>.html, checks every
step as a screenshot and opens it. Keep the scene file: ask for changes ("split step 3", "show
the retry path") and the agent edits it.
| key | does |
|---|---|
→ / space / click |
next step |
← |
previous step |
P |
autoplay (?play=loop in the URL loops) |
V |
proof view: which hops are traced to code |
D |
before / after, in a PR talk |
C / click a block or arrow |
the code behind it |
T |
light ↔ dark |
1–9 |
jump to a step (also #3 in the URL) |
On a phone the board turns portrait and follows the part each step is about.
Share it
A talk is one HTML file: no server, works offline, send it to anyone.CHALK_SHARE=1 leaves your local paths out and keeps the GitHub permalinks.
Need it inline, in a README, a PR or Slack?
node skills/chalk-talk/scripts/record.mjs chalk-talks/auth.html --out auth.gif --style chalk
record.mjs drives your installed Chrome frame by frame (no ffmpeg, no npm packages) and writes
a looping GIF. --steps 2-5, --width 960, --theme dark.
Styles
| iso (default) | little 3D blocks on an isometric floor; servers blink when a packet lands, databases ripple on a write, queues fill and drain |
| chalk | the same board drawn in chalk on a slate: hand-drawn strokes, pastel hatching |
| studio · blueprint · editorial | flat card layouts for bigger systems |
"style": "chalk" in the scene, or ?style=chalk on any talk.
How it works
your question ──▶ agent reads the code ──▶ scene.json ──▶ build.mjs ──▶ talk.html
▲ (proof check) │
└──── check.mjs: report + PNG per step
A scene is plain JSON: nodes on a coarse grid, edges between them (with the code that proves
them), and steps that say what to show, what flows and what to say:
{
"title": "How logging in works",
"nodes": [
{ "id": "web", "kind": "browser", "label": "Web app", "at": [0, 0] },
{ "id": "api", "label": "Auth API", "sub": "POST /login", "icon": "key", "at": [1, 0],
"code": "src/auth/login.ts:12-40" }
],
"edges": [
{ "id": "req", "from": "web", "to": "api", "label": "POST /login", "packet": "email, pw",
"code": "src/web/login.tsx:31-38", "calls": "fetch('/login'" }
],
"steps": [
{ "title": "The request", "say": "The web app sends both to the **Auth API**.", "show": ["req"], "flow": ["req"] }
]
}
The engine (one HTML template, no dependencies) projects the grid onto an isometric floor, draws
each node as a 3D object, routes paths around blocks, places labels where they cover nothing,
and reports what it couldn't fix (arrow api -> db runs through cache) so the agent changes the
scene. Nine kinds of blocks, 37 icons, a sequence layout for handshakes and OAuth, five styles.
Everything is in the scene reference.
Build a talk by hand, no agent needed:
node skills/chalk-talk/scripts/build.mjs my-talk.scene.json # writes my-talk.html, checks proof
node skills/chalk-talk/scripts/check.mjs my-talk.html # layout report + a PNG per step
FAQ
Can it still be wrong? Yes: an agent can pick the wrong story or oversimplify. What it can't
do silently is draw an arrow that claims a call that isn't in the code: that's a ! and a build
warning. The ? marks show you exactly where the talk relies on judgment, not a line.
Is my code sent anywhere? No. chalk-talk is a skill your agent runs locally. The page is a
file on your disk; nothing is uploaded.
Big repos? One journey per talk, about 8 blocks. Ask for the next journey and you get the
next talk. Small focused talks beat one unreadable map.
Credits
- Fonts: Geist by Vercel, IBM Plex by IBM,
Inter Tight, Newsreader,
Caveat and
Patrick Hand, all under the SIL Open Font
License, loaded from Google Fonts and not bundled. - The step-through idea owes a lot to Nicky Case's explorable explanations and Julia Evans' zines.
License
MIT. Use it, fork it, ship it. If it helped you understand something, a ⭐ helps others find it.
Yorumlar (0)
Yorum birakmak icin giris yap.
Yorum birakSonuc bulunamadi