Commit Context Tracing

ctx trace¶

Show the context behind git commits. Links commits back to the decisions, tasks, learnings, and sessions that motivated them.

git log shows what changed, git blame shows who — ctx trace shows why.

ctx trace [commit] [flags]

Flags:

Examples:

# Show context for a specific commit
ctx trace abc123

# Show context for last 10 commits
ctx trace --last 10

# JSON output
ctx trace abc123 --json

Output:

Commit: abc123 "Fix auth token expiry"
Date:   2026-03-14 10:00:00 -0700
Context:
  [Decision] #12: Use short-lived tokens with server-side refresh
    Date: 2026-03-10

  [Task] #8: Implement token rotation for compliance
    Status: completed

When listing recent commits with --last:

abc123  Fix auth token expiry         decision:12, task:8
def456  Add rate limiting             decision:15, learning:7
789abc  Update dependencies           (none)

ctx trace file¶

Show the context trail for a file. Combines git log with context resolution.

ctx trace file <path[:line-range]> [flags]

Flags:

Examples:

# Show context trail for a file
ctx trace file src/auth.go

# Show context for specific line range
ctx trace file src/auth.go:42-60

ctx trace tag¶

Manually tag a commit with context. For commits made without the hook, or to add extra context after the fact.

Tags are stored in .context/trace/overrides.jsonl since git trailers cannot be added to existing commits without rewriting history.

ctx trace tag <commit> --note "<text>"

Examples:

ctx trace tag HEAD --note "Hotfix for production outage"
ctx trace tag abc123 --note "Part of Q1 compliance initiative"

ctx trace hook¶

Enable or disable the prepare-commit-msg hook for automatic context tracing. When enabled, commits automatically receive a ctx-context trailer with references to relevant decisions, tasks, learnings, and sessions.

ctx trace hook <enable|disable>

Prerequisites: ctx must be on your $PATH. If you installed via go install, ensure $GOPATH/bin (or $HOME/go/bin) is in your shell's $PATH.

What the hook does:

1. Before each commit, collects context from three sources:
2. Pending context accumulated during work (ctx add, ctx task complete)
3. Staged file changes to .context/ files
4. Working state (in-progress tasks, active AI session)
5. Injects a ctx-context trailer into the commit message
6. After commit, records the mapping in .context/trace/history.jsonl

Examples:

# Install the hook
ctx trace hook enable

# Remove the hook
ctx trace hook disable

Resulting commit message:

Fix auth token expiry handling

Refactored token refresh logic to handle edge case
where refresh token expires during request.

ctx-context: decision:12, task:8, session:abc123

Reference Types¶

The ctx-context trailer supports these reference types:

Storage¶

Context trace data is stored in the .context/ directory: