v0.6.0

This release combines the 0.5 recovery/search and 0.6 usage milestones. There is no separate 0.5.0 release.

Highlights

• Bounded, redacted historical recovery evidence with explicit continue/fork cutoffs, source attribution, recorded compaction summaries and omission notices. Current Git context is not historical file restoration.
• Search across archived Codex sessions and Claude Code/Codex child transcripts, with exact file selectors and uniquely proven parent-step links.
• Separate Codex descendant usage, evidenced inherited-call deduplication, explicit unattributed children, and descendant-aware MCP cache invalidation.
• Opt-in session-catalog token totals through --sessions --usage and MCP agent_tree_sessions({usage:true}). Default catalogs stay metadata-only; missing data remains distinct from zero.
• Hardened descriptor ownership, filesystem failure isolation, native-path validation and macOS filesystem-alias handling.

Verification

Linux and macOS CI passed with Node 22, 24 and 26, including tests, both TypeScript checks, lint, build, release consistency, installed-tarball CLI/MCP smoke and dependency audit. The attached tarball also passed the complete server prepublish checks and installed-package smoke.

Install or upgrade from npm:

npm install -g @seungwoolee/agent-tree@latest
agent-tree --version

The npm latest tag is 0.6.0. The registry tarball matches the attached, checksum-verified package. Fresh registry installation and CLI/MCP behavior were verified after publication. The attached package can also be installed directly with npm install -g ./seungwoolee-agent-tree-0.6.0.tgz after download.

SHA256: 1549b7f0e77b450ab16fcbb67649d213664b8a666903550b6fd9724011421cc2

Full changelog

v0.4.0

Fixed

• Output written to a pipe could be cut short. The CLI exited before an
  asynchronous pipe drained, so agent-tree --json | jq or a large
  --sessions --json catalog could receive only the first 64 KiB, or
  another multiple of it (65536 of 378774 bytes in one export measured on
  macOS; Linux showed the same for larger exports). The CLI now waits for
  stdout and stderr to flush. A stdout reader that stops early (| head)
  ends it with status 0 instead of an EPIPE error, and a closed stderr only
  drops diagnostics instead of ending the export.

Added

• Search across sessions. --search <text> and the MCP tool
  agent_tree_search find the session and the numbered step where a text
  appears in prompts, replies and tool inputs (tool results with
  --include-tool-output), newest session first, with redacted snippets.
  Every project and both agents by default; --cwd, --source,
  --since <days> and --limit narrow it, and --json prints the results.
  A raw-byte prefilter keeps a scan of every local session fast (19.9 GiB in
  about 15 s on one machine). Matching runs on redacted text, so a search
  can neither find nor confirm a secret. MCP replies are capped near 20 KB.
  The MCP server now has seven tools.
• Token usage per step. Every mindmap node carries usage whenever the
  session logged it: calls, prompt tokens with cache reads and writes,
  output and reasoning tokens, the largest context, the model's window for
  Codex, compactions, and subagent usage reported beside the main numbers.
  --usage adds these columns to the text tree, and agent_tree_list
  accepts usage: true. Claude Code writes one response as several records
  with the same usage, so each response counts once. Codex usage comes from
  token_usage_record where present, otherwise from token_count. Claude
  Code subagent transcripts count toward the step that started them.
• Open a session from any step. --open <step>, with --mode,
  --agent claude|codex and --open-dir, starts the agent with the
  continue or fork prompt in the step's directory, without a shell, and
  exits with the agent's status. For a --file session it first shows the
  directory and the instruction and waits for Enter; --yes skips that. It
  refuses without a terminal, inside an agent session (CLAUDECODE=1) and
  for prompts over 100,000 bytes, and exits 127 when the agent is not on
  PATH. No MCP tool starts an agent; agent_tree_snapshot and the
  interactive --snapshot suggest the --open command instead.
• agent-tree --help ends with the project's GitHub link.
• After the first successful resume from the interactive tree, the CLI
  prints a short note asking for a GitHub star, once per machine. It goes to
  stderr only and stays silent for piped output, CI, Claude Code, --json
  and --dump-json; AGENT_TREE_NO_STAR_HINT=1 turns it off. A marker under
  ~/.cache/agent-tree/ records that it was shown. The MCP server never
  prints it.

Known limits

• Search reads main transcripts only: not Claude Code subagent transcripts
  or Codex sessions archived under ~/.codex/session_archives/. Case
  folding covers ASCII letters only. Search skips its own agent-tree --search commands and agent_tree_search calls, but other text that
  quotes the query still matches.
• Claude Code logs no context window, so Claude rows show context size
  without a limit. Codex subagent sessions are not counted toward a step.
• --open runs on macOS and Linux, and its prompt is a command-line
  argument that other local users can see in ps.

