Agent Think Map

Your agent took 40 steps. Find the one that matters.
A visual debugger for AI agents. Follow tools, skills, MCP calls, and subagents.
Find the run. Inspect the evidence. Get back to building.

Try the canvas demo  ·  Try the new Studio  ·  Contribute

An agent calls a tool, delegates to another agent, hits a permissions error, and keeps going. The final answer is only part of the story. Agent Think Map makes that execution path explorable.

Run Studio beside Claude Code or Codex, or embed the canvas in your own application. Keep your existing agent workflow. Inspect the events it emits.

From “what happened?” to the original evidence

Studio brings live traces, imported history, run comparison, agent handoffs, and recurring problems into one local workspace. Version 0.2.1 includes Claude Code history import, evidence-aware comparison, and the corrected Codex live-capture path.

A workspace that makes room for your trace. Drag the history divider to resize it. Collapse it when you need the canvas. Open History again without losing the trace; narrow screens use a compact drawer. Your sidebar preferences are remembered locally.

For example: open Problems, select a repeated permissions error, inspect its captured input, then open the affected run and follow the agent that made the call. Suggested checks help you investigate; the original trace is there to verify them.

Use npx agent-think-map@latest codex --install or npx agent-think-map@latest claude --install for the latest Studio. The hosted canvas demo is a separate preview of the embeddable viewer.

Try the new Studio

No account or API key needed for the sample preview. Requires Node.js 22.13 or newer.

git clone https://github.com/nimrodfisher/agent-think-map.git
cd agent-think-map
npm ci
npm run build
node node_modules/vite-node/vite-node.mjs scripts/preview-history.ts

Open the local URL printed in your terminal. Explore sample runs, nested agents, repeated errors, and run comparison. This preview uses synthetic data in a temporary database, separate from your real run history. Press Ctrl+C to stop it.

Want a quick look at the published canvas instead?

npx agent-think-map

This replays a recorded turn in your browser. No agent connection required.

Connect your coding agent

Use the published package commands below, or run node /path/to/agent-think-map/bin/cli.mjs in place of npx agent-think-map to use your built source checkout. For Claude Code, run the command from the project where you launch Claude.

Claude Code

npx agent-think-map claude --install

1. Keep Studio running; it opens at http://127.0.0.1:3334.
2. Restart Claude Code if it was already open, then ask it to use a tool.
3. Watch the trace appear as hooks fire.

Installation adds hooks to the current project's .claude/settings.local.json. Install in each project you want to trace. Existing hooks from other tools are preserved.

Codex Desktop and CLI

npx agent-think-map codex --install

1. Keep Studio running; it opens at http://127.0.0.1:3335.
2. Restart Codex Desktop or the CLI to load its hooks. Review or trust the hook command if Codex prompts you.
3. When asked whether to share prompts and tool events with the local map, choose yes, no, or later.

The default install uses ~/.codex/hooks.json and covers future sessions across projects. Use --install --project from a project to scope installation to its .codex/hooks.json. Codex Desktop can run normally; it does not need to start from the Studio terminal.

Choosing yes enables forwarding for current and future sessions. no skips forwarding; later defers the choice for that session. Re-running the user-level install resets the consent prompt.

Useful commands

Replace claude with codex for the Codex integration.

npx agent-think-map claude             # Start without changing hooks
npx agent-think-map claude --no-open   # Keep the browser closed
npx agent-think-map claude --smoke     # Load a sample turn
npx agent-think-map claude --doctor    # Check installed hook transport
npx agent-think-map claude --rollback # Restore a backed-up hook configuration

Use --port <number> to change the port. If Studio is already running on its port, --install updates hooks and exits. Keep that existing Studio process running.

See installation recovery and package development for backup behavior, rollback scope, and diagnostic details.

What the map can show

Inspect available inputs, output previews, errors, timings, token usage, and cost. The timeline lets you scrub through the turn. Parallel tools and subagents retain their branching structure.

The map reflects recorded events. Reasons, usage, and cost depend on what the runtime supplies. Codex lifecycle hooks do not stream chain-of-thought. Agent relationships currently follow captured parents within a run; cross-run agent lineage is future work.

Local history, clear boundaries

Studio stores versioned events in ~/.agent-think-map/runs.db using SQLite. Claude and Codex use the shared local storage implementation. History survives restarts; unfinished sessions become interrupted.

Import existing Claude Code history without setting up hooks:

npx agent-think-map@latest claude --import-history --dry-run
npx agent-think-map@latest claude --import-history
# Optional: --history-root /path/to/claude/projects

For a built source checkout, use an absolute path to bin/cli.mjs in place of npx agent-think-map@latest. The command reads main-session transcripts under ~/.claude/projects, reports created and updated runs, appended and duplicate events, skipped live sessions, and malformed or unreadable input, then exits without starting Studio or changing hooks. Open Studio normally afterward to search, label, bookmark, and compare imported runs. They show an Imported marker and can be selected using Filters → Origin. Dry-run simulates ingestion in memory using a temporary snapshot of existing history; it leaves the target database unchanged, including when no database exists.

