CoT Reasoning Map

See your agent think, live. A local companion for Claude Code that draws the chain of thought as it happens: a real-time reasoning map of typed moves — framing, hypothesis, verification, backtrack, self-correction, insight, action, conclusion — laid out as a graph with dependency and discard edges, an effort timeline, and click-through to the verbatim thinking excerpts.

Start it once, keep the tab open, and every Claude Code session on your machine becomes watchable — no configuration inside Claude Code, no API key required.

Live mode (the product)

npm run live

Open http://localhost:4173. A file watcher on ~/.claude/projects tracks every recently active session and streams new thinking blocks to the page over SSE. The session strip at the top shows each session with its task, activity dot, and move count — click one to pin it, or stay on ⚡ Auto to always follow the most recently active session. Moves are typed instantly by a cue-based heuristic annotator (src/annotate.js) — zero latency, zero cost. Restrict the watcher to one file with FOLLOW=/path/to/session.jsonl npm run live.

LLM-grade refinement (optional)

Export ANTHROPIC_API_KEY before npm run live and the map upgrades itself: heuristic moves appear instantly, then ~6s after the session goes quiet a Claude Haiku pass re-annotates the full trace with proper move boundaries, dependency edges, and verbatim excerpts (forced structured output, src/llm-annotate.js). The page badge shows heuristic vs ✦ LLM-refined. Without a key everything works as before. Model override: COT_REFINE_MODEL (default claude-haiku-4-5, ~$1/$5 per MTok).

Privacy note: refinement sends thinking text to the Anthropic API under your key.

Related MCP server: Sequential Thinking MVP Server

Install

Requires Node 18+.

git clone https://github.com/matanma12/reasoning-map.git
cd reasoning-map
npm install
npm run live

Inline maps in the chat (MCP App)

The same renderer also ships as an MCP App (SEP-1865) so Claude can draw a reasoning map inline in the conversation — useful for post-hoc analysis of a finished session:

claude mcp add cot-spike --scope user -- node "$(pwd)/server.js"

Restart Claude Code, then say "map the reasoning of my last session". The flow: list_sessions finds transcripts with thinking blocks → get_thinking extracts them → the calling Claude annotates the moves itself (no API key) → show_reasoning_map renders the widget (Claude Code desktop app / claude.ai; text fallback in the CLI).

Under the hood: trace store & patterns

Every watched or rendered trace is saved to ~/.claude/cot-maps/traces/, and a pattern engine (src/patterns.js) tags named reasoning shapes — evidence loop, hypothesis elimination, verify-before-commit, anti-patterns like leap-of-faith. Pattern chips on each map highlight where a shape occurs; "show my reasoning pattern library" renders the cross-trace view; npm run backfill (add --llm for Haiku-grade annotation) seeds the store from your whole session history.

This layer runs silently and costs nothing. It also hedges the product against raw CoT becoming scarcer: typed moves extracted from summaries and tool-call sequences stay meaningful even where verbatim thinking isn't returned.

Development

• live.js — the live server (watcher + SSE on :4173)

• server.js — MCP server (stdio; npm run serve:http for Streamable HTTP on :3001)

• src/map-core.js — shared renderer between the live page and the MCP widget

• npm run build — bundles (auto-runs before npm run live) dist/{mcp-app,live,patterns}.html (vite-plugin-singlefile)

• node test-client.js / node test-refine.js — protocol and refiner tests

Roadmap — live-first

The focus is the live experience: making "watch your agent think" excellent.

1. Multi-session dashboard — shipped: session strip, pin/auto follow

2. Live annotation quality — richer heuristics, incremental (per-turn) LLM refinement

3. Turn/tool context on the map — show which tool calls each reasoning stretch drove

4. Packaging — one-command install (npx / Claude Code plugin), auto-start

5. claude.ai deployment — hosted HTTP mode for non-local use

Deferred, not deleted: the learning direction (predict-the-next-move replay, spaced pattern review). The trace store and pattern engine keep collecting so that door stays open.

MIT licensed.