Changed

• --cwd naming a missing directory exits 2, like other usage errors,
  instead of 1.
• The Claude Code reader no longer warns on stderr about a missing
  permission-mode line; current Claude Code omits it in many valid sessions
  (122 of the newest 300 on one machine). --verbose still shows it.

Docs

• The README covers search, token usage and --open, ticks the 0.4 roadmap
  items and adds the next ones; every list of MCP tools now has seven.
• The README is reorganized around the supported agents, features, a
  first-class "For AI agents" section (identity, isolated install and
  self-test, MCP wiring for any client, tools, recipes and rules) and a new
  roadmap: search across sessions, token usage per step, and opening a
  session from any step. The npm page now shows 0.2.1 and 0.3.0 as published
  instead of "publication pending".
• RELEASING.md records the npm web 2FA path for scripted publishes, that a
  prebuilt-tarball publish skips prepublishOnly, and that a new tarball can
  return 404 for minutes after npm view lists the version.
• RELEASING.md notes that an npm login lasts two hours, so the login and
  the publish approvals belong in one sitting, and that web login works
  without a TTY. CONTRIBUTING.md warns that building from a worktree whose
  node_modules is a symlink embeds the other checkout's paths in dist/.

v0.3.0

Added

• A session-source interface separating discovery and log normalization from
  analysis, rendering, configuration, and MCP transport.
• Codex rollout support via CLI --source codex and MCP source: "codex".
  CODEX_HOME controls discovery, project filtering uses metadata cwd, and
  portable --file imports detect Claude Code or Codex automatically.
• Codex message/tool normalization, apply-patch file paths, public reasoning
  summaries, compaction markers, duplicate-notification suppression, and
  deterministic event identities. Thread IDs remain distinct from root
  session IDs. Discovery excludes subagent sessions and symlink entries.
• Source identity in JSON mindmaps and catalogs; source-preserving CLI
  snapshot hints and optional source filters for pick history.
• Synthetic adapter, CLI, MCP, and installed-tarball regressions for both
  sources. No private rollout fixtures are distributed.

Fixed

• Tool and file labels redact credentials before truncation, preventing
  partial tokens from surviving shorter heuristic labels.
• Interactive picker and discovery fallback messages apply output redaction.

Breaking

• Pick history is now stored at
  ~/.cache/agent-tree/picks/<source>/<session-id>.jsonl. Flat-directory
  history is neither read nor migrated; Claude and Codex UUIDs cannot share
  or remove one another's stars.
• Nonempty unrecognized imports require an explicit source instead of
  silently producing an empty Claude tree.

This release also includes the 0.2.1 changes.

v0.2.1

Toolchain and release verification

• TypeScript 7.0.2 is the default native type checker and watch compiler.
  TypeScript 6.0.3 remains the JavaScript compiler API for typescript-eslint;
  both compilers are invoked by explicit paths to avoid npm bin collisions.
• verbatimModuleSyntax enforces explicit type-only imports in ESM code.
• Release checks keep the package, lockfile, plugin, marketplace, skill,
  and bundled versions aligned. CI rejects stale committed bundles and
  exercises CLI and MCP from an independently installed local tarball.
• Updated the MCP SDK's transitive Hono dependency to 4.13.13.
• Package, plugin, marketplace, and skill versions advance to 0.2.1.

Added

• Portable Claude Code JSONL imports via CLI --file and MCP file, project
  selection/configuration via --cwd, and parse-free session catalogs via
  --sessions [--limit N] and the sixth MCP tool, agent_tree_sessions.
• Complete redacted JSON mindmaps/catalogs (--json, MCP list
  format: "json") without stdout banners, and CLI --strict malformed-line
  rejection. Incompatible selectors, modes, and flags fail with exit code 2.
• CLAUDE_CONFIG_DIR discovery support; project paths encode every
  non-ASCII-alphanumeric character as -. Exports without a valid session
  UUID use a stable path-derived 32-hex identity for local pick history.

Changed

• Config precedence is defaults < user < project < environment < explicit
  CLI. Per-field validation warns without discarding valid sibling settings.
  MCP analysis caches invalidate on caller config and file identity metadata.
• LLM model, input/output limits, parallelism, prompt caching, and language
  settings are honored. Exact messages.countTokens preflight reservations
  precede paid calls; failed counts make no paid labeling call, and failed
  requests do not refund reservations. The input budget is not a spending cap.
• CLI and MCP share the package version source. ESLint 10 flat config and
  Vitest 5 modernize the toolchain. TypeScript 7 performs type checks, while
  TypeScript 6 supplies the compiler API for typescript-eslint.
• Docs and skill schemas now describe six tools and Claude Code-only input;
  Codex/Gemini native session adapters remain unimplemented.
