TreeTrace
GitHub Get started
Use cases

WHERE
TREETRACE
EARNS ITS KEEP

One local record. Put to work in plain, concrete ways.

TreeTrace writes one redacted, deterministic lineage after a coding or CLI agent session. The same record answers a different question for security, evals, onboarding, audit, postmortems, and the engineer steering the agent, and none of it ever leaves your machine.

Get started See what it records
SESSION LINEAGE · session_01H9F2K ONE RECORD
$ npx treetrace --report
● root prompt "add JWT refresh to auth middleware"
│ ⚠ secret console.log token REDACTED hash:9f3a…
│ ✗ dead-end abandoned · wrong tool choice
│ └─ fix lesson never log raw tokens ✓ eval
● head outcome 6 steps · 2 dead-ends · 1 caught
Concrete jobs

Real scenarios, plainly worded.

Each one runs on the same local trace, with no upload, no telemetry, no LLM judge. Most are shipping today; the audit story is honestly a foundation still being built.

Security

Catch a leak before it ships

Mid-session an agent logs a live key: console.log("token:", t). The branch gets abandoned, but the secret is already sitting in the transcript.

  • Curated rules for AWS, GitHub, Anthropic, OpenAI, Stripe, npm, JWTs and more flag it, with a high-entropy fallback for unknown shapes.
  • Every export fails closed: the secret is redacted and a shadow scan re-checks the rendered file before anything is written.
  • redactions.json stores only a content hash, never the raw value.
See how it works
Evals

Turn a fix into a regression eval

You corrected the agent once: "read the secret from env, don't hardcode it." A week later, a fresh session makes the exact same mistake.

  • Real corrections export to .treetrace/evals.jsonl as model-agnostic eval cases, with no LLM judge deciding what counts.
  • The format is built to drop into promptfoo, OpenAI Evals-style harnesses, and LangSmith-style datasets.
  • Every dead-end and refusal becomes a candidate check the next run has to pass.
See the data model
Training

Show new devs how it actually went

Someone joins and inherits a feature. All they can see is the final diff, none of the wrong turns and corrections that actually shaped it.

  • PROMPT_TREE.md narrates the real build path: the goal, every steer, the corrections that stuck, the branches that were abandoned.
  • A handoff memory pack plus a read-only treetrace mcp server hand the next person (or agent) the lessons.
  • Hand off what went wrong, so they start already knowing it.
See the data model
GRC & audit

Evidence you can stand behind

Governance needs to show what an automated agent touched, including auth, secrets, access control, and a skipped test, and where a human pushed back on it.

  • Flags every touch of auth, a secret, access control, a skipped test, or an unsafe shell command.
  • Each signal carries a confidence score, the evidence text, and the node where it happened, built from deterministic rules, not recollection.
  • Redaction-gated before write, and the v0.3 schema maps cleanly onto W3C PROV for provenance tooling.
Foundation being built
Incident review

Reconstruct what the agent did

A change broke production and nobody remembers how the agent got there. The diff is on the screen; the reasoning that led to it is gone.

  • Rebuilds the fork-aware lineage from local transcripts: root goal, every steer, and the path that actually shipped.
  • Reference checks flag files, imports, and packages the agent named that don't resolve against the real working tree.
  • Typed failure signals (wrong_tool_choice, repeated_failed_fix, scope_drift) point straight at where it went wrong.
See how it works
Prompting

See steered vs dead-end paths

You want to prompt better, but the session is gone and you can't tell which of your steers actually moved the work forward and which went nowhere.

  • Separates the accepted spine that shipped from every branch you walked away from.
  • Surfaces the constraint the agent kept ignoring, so you can put it up front next time.
  • Dead-ends are kept, not erased. The rework is the lesson.
See how it works
Handoff

Hand off with the whole story

End of the day, half a task done, and you're passing it to a teammate or to the next agent. A one-line "here's where I left it" loses everything that mattered.

  • treetrace --handoff prints an agent-ready continuation brief to stdout.
  • agent-memory.md carries the accepted constraints and the corrections that stuck.
  • The next session starts from real lineage, not a cold prompt.
See the data model
Efficiency

Measure the cost of rework

You suspect a lot of the spend goes to steering the agent back on track, but across sessions, you have no way to actually see it.

  • Input and output token counts per session show where the spend actually went (adapter coverage varies, and is documented).
  • Dead-ends and abandoned branches make wasted turns visible instead of invisible.
  • Track the same mistakes across sessions and stop paying for them twice.
See how it works

Put your last session to work.

One command, in any repo. Redaction-gated, deterministic, nothing leaves your machine. Node 18+.

$npx treetrace
Read the source Read the docs