backstory

Git history tells you what changed. When the change came from an AI coding agent, the why lives in a prompt that gets thrown away. backstory captures those prompts and attaches them to your commits as git notes (refs/notes/backstory), so the context travels with the repo without touching the commits themselves.

Works with Claude Code, Cursor, OpenAI Codex CLI and Google Antigravity. Everything stays on your machine.

Install

npm install -g backstory

Requires Node 18+. The Cursor adapter additionally needs better-sqlite3 (installed automatically as an optional dependency; if its build fails, only the Cursor adapter is disabled).

Setup, once per repo

cd your-repo
backstory install-hooks
backstory watch

install-hooks writes a post-commit hook that moves any captured prompts into a git note on the new commit. It never blocks or fails a commit.

watch detects which agents have data for this repo and starts recording in the background. backstory stop ends it, backstory status shows what is pending.

To make notes follow git push / git pull automatically:

backstory install-hooks --configure-push

Or push them by hand: git push origin refs/notes/backstory.

How capture works per agent

| agent | mechanism | | --- | --- | | Claude Code | official Stop hook, registered in .claude/settings.local.json | | Codex CLI | tails the session transcripts under ~/.codex/sessions/ | | Antigravity | tails conversation logs under ~/.gemini/antigravity-ide/brain/ (and legacy ~/.gemini/antigravity/brain/) | | Cursor | polls Cursor's internal sqlite database (undocumented format, may break on Cursor updates; degrades silently) |

For anything else, record by hand:

backstory note -p "make the retry logic exponential" -r "rewrote backoff in client.js" -f "src/client.js" --agent chatgpt

Reading the history back

backstory why src/client.js 42     # who wrote this line, and what was the prompt
backstory log src/client.js       # full history of a file with AI context inline
backstory show HEAD               # raw note JSON for one commit
backstory export --out notes.json # everything as JSON
backstory dashboard               # local web UI on http://localhost:4287

The dashboard has full-text search across prompts, a per-file timeline, a breakdown by agent and a list of the most AI-touched files. It is served locally from the export data and needs no build step.

Notes on the data

Entries are stored in a common shape regardless of agent:

{
  "agent": "claude-code",
  "prompt": "the user's instruction",
  "response_summary": "short summary of what the AI did",
  "files": ["src/client.js"],
  "timestamp": "2026-07-17T09:30:00.000Z",
  "session_id": "abc123"
}

Between commits, entries queue up in .git/backstory/pending.json. On commit they become one note on that commit. Notes are additive: nothing in your existing history is modified, and deleting the refs/notes/backstory ref removes everything backstory ever wrote.