Sharing via Git Hooks

A post-commit hook writes trace IDs into git notes on each commit. The notes travel with commits when pushed, so collaborators can look up the traces that produced any change.

Setup

traces setup git

This installs .git/hooks/traces-post-commit and injects a guarded call into .git/hooks/post-commit. It chains with existing hooks (husky, lefthook, project hooks) without overwriting them. It also configures a per-repo fetch refspec so notes sync on pull.

Running traces setup (the interactive flow) also offers to install git hooks after agent skill selection. It then scans your trace history for other repos you've worked in and offers to install hooks on any that don't have them yet.

Agent hooks

When traces setup runs, it also installs lifecycle hooks into each detected agent's config. These hooks fire on session start, prompt submission, and agent completion, tracking which traces are active in traces-active.json inside the git directory.

This means the git hooks know exactly which traces to attach to a commit without searching. Traces are also uploaded in the background as the agent works, so shared URLs are usually ready before you commit.

Agent hooks are supported for all agents: Claude Code, Cursor, Gemini CLI, Codex, Copilot, Cline, OpenCode, Pi, Amp, OpenClaw, and Hermes.

What the hook does

On each commit, the hook:

1. Reads traces-active.json for active session trace IDs (instant file read when agent hooks are installed, falls back to traces list --dir . --since <timestamp> search otherwise)
2. Records the repo URL, branch, and commit ref on each trace in local SQLite
3. Writes their external IDs into refs/notes/traces on the commit
4. Runs traces share in the background to upload unshared traces (often already uploaded by agent hooks)
5. Pushes notes to the remote

Multiple traces can attach to a single commit, and multiple commits can reference the same trace.

Note format

One trace per line, shared URL appended when available:

traces:<externalId> <sharedUrl>
traces:<externalId>

The traces: prefix prevents collisions with other tools using git notes. Notes are appended, not replaced, so multiple collaborators can add trace IDs to the same commit.

Reading notes

# Check note on latest commit
git notes --ref=traces show HEAD

# View notes inline with commit log
git log --notes=traces -3

# List all trace IDs from recent commits (machine-readable)
traces notes --json

The traces notes command parses refs/notes/traces and returns trace IDs, commit refs, and shared URLs. URLs are validated against an allowlist (traces.com and the configured TRACES_URL host).

To browse linked traces from your repo history, see CLI Discovery.

Viewing trace content

# Show a trace from the local store
traces show <id> --json

# Fetch from the API if not available locally
traces show <id> --json --remote

# Render as markdown with injection-resistant boundary tags
traces show <id> --markdown

The --markdown flag wraps the output in random boundary tags and includes a preamble marking the content as historical context. This format is designed for safely loading trace history into AI agent context windows.

Verifying

# Run health check
traces doctor

Removing

traces remove git

Removes the hook file and the injected call from .git/hooks/post-commit, leaving other hooks intact.