• README rewritten around a terminal demo (docs/demo.svg, rendered from
  real CLI output), a quick start, what's new in 0.2, the Claude Code plugin
  and a roadmap, with reference material in collapsible sections and verified
  install paths for the development version and the plugin. The marketplace
  command is claude plugin marketplace add lifrary/agent-tree; current
  Claude Code rejects the previously documented github: prefix.

Fixed

• Phase-only text rendering preserves canonical node numbers for subsequent
  snapshot selection. Hidden children no longer renumber later phases.
• Dropping sidechains preserves original source-event ranges and keeps
  dropped events out of the selected tree's metadata and snapshots.
• --dry-run skips dump/cache writes and pick changes while retaining
  analysis; use --no-llm as well to avoid paid labeling.
• TUI selection shares the --snapshot path for git context, redaction,
  pick history, and clipboard behavior, and honors text display options.
• --redact-dryrun reports per-pattern hit counts from parsed source
  strings on stderr without exposing matched values.
• UUIDless Claude Code metadata lines of any non-event type (custom-title,
  agent-name, mode, atis-latch, ai-title, file-history-delta, …)
  are skipped as metadata, and structured attachment content (hook context
  lists, file and memory objects) is dropped without a malformed warning.
  Previously a real 14.7 MB session printed 1,592 multi-line warnings and
  --strict rejected all 150 recent real transcripts tested.
• /pre-publish-audit reads npm pack --json from npm 12, which prints an
  object keyed by package name instead of an array; its tarball check
  previously failed with "Cannot index object with number".

Security

• Discovery accepts only UUID-named regular session files, excluding
  agent/subagent and symlink entries. JSON exports/catalogs and errors retain
  redaction at output boundaries.
• Security redaction cannot be disabled. Config accepts only the implemented
  anthropic provider and telemetry.enabled: false.

Breaking

• Node.js ≥22.13.0 is required. CI covers Node 22/24/26 on Linux and macOS.
• Per-session MCP tools accept sessionId or file, never both;
  agent_tree_picks takes {} only. JSON exports reject display filters.
  Invalid config fields and unsupported settings now warn instead of being
  silently accepted.

Docs: README jargon + redact-strict accuracy pass (2026-04-29)

Follow-up audit on the README rewrite that landed three days ago. Three
load-bearing claims were either reader-hostile or factually wrong:

• /wrap reference removed. The opening tagline framed agent-tree
  against "linear /wrap summaries", but /wrap is a third-party plugin
  command (session-wrap:wrap) — readers without that plugin installed
  see a comparison they can't parse. Rephrased to "linear end-of-session
  summaries". skills/agent-tree/SKILL.md had the same trap in two
  places (like /wrap or /ooo, Generating a /wrap summary); both
  rewritten in tool-agnostic language.
• One-shot npx install command was broken. README's "Install"
  section opened with npx -y @seungwoolee/agent-tree --list, which the
  same README's "Why not bare npx?" section explicitly says doesn't
  work — the package ships two bins (agent-tree, atree) so npx 10+
  can't auto-resolve, and --list gets eaten as a positional. Replaced
  with the isolated /tmp/atree install pattern that /mcp-smoke
  already uses (regression-tested every release).
• --redact-strict "adds card" was a documentation-vs-code split.
  The README, the CLI --help, the redact.ts header comment, and the
  SKILL.md privacy section all claimed --redact-strict adds 5 PII
  patterns including card. In reality redactCreditCards() is called
  unconditionally inside apply() (default-on for everyone), and
  STRICT_EXTRA defines 5 regex entries covering 4 PII categories —
  email, ssn_us, rrn_ko, plus phone split into two regexes
  (phone_e164 + phone) for ReDoS safety. Fixed to "16 named secret
  patterns + always-on Luhn-validated card check; --redact-strict adds
  4 more PII patterns (email/phone/SSN/RRN)" everywhere. Behavior
  unchanged — this was purely a doc/help-text drift.

