Agent Trace records who changed what and why. It is the foundation of ChooChoo's improvement loop: traces → benchmarks → better agents.

Every time an AI agent modifies a file, a trace captures the contributor type, model ID, file path, line ranges, and a link to the conversation that produced the change. Traces are stored in .choochoo/traces.jsonl.

choochoo trace hooks scan      # detect Claude Code, OpenCode, Gemini CLI, Cursor, Codex
choochoo trace hooks install   # add hooks to their config files

choochoo trace list            # list recent traces
choochoo trace show <id>       # inspect a specific trace

Why Trace?

Git captures what changed, but not why. When an AI agent writes code, the reasoning behind it is typically lost after the commit.

Agent Trace closes this gap. By linking changes back to the conversation that created them, ChooChoo enables:

1. Context across sessions — agents can retrieve past decisions, avoiding repeated mistakes.
2. Benchmarking — traces feed evaluation harnesses (SWE-Bench, ITBench, custom task suites) to measure agent quality over time.
3. Context quality scoring — how much of the agent's work was on-target? Did the provided context help?
4. Attribution — differentiate human-authored from AI-authored code for audit purposes.
5. Prompt optimization — GEPA-style feedback uses trace outcomes to improve system prompts automatically.

Specification

The Agent Trace standard defines a JSON schema for recording trace data. It is an open standard — see Supported Schemas for the full list.

Example Trace

{
  "version": "0.1.0",
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "timestamp": "2026-01-23T14:30:00Z",
  "vcs": {
    "type": "git",
    "revision": "a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0"
  },
  "tool": {
    "name": "cursor",
    "version": "2.4.0"
  },
  "files": [
    {
      "path": "src/utils/parser.ts",
      "conversations": [
        {
          "url": "https://api.cursor.com/v1/conversations/12345",
          "contributor": {
            "type": "ai",
            "model_id": "anthropic/claude-opus-4-6"
          },
          "ranges": [
            {
              "start_line": 42,
              "end_line": 67,
              "content_hash": "murmur3:9f2e8a1b"
            }
          ],
          "related": [
            {
              "type": "session",
              "url": "https://api.cursor.com/v1/sessions/67890"
            }
          ]
        }
      ]
    }
  ],
  "metadata": {
    "confidence": 0.95,
    "dev.cursor": {
      "workspace_id": "ws-abc123"
    }
  }
}

The metadata.confidence field represents the agent's self-assessed certainty. Lower confidence values indicate the agent was uncertain — useful signal for quality scoring and benchmarking.

Implementing with Hooks

ChooChoo automatically installs hooks into your AI coding tools. Run choochoo trace hooks install to set them up.

Claude Code (.claude/settings.json)

{
  "hooks": {
    "SessionStart": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "choochoo trace record"
          }
        ]
      }
    ],
    "SessionEnd": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "choochoo trace record"
          }
        ]
      }
    ],
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "choochoo trace record"
          }
        ]
      },
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "choochoo trace record"
          }
        ]
      }
    ]
  }
}

Cursor (.cursor/hooks.json)

{
  "version": 1,
  "hooks": {
    "sessionStart": [{ "command": "choochoo trace record" }],
    "sessionEnd": [{ "command": "choochoo trace record" }],
    "afterFileEdit": [{ "command": "choochoo trace record" }],
    "afterShellExecution": [{ "command": "choochoo trace record" }]
  }
}

Traces and Context Retrieval

Traces power Context Compilation. When choochoo context generate builds AGENTS.md, it uses qmd vsearch — semantic indexing over your trace history — to surface the most relevant past decisions for the current codebase state. This gives agents institutional memory without requiring them to re-read the entire history.

SWE-Bench and ITBench are example benchmark targets that can consume trace output to evaluate agent performance on real-world tasks.

Managing Traces via CLI

choochoo trace record          # Capture current session state
choochoo trace list            # List recent trace records
choochoo trace show <trace-id> # View details for a specific trace

In CI/CD pipelines, trace data is submitted alongside validation results.

Related

• Agents — Register AI agents with boundaries and rails.
• Context Compilation — How traces power agent startup context.
• Governance (Preview) — How trace data feeds audit and risk workflows.
• CLI Reference — Full documentation for choochoo trace commands.