ChooChoo

Agent Trace records who changed what and why. Every time an AI agent (or a human) 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.

The ChooChoo CLI can auto-detect coding agents on your machine and install hooks that record traces automatically:

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

Traces are stored in .choochoo/traces.ndjson and can be listed or inspected:

choochoo trace list
choochoo trace show <id>

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 links changes back to the conversation that created them, so you can:

Review with full context — see the AI's reasoning behind a PR.
Build agent memory — agents can retrieve past decisions to avoid repeating mistakes.
Audit — differentiate between human and AI-authored code.

Specification

The standard defines a JSON schema for recording trace data. Agent Trace is one of several open standards that ChooChoo builds upon — see the Standards Reference for the full list, and Schema Definitions for the formal spec.

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-5-20251101"
          },
          "ranges": [
            {
              "start_line": 42,
              "end_line": 67,
              "content_hash": "murmur3:9f2e8a1b"
            }
          ],
          "related": [
            {
              "type": "session",
              "url": "https://api.cursor.com/v1/sessions/67890"
            }
          ]
        }
      ]
    },
    {
      "path": "src/utils/helpers.ts",
      "conversations": [
        {
          "url": "https://api.cursor.com/v1/conversations/12345",
          "contributor": {
            "type": "ai",
            "model_id": "openai/gpt-4o"
          },
          "ranges": [
            {
              "start_line": 10,
              "end_line": 25
            }
          ]
        }
      ]
    }
  ],
  "metadata": {
    "confidence": 0.95,
    "dev.cursor": {
      "workspace_id": "ws-abc123"
    }
  }
}

The metadata.confidence field is used by ChooChoo's risk scoring algorithm as the Agent Confidence (A) factor. Lower confidence values increase the overall risk score, potentially triggering approval workflows.

Each agent referenced in traces should have a registered System Card that documents its capabilities and limitations. The trace links the agent's identity to the Audit Trail, creating a complete chain of attribution.

Implementing with Hooks

You can automatically capture Agent Traces by configuring hooks in your AI coding tools. The choochoo trace commands handle the recording and retrieval of trace data.

Cursor Example (`.cursor/hooks.json`)

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

Claude Desktop Example (`.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"
          }
        ]
      }
    ]
  }
}

By hooking into these events, ChooChoo automatically generates and stores the trace data, building the Context Graph in the background. This data is also accessible from The Station for visualization and search.

Managing Traces via CLI

Use the choochoo trace commands to manage trace data:

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, providing a complete record of every change and the context behind it.

Agent Trace

Why trace?

Specification

Example Trace

Implementing with Hooks

Cursor Example (`.cursor/hooks.json`)

Claude Desktop Example (`.claude/settings.json`)

Managing Traces via CLI

Agents

System Cards

Audit Trail

Risk Scoring

Standards Reference

CLI Reference

On this page