agent-tree

agent-tree

Navigate any Claude Code session as a numbered file-tree in your terminal — and resume from any node.

A finished Claude Code session can run thousands of turns across hours of work. Linear end-of-session summaries flatten that into prose and lose the branches, dead-ends, and good-but-discarded ideas. agent-tree parses the session JSONL into a tree-style hierarchy you read directly in your terminal: each user-prompt is a phase, each segment underneath is a sub-action, and any node you've previously resumed from is marked with ⭐. Pick a number, and the resume markdown lands on your clipboard ready to paste into a fresh claude session.

Built for Claude Code today. Designed to extend to Codex / Gemini sessions tomorrow — hence the agent-neutral name.

If an LLM agent landed on this README from a bare repo URL, jump to For agents (LLMs handed this URL) for an identity block, self-test sequence, MCP tool schemas, and common task recipes.

What it looks like

agent-tree · session fd8b7e83 · 8602 events · 1916 turns · 210 nodes · 2707 min

 1. 🎯 Build agent-tree per SPEC.md v0.3                                        (root)
 2. ├─ "Read SPEC.md — self-contained spec v0.3 …"   (23 actions · 21 files · 19min) T0      events 0–40
 3. ├─ "Implement milestones M1 through M5 end-to-end"  (24 actions · 19 files · 14min) T+1h 8m   events 1362–1494
 4. ├─ ⭐ "Must run strictly inside the terminal"        (15 actions · 15 files · 12min) T+23h 43m events 5885–5918
 5. ├─ "Layout is secondary — think file-tree hierarchy"  (1 action · 1 file · 3min)    T+24h 44m events 6583–6587
 6. └─ ⭐ "Polish the output carefully"                   (9 actions · 9 files · 4min)  T+43h 17m events 7077–7144

Pick a number to copy that node's resume context.
  N        → continue mode (preserve decisions, change direction)
  N fork   → fork mode (discard subsequent turns)
  N c / N f → shorthand

Phase headers are cyan on TTY, ⭐ marks are yellow, T+1h 8m / events 0–40 are dimmed. --phases-only collapses sub-actions for fast navigation; default view expands them.

Install

Try without installing globally

mkdir -p /tmp/atree && cd /tmp/atree
npm init -y >/dev/null && npm install @seungwoolee/agent-tree
./node_modules/.bin/agent-tree --list

A bare npx -y @seungwoolee/agent-tree … form does not work — the package ships two bins (agent-tree, atree) so npx 10+ can't auto-resolve from the package name alone. The isolated-install pattern above is what the bundled /mcp-smoke slash command uses, so it's regression-tested every release. See Why not bare npx? below for the full trap.

As a global CLI

npm install -g @seungwoolee/agent-tree

Two bins are exposed: agent-tree (primary) and atree (alias).

As a Claude Code plugin (recommended for in-session use)

The plugin manifest ships an MCP server so the tools surface natively in every Claude Code session — no subprocess spawn, no --no-llm juggling.

~/.claude/plugins/local/ is not auto-scanned, so a plain git clone there will not register the plugin. The canonical registration path uses Claude Code's plugin CLI:

# Option A — directly from GitHub (recommended)
claude plugin marketplace add github:lifrary/agent-tree
claude plugin install agent-tree@agent-tree

# Option B — from a local clone (contributors / live dev)
git clone https://github.com/lifrary/agent-tree
cd agent-tree
npm install && npm run build     # optional — dist/ is committed; rebuild only after editing src/
claude plugin marketplace add "$PWD"
claude plugin install agent-tree@agent-tree

Restart Claude Code. The plugin loader only spawns MCP servers at session start, so changes to installed_plugins.json need a restart to take effect.

After restart, /mcp should list agent-tree with status connected and 5 tools beneath it. Or invoke the tool directly in chat:

> Use agent_tree_list with cwd="/path/to/any/project"

Claude Code calls the tool and returns a numbered file-tree of that project's most-recent session.

Troubleshooting the install

If the tools don't surface: