Skip to article content

Revised 26 October 2026 · v1.0.0 · what changed

Code: github.com/herrrickshaw/claude-provenance

Watch the walkthrough

Watch on YouTube: youtu.be/aENlyT4G1aY

Why it is useful

• Who benefits: people who use Claude Code or claude.ai heavily and need to answer when, with which model, in which folder and on which git branch something was asked or done.
• What it replaces: grepping scattered JSONL transcripts by hand.
• Evidence from the run: a synthetic session of four messages became a queryable table with role, model, tool names, content length and a hash; a second run skipped the unchanged file.
• Audit value: each row stores the source file and line number plus a SHA-256 of the full content, so you can recompute the hash later and detect edits.
• Privacy note built in: the database holds transcript content, so it is meant to stay local and gitignored.

What it is for

claude-provenance reads transcripts that Claude Code already writes under ~/.claude/projects, your prompt history file, and optionally a claude.ai data export, and writes one SQLite file, provenance.db.

Each message row records where it came from (file and line), when (original and ingest timestamps), who (role, model, CLI version, git branch, working folder), what (record type, tool calls, a 300-character preview) and integrity and lineage (SHA-256, message id and parent id).

Re-runs are incremental: unchanged source files are skipped. --summary also writes a markdown summary of counts by source, project and model.

Who it is for

• Teams or individuals who need a record of AI-assisted work
• Researchers measuring their own AI usage
• Anyone debugging which session changed something

What you need

Get the code and an AI assistant

You do not have to be a programmer. Get the repository, give it to an AI assistant, and ask in plain language. Any of these routes works:

git clone https://github.com/herrrickshaw/claude-provenance.git
cd claude-provenance
claude      # or: gemini

Install

1. Clone the repo

   git clone https://github.com/herrrickshaw/claude-provenance.git
   cd claude-provenance

2. Make sure provenance.db and PROVENANCE_SUMMARY.md stay out of git (the repo gitignores them in the author's setup; add your own ignore if you copy the script elsewhere)

   printf 'provenance.db\nPROVENANCE_SUMMARY.md\n' >> .gitignore

Quick start: commands and what you should see

Ingest everything and write the summary

python3 provenance_log.py --summary

'Parsed N files (...). Ingested M messages this run.' then the database path and the summary path.

Run it again

python3 provenance_log.py

'Parsed 0 files (N unchanged, skipped)': only new or changed transcripts are re-read.

Look at one day or one tool

sqlite3 provenance.db "SELECT ts, role, model, content_preview FROM messages WHERE ts LIKE '2026-10-01%' ORDER BY ts"

The messages of that day in time order.

Include a claude.ai export

python3 provenance_log.py --claude-ai-export /path/to/unzipped-export

Adds source claude-ai-export rows, one per chat message.

Sample outputs

Real output from a run on the date shown in the sources line; trimmed to fit.

Ingest of a synthetic Claude Code session (run 19 Oct 2026, HOME pointed at a made-up folder)

python3 provenance_log.py --summary
python3 provenance_log.py
Parsed 2 files (0 unchanged, skipped). Ingested 5 messages this run.
Database now holds 5 messages across 1 sessions -> .../provenance.db
Summary written -> .../PROVENANCE_SUMMARY.md
---rerun
Parsed 0 files (1 unchanged, skipped). Ingested 0 messages this run.

The demo used a fake ~/.claude with one four-message session and one prompt-history line. No real transcripts were read.

The provenance record for that session

sqlite3 -header -column provenance.db "select ts,role,model,tool_names,content_chars,substr(content_sha256,1,12) sha,content_preview from messages where source='claude-code' order by ts"
ts                    role       model            tool_names  content_chars  sha           content_preview
--------------------  ---------  ---------------  ----------  -------------  ------------  ------------------------------------
2026-10-01T09:00:00Z  user                                    25             82bb095abde1  Why does test_parse fail?
2026-10-01T09:00:05Z  assistant  claude-sonnet-5  Bash        39             7c687025e3fc  Let me run it. {"command": "pytest -x"}
2026-10-01T09:00:09Z  user                                    31             02aebbe264cc  1 failed: off-by-one in parse()
2026-10-01T09:00:15Z  assistant  claude-sonnet-5  Edit        73             63c17a533d05  parse() slices one char too many; fix the end index.

Preview lines trimmed. The first hash equals sha256('Why does test_parse fail?'), checked separately.

Summary file header

head -22 PROVENANCE_SUMMARY.md
**5 messages** across **1 sessions**

| Source | Messages | First | Last |
| claude-code | 4 | 2026-10-01T09:00:00Z | 2026-10-01T09:00:15Z |
| prompt-history | 1 | 2026-09-21T14:13:20+00:00 | ... |

| Model | Assistant messages |
| claude-sonnet-5 | 2 |

Trimmed. Counts are for the synthetic data only.

Ways to use it

Sample prompts for your AI assistant

Copy, paste and edit the parts in [brackets].

• Explain the claude-provenance repository in plain English: what problem it solves, what the main files do, and what I need installed.
• Write a SQLite query that shows my Claude messages per day for the last 30 days, split by model.
• Which git branches had the most assistant tool calls? Query provenance.db and show the top 10.
• Explain how I would verify that one message in provenance.db has not been altered since it was ingested.
• Review provenance_log.py for privacy risks and suggest what I should exclude before sharing a summary.
• Help me export my claude.ai data and ingest it with --claude-ai-export, step by step.

Limits and honest caveats

Sources: claude-provenance README and provenance_log.py; run on 19 October 2026 on a fresh clone with HOME pointed at a synthetic ~/.claude folder (one made-up session). No real transcripts or the repo's own database were read.

About this article: Researched, written and edited by Umashankar Triplicane Dwarakanathan, with AI research assistance; every figure is meant to trace to the primary source cited. See the Editorial Policy for how sourcing, AI use and corrections work.