Trace Hooks

ChooChoo can auto-detect AI coding agents on your machine and install hooks that record a trace every time the agent modifies a file. This works with Claude Code, OpenCode, and Gemini CLI.

1. Scan for agents

See which coding agents ChooChoo can detect:

choochoo trace hooks scan

This checks for config directories at:

2. Preview changes

Before writing anything, use --dry-run to see what would change:

choochoo trace hooks install --dry-run

This shows which config files would be created or updated, without modifying anything.

3. Install hooks

Install the trace hooks:

choochoo trace hooks install

For each detected agent, this adds hooks that call choochoo trace record on relevant events:

• Claude Code: hooks on SessionStart, SessionEnd, PostToolUse
• OpenCode: hooks on file_edited, session_completed
• Gemini CLI: hooks on SessionStart, SessionEnd, AfterTool

If a config file doesn't exist yet, ChooChoo creates it. Use --no-create to skip creating new files.

4. Verify

After installing, check that traces are being recorded:

# Make a change with your coding agent, then:
choochoo trace list

You should see new trace entries with the agent's model ID, the files it changed, and timestamps.

How traces are stored

Traces are appended to .choochoo/traces.ndjson (newline-delimited JSON) in your project root. Each line is a self-contained trace record. See Agent Traces for the full schema.

Related