Repeat imports add only new transcript events. Sessions already containing live-captured evidence are skipped. If live capture later continues an imported session, its origin becomes Live and further imports skip it; historical overlap is not reconciled. Separate subagent transcript files are excluded, while Task and sidechain relationships recorded in the main transcript are retained. An assistant finishing a turn does not prove the session ended: without explicit session-end evidence, an imported run is shown as interrupted. This indicates incomplete capture, not a failed outcome.

History import is manual and currently supports Claude Code only. Codex supports live capture; retroactive Codex history import is not available.

• No hosted account required. The Studio integrations send trace events to the local server.
• Search recorded context. Search covers indexed prompts, labels, models, operations, previews, and errors; it is not a full-text search of every raw payload.
• Separate execution from outcome. A completed run can still need work. Outcome labels are your judgment.
• Inspect recurring errors. Problem groups match captured operation/error identity. They scan up to the newest 10,000 errors and show up to 20 recent occurrences per group, with a notice when coverage is partial.
• Keep evidence close. Suggested troubleshooting checks are starting points, not verified root causes or automatic fixes.

Trace data can contain prompts and tool content. Review captured data before sharing a screenshot or attaching a trace to an issue.

Compare runs using recorded evidence

Comparison is available in both the Claude Code and Codex Studios, including for imported runs.

1. Mark a useful reference run Worked.
2. Select the run you want to investigate and click Compare…. Search the baseline picker, which defaults to Worked runs. You can choose another outcome after explicit confirmation.
3. Inspect Baseline and Candidate side by side. Both panes show their actual outcomes. Select a row to highlight the corresponding steps in both panes, follow linked scrolling, and inspect the original captured events.
4. Use First detected difference to jump to the first non-matched row. Read its evidence explanation and the comparison warnings before drawing a conclusion.

Compare… always opens the picker. The Compare workspace tab reopens the current comparison, or opens the picker if none exists. Switching workspace tabs retains the comparison; Back to trace restores the saved trace selection and history scroll position and removes the baseline from the URL. Local session/baseline links can reopen a comparison when its runs are still available.

Each row explains whether correspondence is exact or inferred. Exact correspondence requires captured operation identities, equal fingerprints unique within each turn, and finished steps. An exact pair is only classified as matched when its status and output class also agree. Running steps, repeated fingerprints, missing identity, structural identity alone, and differing input shapes can weaken the evidence; inferred pairs never receive high confidence. Warnings report inferred pairs as a share of all paired steps, excluding inserted and missing steps.

Alignment is provisional. Even identical user or answer steps can be inferred differences when operation identity is unavailable, so the first detected difference can point to insufficient evidence. It is an investigative lead, not a proven cause or an automated diagnosis. Original-step inspection shows captured event envelopes, not a reconstructed historical canvas.

For the analyzer V2 API fields and evidence vocabulary, see the diff evidence handoff. The history import handoff and comparison UI handoff record implementation details, boundaries, and validation.

Put the canvas in your own app

Web component

Point events-url at your agent's SSE endpoint:

<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/[email protected]/dist/styles.css" />
<script type="module" src="https://cdn.jsdelivr.net/npm/[email protected]/dist/element.cdn.js"></script>
<agent-think-map events-url="/sse" layout="split"></agent-think-map>

Layouts: split, overlay, or canvas-only. <agent-simulator> remains an alias.

React

npm i agent-think-map

import { AgentSimulator } from "agent-think-map/react";
import "agent-think-map/styles.css";

<AgentSimulator events={events} layout="split">
  <YourChat />
</AgentSimulator>

Pass an array or async iterator as events, or use eventsUrl="/sse".

Bring your runtime

TraceAdapter accepts supported Claude Agent SDK, OpenAI Agents SDK, and Codex app-server events:

import { TraceAdapter } from "agent-think-map";

const adapter = new TraceAdapter({ runId, prompt });
for (const event of adapter.ingest(nativeEvent)) {
  push(event);
}

For another runtime, emit the shared event protocol. For example:

{
  "type": "node.started",
  "id": "call-1",
  "kind": "mcp",
  "title": "github / create_issue",
  "reason": "Called create_issue on server github",
  "ts": 1710000000000
}

The protocol includes run.started, run.meta, node.started, node.delta, tool.input, node.completed, node.failed, and run.completed. Send frames as SSE data: messages. See the event schema and sample traces.

Using NanoClaw? Start with the runner integration and removal instructions.

Make it better with us

Open source. MIT licensed. Built for people building with agents.

The next useful feature might come from the trace that confused you today. You can help without writing an adapter:

• Try a real workflow. Tell us where you lost the thread, which step you could not find, or what the inspector was missing.
• Report a reproducible bug. Include your OS, Node version, agent integration, expected behavior, and a sanitized screenshot or small fixture.
• Improve the experience. Keyboard navigation, responsive layouts, clearer errors, and documentation all matter.
• Connect another runtime. Map its events to the shared protocol so it can use the same canvas.

Open an issue · Read the contribution guide · Explore the UX roadmap

If the map helps you explain an agent failure, share a short recording and link back to the repo. Star the project if you want to help more agent builders find it.

Develop locally

After cloning and installing dependencies:

npm run dev       # Demo app with development tooling
npm test          # Test suite
npm run build     # ESM library, declarations, and CDN assets

Use the Studio preview to work on run history and troubleshooting. See package development for package-consumer checks.