Also tightened a few smaller items: --diff <a> <b> table notation →
<from> <to> (more readable than commander's variadic <ids...>),
version 0.1.2 (as of 2026-04) in the For-agents identity block →
(npm badge above shows latest) so the README doesn't go stale on
release day, and dist/*.js ships in git too — optional for Option A
comment placement clarified to apply to both install options
(dist/ is committed, so npm run build is only needed after editing
src/).

dist/ rebuilt to ship the new --help text in the next release. Tests
still 134 / 12 (no behavioral changes).

Docs: README rewrite + agent-friendly surface (2026-04-26)

Rewrote README.md for v0.1.2 accuracy and added a top-level
"For agents (LLMs handed this URL)" section. Modern agentic workflows
often hand a repo URL to an LLM with no other context; the new section
provides:

• Identity block (package / repo / version / runtime / data source)
• One-shot self-test sequence (isolated /tmp install + --version /
  --help / --list); see "self-test npx form" note below for why
  bare npx is unreliable here
• MCP tool schemas — zod-derived JSON, copy-paste-ready
• Common task recipes ("user says X → call Y")
• Constraints + failure modes (no ~/.claude/projects/ data, in-progress
  sessions, ambiguous prefix, LLM cost, redaction, MCP path resolution
  per marketplace type)
• Pointer table to CHANGELOG / SKILL.md / src/mcp/server.ts /
  src/cli/options.ts / RELEASING.md / CONTRIBUTING.md

Also refreshed stale references across the doc set:

• README test count 113 / 12 → 134 / 12 and pattern count
  10 default → 16 default (5 strict). Original "10 default" was a much
  earlier number; the v0.1.2 audit added several token classes (slack,
  github_pat_finegrained, openai_project_key, stripe, huggingface, npm,
  gcp_oauth, aws_temp). The v0.1.2 CHANGELOG line "all 14 DEFAULT_PATTERNS"
  was itself stale — direct count of name: entries between
  DEFAULT_PATTERNS and STRICT_EXTRA in src/utils/redact.ts is 16
• README self-test npx form. Earlier draft used
  npx -y @seungwoolee/agent-tree --version which silently fell back
  to npx's own --version (returning the npm version 10.9.4, not the
  package). Multi-bin packages (agent-tree + atree) need the
  explicit bin name: npx -y @seungwoolee/agent-tree agent-tree --version
  works for --version/--help (commander short-circuits), but breaks
  --list because npx passes the bin name through as an arg →
  commander reads it as [session-id]. Final form is an isolated
  /tmp/atree-probe install (same pattern /mcp-smoke uses, so it's
  regression-tested every release).
• skills/agent-tree/SKILL.md install fallback. The same multi-bin
  npx trap bit this file's command not found recovery line —
  npx -y @seungwoolee/agent-tree … was offered as a one-shot
  alternative to npm i -g. Removed the npx option; npm i -g is
  the only suggestion now, with an inline note pointing Claude Code
  at the README "Why not bare npx?" explanation so the reflex
  doesn't reintroduce it.
• README plugin-cache verification path 0.1.0 → version-agnostic glob
  * so future bumps don't immediately re-stale the troubleshooting steps
• README MCP smoke example now points to the bundled /mcp-smoke slash
  command instead of an inline tools/list echo (which lacked the
  spec-requ...

v0.1.2

Release v0.1.2

v0.1.1

Release v0.1.1

v0.1.0 — initial public release

First public release of agent-tree — navigate any Claude Code session as a numbered file-tree in your terminal, and resume from any node.

Install

npm install -g @seungwoolee/agent-tree

Or as a Claude Code plugin (recommended — surfaces 5 MCP tools in every session):

git clone https://github.com/lifrary/agent-tree ~/.claude/plugins/local/agent-tree
cd ~/.claude/plugins/local/agent-tree && npm install && npm run build

Highlights

• Terminal-only file-tree: phases (user prompts) → sub-actions, with phase metadata (N actions · M files · T min). No browser, no HTML.
• Smart default: agent-tree with no args picks up the latest session of the current project; falls back to globally latest.
• ⭐ pick history: previously resumed-from nodes are starred (GitHub-style binary). Persisted at ~/.cache/agent-tree/picks/.
• Continue / Fork resume: pick a node, get the resume markdown on stdout (and clipboard on TTY) ready to paste into a new session. Snapshots auto-include git context (branch / HEAD / status / recent commits).
• MCP plugin: 5 tools (agent_tree_list / snapshot / picks / diff / unstar) surface in any Claude Code session natively, no subprocess spawn.
• Secret redaction: 15 default patterns (Anthropic / OpenAI / GitHub classic + fine-grained PAT / AWS / GCP API + OAuth / Stripe / HuggingFace / JWT / PEM / Bearer); --redact-strict adds email / phone / card / SSN / RRN.

Quality bar at release

• 113 tests across 12 files (lint + typecheck + test + build all clean)
• Comprehensive security audit: 39 fixes including the redactor pipeline, MCP tool routing, path-traversal mitigation (CVE-2022-24765 class), --dump-json hardening
• End-to-end install verification: fresh npm i @seungwoolee/agent-tree → CLI + MCP both functional

See CHANGELOG.md "Post-rebrand audit hardening" for the full list.

Multi-agent intent

Project is named agent-tree (not claude-tree) so v0.2 can add Codex / Gemini session adapters when those formats stabilize.

---

Built with Claude Code itself — this very session was the first to dogfood the tool against its own JSONL.