simple-ai-provenance

Track every AI prompt you send in Claude Code, annotate git commits with what was asked, and query the full history of any session.

What it does

• Auto-captures every prompt you send in Claude Code via a hook — no manual steps
• Annotates commits with the prompts that produced the code, via global git hooks
• Answers "what did I do in this session?" through MCP tools callable inside Claude
• Generates PR descriptions with the full AI audit trail across every commit on the branch
• Tracks cross-repo work — if Claude is opened in one repo but edits files in another, prompts follow the files
• Stays compact — commit messages switch from verbose (all prompts) to condensed (summary) above a configurable threshold

Install

pip install simple-ai-provenance
provenance-setup

Then restart Claude Code and Claude Desktop.

That's it. Every prompt from that point forward is recorded automatically.

How it works

You type a prompt
    ↓
UserPromptSubmit hook fires → written to ~/.claude/provenance/provenance.db
    ↓
Claude writes/edits files
    ↓
PostToolUse hook fires → cross-repo reference stored if files are in a different repo
    ↓
git commit -m "fix: ..."
    ↓
prepare-commit-msg hook appends AI provenance block
    ↓
post-commit hook marks those prompts as committed

Commit message (≤ 5 prompts — verbose)

fix: auth bug

── AI Provenance ──────────────────────────────────────────

Session 1  (2026-02-26 14:30, id: a1b2c3d4, 3 prompts)
  • fix the auth bug in login.py
  • add error handling for the edge cases
  • write unit tests for the new endpoints

Files: src/auth/login.py, tests/test_auth.py

─────────────────────────────────────────────────────────

Commit message (> 5 prompts — long form)

Above the threshold the block stays complete — every prompt is still listed, just tighter, and capped by max_prompt_lines.

refactor: connection pooling

── AI Provenance ──────────────────────────────────────────

12 prompts · 2 sessions over 1h 23m

Session 1  (09:00, id: a1b2c3d4, 5 prompts)
  • refactor the database connection pooling module
  • pool should be lazy, not built at import time
  • ... (each prompt on its own line)

Session 2  (10:30, id: e5f6g7h8, 7 prompts)
  • add retry logic with exponential backoff
  • ...

(+2 more prompts — call get_session_summary in Claude)

Files: src/db/pool.py, src/db/retry.py (+3 more)

─────────────────────────────────────────────────────────

The block is plain text and is stored in the commit message. Earlier versions prefixed every line with #, which made the block's survival depend on how the commit was made: git commit -m keeps comment lines (cleanup mode whitespace), while any editor-based commit deletes them (cleanup mode strip). An audit trail that disappears depending on how you commit is not an audit trail, so as of 3.2.0 the block is written as ordinary message text.

Commits made in a batch

One piece of work is often split into several commits made seconds apart. Provenance is not consumed by the first of them: a commit also picks up the prompts attached to commits made in the same repo within batch_window_minutes (default 10), so every commit in the burst carries the same block.

MCP Tools

Once installed, these tools are available inside any Claude session:

Configuration

Config lives at ~/.claude/simple-ai-provenance-config.json:

{
  "settings": {
    "verbose_threshold": 5,
    "batch_window_minutes": 10,
    "max_prompt_lines": 40
  }
}

Prompts that are not user input — harness task notifications, subagent messages, local command output, system reminders — are filtered out at record time and again when a block is built, so entries recorded by earlier versions never reach a commit message.

Change it via the MCP tool inside Claude:

configure verbose_threshold=10

Or directly edit the JSON file.

Requirements

• Python 3.9+
• Claude Code (Claude CLI)
• Claude Desktop (optional — for MCP tools in the desktop app)
• Git

PR integration

sap-pr wraps gh pr create with the AI provenance block pre-filled in the body:

cd your-repo
sap-pr                        # gh prompts you interactively for title etc.
sap-pr --title "feat: auth"   # skip the interactive title prompt
sap-pr --base develop         # diff against a branch other than main
sap-pr --dry-run              # preview the body without creating the PR

The generated PR body lists every AI prompt grouped by session, across all commits on the branch.

How sessions are scoped

Each Claude Code session is scoped to the git repository detected from the working directory. Prompts from different projects never mix.

Session in ~/projects/api  → recorded under repo /Users/you/projects/api
Session in ~/projects/web  → recorded under repo /Users/you/projects/web

Cross-repo tracking: if Claude is opened in workspace/ but edits files in workspace/my-service/, the PostToolUse hook detects the file's actual git root and stores a cross-reference. Running sap-pr inside my-service/ will include those prompts.

Troubleshooting

Windows

pip or provenance-setup not found

If pip install simple-ai-provenance fails or provenance-setup is not recognized:

# Use the Python launcher (ships with Python for Windows)
py -m pip install simple-ai-provenance
py -m simple_provenance_tracker.install

Ensure Python is in your PATH. The Windows Python installer has an "Add to PATH" checkbox — if you missed it, re-run the installer and enable it.

Cannot modify Claude settings

If provenance-setup reports it could not write settings.json:

1. Close Claude Code completely
2. Re-run provenance-setup (or py -m simple_provenance_tracker.install)

Claude Code may lock ~/.claude/settings.json while running.

MCP server not listed in Claude Code

Use the absolute Python path in your MCP config. Find it with:

py -c "import sys; print(sys.executable)"

Then in ~/.claude.json (or %USERPROFILE%\.claude.json):

{
  "mcpServers": {
    "simple-ai-provenance": {
      "command": "C:/Users/YOU/AppData/Local/Programs/Python/Python311/python.exe",
      "args": ["-m", "simple_provenance_tracker.mcp_server"]
    }
  }
}

Git hooks not firing

Ensure Git for Windows is installed. Verify the hooks path:

git config --global core.hooksPath
# Should show: C:\Users\YOU\.config\git\hooks

macOS

simple-ai-provenance: command not found

The CLI may be installed into a Python bin/ directory that isn't in your shell's PATH. Find and add it:

# Find where it was installed
python3 -c "import sys; print(sys.executable)"
# e.g. /Library/Frameworks/Python.framework/Versions/3.11/bin/python3

# Add the bin directory to your shell profile
echo 'export PATH="/Library/Frameworks/Python.framework/Versions/3.11/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc

If your active shell is bash (not zsh), also add to ~/.bash_profile and ~/.bashrc.

MCP server not listed in Claude Code

Register globally with the absolute Python path in ~/.claude.json:

{
  "mcpServers": {
    "simple-ai-provenance": {
      "command": "/Library/Frameworks/Python.framework/Versions/3.11/bin/python3",
      "args": ["-m", "simple_provenance_tracker.mcp_server"]
    }
  }
}

Validate JSON: python3 -m json.tool ~/.claude.json >/dev/null && echo OK

Then restart Claude Code.

General

If MCP tools still don't appear after setup, the two most common checks are:

1. Can the CLI be found? (which simple-ai-provenance on macOS, where simple-ai-provenance on Windows)
2. Is the Claude config valid JSON? (python3 -m json.tool ~/.claude.json)

Uninstall

# Remove git hooks
git config --global --unset core.hooksPath

# Remove the UserPromptSubmit block from ~/.claude/settings.json

# Remove the simple-ai-provenance entry from Claude Desktop config

# Remove data (optional)
rm -rf ~/.claude/provenance/
rm ~/.claude/simple-ai-provenance-config.json

pip uninstall simple-ai-provenance

License

AGPL-3.0-or-later