GET STARTED
TreeTrace runs in any repo after an AI coding session. It reads local transcripts, writes a structured record, and never touches the network. Node.js 18 or newer, zero runtime dependencies, no accounts.
cd your-project && npx treetrace
Install
There is nothing to install globally. TreeTrace ships with no runtime dependencies, so npx treetrace needs nothing else on your machine. No accounts, no uploads, no telemetry. Your transcripts never leave your machine.
Run it with npx
From inside the project you want to trace:
cd your-project
npx treetraceNode 18+ required. Claude Code sessions are discovered automatically from your local history. Other tools (Codex, Cursor, Copilot, Gemini, Grok, ChatGPT export, or a plain transcript) import with --file and an optional --from.
Or run it in CI with the GitHub Action
To regenerate the report in a pull request from a committed transcript or a committed .treetrace/tree.json, add the action to a workflow. See the GitHub Action below for the full YAML.
Quickstart
Trace your last session, then read it in your terminal. The same run writes the machine-readable artifacts into .treetrace/.
1. Trace the current project
Writes TREETRACE_REPORT.md, PROMPT_TREE.md, and the .treetrace/*.json lineage from your local Claude Code history.
npx treetrace2. Print the human report in the terminal
Good for a Codex CLI, Claude Code, or SSH session where you want the report in the window. --redact-auto redacts every detected secret without prompting, which is what you want outside an interactive shell.
npx treetrace --report --redact-auto3. Import another tool's session
Pass a .json or .jsonl file and the format is auto-detected; force it with --from. A pasted User: / Assistant: transcript works on --stdin.
npx treetrace --from chatgpt --file conversations.json
npx treetrace --stdin < chat.txt4. Hand the next agent its lessons
Start a read-only MCP server over stdio, or print a continuation brief to stdout for the next session.
npx treetrace --handoff
npx treetrace mcpCLI command reference
Every command runs locally and passes the same redaction gate before anything is written or printed. The graph modes (--graph, --full, --summary) return early and do not compose with --report; run the graph as its own invocation.
| Command | What it does |
|---|---|
| Core | |
npx treetrace | Trace this project and write all artifacts. |
npx treetrace --report | Write all artifacts and print the human report. |
npx treetrace --handoff | Print an agent-ready continuation brief. |
npx treetrace --security | Print a security-focused report and write .treetrace/hallucinations.json. |
| Import sources | |
npx treetrace --file session.jsonl | Import specific session or transcript files (format auto-detected). |
npx treetrace --from chatgpt --file conversations.json | Import another tool's export with an explicit format. |
npx treetrace --stdin < chat.txt | Parse a pasted User: / Assistant: transcript. |
npx treetrace --since 2026-06-01 | Limit to sessions on or after a date. |
| Targeted artifacts | |
npx treetrace --failures | Write and print .treetrace/failures.json. |
npx treetrace --rejections | Write and print .treetrace/rejections.json. |
npx treetrace --lessons | Write and print .treetrace/lessons.md. |
npx treetrace --evals | Write and print .treetrace/evals.jsonl. |
npx treetrace --memory | Write and print .treetrace/agent-memory.md. |
| Graph & output modes | |
npx treetrace --graph | Write PROMPT_TREE_GRAPH.md, a branded Mermaid graph that renders free on GitHub; large projects auto-summarize. |
npx treetrace --titles-only | Compact human tree, no full prompt details. |
npx treetrace --each | Write one full report bundle per session into --out-dir (default treetrace-reports/), with INDEX.md and index.json. |
npx treetrace --deterministic | Pin the generation timestamp so re-running on the same session is byte-identical. |
| Privacy & integration | |
npx treetrace --redact-auto | Redact every detected secret without prompting (used automatically outside a TTY). |
npx treetrace mcp | Start a read-only Model Context Protocol server over stdio. |
Tip. For both terminal output and a shell-captured copy, pipe it: npx treetrace --report --redact-auto | tee treetrace-output.md.
GitHub Action
TreeTrace ships a composite action. Session logs live on dev machines, not in CI, so the typical use is regenerating the report in a pull request from a committed transcript or a committed .treetrace/tree.json, and optionally posting it as a PR comment.
Inputs
| Input | Default | Description |
|---|---|---|
source | '' | Path to a committed transcript file (.jsonl or plain text). When set, it runs treetrace --file on it. |
comment-pr | 'false' | Post the tree summary as a PR comment. Requires GITHUB_TOKEN. |
Workflow example
Add this to .github/workflows/treetrace.yml:
name: TreeTrace
on:
pull_request:
permissions:
contents: read
pull-requests: write
jobs:
treetrace:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: actions/setup-node@v4
with:
node-version: '20'
- uses: TreeTraceTool/TreeTrace@v1
with:
source: .treetrace/session.jsonl
comment-pr: 'true'No source? If source is empty, the action uses a committed .treetrace/tree.json when present; commit TREETRACE_REPORT.md and PROMPT_TREE.md alongside it so the report renders. With nothing to read, the step is a no-op.
Config
TreeTrace is configured entirely by flags. There is no config file and nothing to set up. The defaults are local-first and fail-closed.
Where it reads from
- Claude Code sessions are discovered automatically from
~/.claude/projects/…, no flags needed. - Other tools import with
--file(format auto-detected) or are forced with--from <tool>:codex,chatgpt,cursor,copilot,gemini,grok,transcript. - Pasted text is read on
--stdinas aUser:/Assistant:transcript. - Date filter:
--since YYYY-MM-DDlimits to sessions on or after a date.
What it writes
TREETRACE_REPORT.mdCombined human-readable report for review and chat handoff.PROMPT_TREE.mdHuman-readable narrative of the build path..treetrace/tree.jsonCanonical machine-readable lineage (v0.3 schema)..treetrace/lessons.mdHuman-readable lessons for future work..treetrace/evals.jsonlGeneric, model-agnostic eval cases..treetrace/agent-memory.mdCompact memory pack for the next agent.Privacy & determinism
- Redaction gate. Every export is shadow-scanned before write. In a TTY each unique hit is reviewed interactively; outside a TTY redaction is automatic, or force it with
--redact-auto. - Reproducible output.
--deterministicpins the generation timestamp so re-running on the same session produces byte-identical artifacts. - Per-session bundles.
--eachwrites one bundle per session into--out-dir(defaulttreetrace-reports/), each auto-redacted and failing closed. - Zero network, zero deps. No accounts, no uploads, no telemetry. Node.js 18+ is the only requirement.