Trace

Git-native session capture for AI coding agents

Quick Start • How It Works • Commands • Configuration • Contributing

Trace hooks into your Git workflow to capture AI agent sessions as you work. Sessions are indexed alongside commits, creating a searchable record of how code was written — not just what changed.

Ecosystem Boundaries

Trace is a Hawk support engine. Keep the dependency edge one-way:

• trace uses local-only types (trace/redaction event types are trace-scoped, not shared contracts)
• do not import hawk/internal/*
• do not import removed legacy path hawk/shared/types
• do not import other engines (eyrie, yaad, tok, sight, inspect) — engines are peers, not dependencies

What you get

Supported Agents

Quick Start

Trace is a library, not a standalone binary. Its full command tree is built by cli.NewRootCmd() and surfaced inside the Hawk CLI as hawk trace ... (Hawk is in development — no public install yet). There is no separate trace binary to install.

Contributors — build/test the library from source:

git clone https://github.com/GrayCodeAI/trace && cd trace
go build ./...
go test ./...

Once Hawk is available, use the commands under hawk trace:

# Enable in your project
cd your-project
hawk trace enable

# Check status
hawk trace status

That's it. Trace runs silently in the background via Git hooks.

How It Works

Your Branch                    trace/checkpoints/v1
     |                                  |
     v                                  |
[Base Commit]                           |
     |                                  |
     |  +--- Agent works ---+           |
     |  |  Step 1           |           |
     |  |  Step 2           |           |
     |  |  Step 3           |           |
     |  +-------------------+           |
     |                                  |
     v                                  v
[Your Commit] ----------------------> [Session Metadata]
     |                           (transcript, prompts,
     v                            files touched, tokens)

Key principles:

• Zero commits on your active branch
• Session data stored on trace/checkpoints/v1 orphan branch
• Checkpoints created automatically at each commit
• Non-destructive rewind — restores files without altering history
• Works on any branch (main, feature, etc.)

Typical Workflow

1. Enable

trace enable                     # Interactive setup
trace enable --agent claude-code # Non-interactive

2. Work normally

Use your AI agent as before. Trace captures everything in the background.

trace status   # Check session anytime

3. Rewind if needed

trace checkpoint rewind   # Select a checkpoint to restore

4. Resume on another branch

trace session resume <branch>   # Restore session metadata & continue

5. Disable (optional)

trace disable   # Removes hooks, code untouched

Commands

Run trace <command> --help for detailed usage.

Configuration

Trace stores config in .trace/ at the repo root.

Project settings (.trace/settings.json)

Shared with the team, committed to git:

{
  "enabled": true,
  "strategy_options": {
    "push_sessions": true,
    "summarize": { "enabled": true }
  }
}

Local overrides (.trace/settings.local.json)

Personal, gitignored:

{
  "log_level": "debug"
}

All options

Checkpoint Remote

Push session data to a separate private repo:

trace enable --checkpoint-remote github:myorg/checkpoints-private

Security & Privacy

• Session transcripts live on trace/checkpoints/v1 in your repo
• Secrets are automatically redacted (API keys, tokens, credentials) — best-effort
• Shadow branches used during sessions are local-only and never pushed
• See docs/security-and-privacy.md for details

Troubleshooting

Debug mode:

TRACE_LOG_LEVEL=debug trace status

Reset everything:

trace clean --all --force

Accessibility:

export ACCESSIBLE=1   # Screen reader friendly mode

Development

# Prerequisites: mise (https://mise.jdx.dev/)
git clone https://github.com/GrayCodeAI/trace.git
cd trace && mise install && mise trust

# Build
mise run build

# Test
mise run test          # Unit tests
mise run test:ci       # Full suite (unit + integration)

# Lint & format
mise run fmt && mise run lint

See CLAUDE.md for architecture details.

License

MIT — see LICENSE

Built by GrayCode AI