Skip to content

agent-trace

agent-trace is a command-line tool for tracing how AI coding assistants (for example Cursor, Claude Code, and Codex CLI) change your repositories. It follows a local-first model: hooks write structured events under your home directory, git hooks build a deterministic attribution ledger at commit time, and you can optionally push and pull data to an HTTP remote or share pointers via git notes (refs/notes/agent-trace).

This site is the published user manual: every command, flag, and configuration path the CLI exposes, plus the concepts you need to use it confidently in real teams.

What you can do with agent-trace

Goal Primary commands
Turn tracing on in a repo agent-trace init
Install hooks once for all projects agent-trace hooks setup-global
See health and counts agent-trace status, agent-trace doctor
Line-level AI vs no-attribution labels agent-trace blame
Pull conversation text behind AI edits agent-trace context
Browse files with git + agent blame agent-trace viewer
Team sync / backup agent-trace remote, push / pull / sync
Ship metadata with the repo agent-trace notes
Session-end transcript summaries agent-trace summary

Design principles (at a glance)

  • No third-party Python dependencies — the CLI uses only the Python standard library (Python 3.9+).
  • Ledger-only blame — blame does not guess from heuristics. Attribution is binary (AI or No attribution); if there is no ledger (and no usable inline data in a git note), lines are No attribution.
  • Explicit sync — nothing uploads to a remote during normal editing; you run push, pull, or sync when you want.
  • Stable project identity — after init, identity is anchored in .git/agent-trace-id so renames and worktrees behave predictably. See Project identity.
  1. Getting started — minimal path from zero to first blame.
  2. Installation — installer behavior, PATH, viewer, uninstall.
  3. Command reference — exhaustive per-command pages.
  4. Configuration — every config set / config reset field.

Specification & source

The tool aligns with the public Agent Trace specification. Source code lives in the agent-trace-cli repository on GitHub.