Backstory

Git shows what changed. Backstory shows why.

The reasoning layer your git history is missing.

You're reading a commit the AI wrote three weeks ago. Something is broken.

• Why did it reject the simpler approach?
• What tradeoffs did it accept that you didn't notice?
• Which decision from last sprint is this about to undo?

There's no author to ask. The chat is gone. The commit message says what changed.

How It Works

1. Capture — Claude Code's SessionEnd hook (set up by backstory init) copies the transcript to .backstory/transcripts/latest.jsonl.
2. Ingest — Backstory extracts the durable decisions, risks, and changed files. The raw conversation is discarded.
3. Link — The session is attached to the relevant Git commit via backstory attach HEAD.
4. Retrieve — Query reasoning by commit, file, line, range, or diff.

Git stays the linkage layer. Backstory stores the reasoning.

Contradiction Detection

An archive is useful. A guardrail is valuable.

Backstory watches for new changes that reverse earlier recorded decisions — and warns you before you merge.

⚠ This change may contradict a decision from commit 8f21c9a:
  "payment.failed should mark subscription as pending, not cancelled"

What It Does

Understand any commit. backstory why HEAD tells you why a commit happened — rejected alternatives, accepted risks, the full chain of reasoning.

Find the reasoning behind any line. Query by file, line, or range. If the AI made a specific decision about that code, Backstory surfaces it.

Catch reversals before they ship. Contradiction detection warns when a new change undoes a past decision. Turns an archive into a guardrail.

Quick Install

Install from PyPI (recommended):

pip install backstory-cli

Run from source (no install needed):

git clone https://github.com/arpitkath/backstory.git
cd backstory
python -m backstory init
python -m backstory test

Then initialize and verify in your repo:

backstory init
backstory test    # verify everything is set up correctly

See a full worked example with before/after code and stored session.

Commands at a Glance

See the full reference below.

Privacy

Backstory is local-first by design. No cloud service or telemetry is required. Raw transcripts are never persisted — only extracted decisions, risks, follow-ups, and Git context are kept. Built-in redaction scans for and removes API keys and secrets during ingestion.

Integration

Works with Claude Code automatically after backstory init. Cursor and Codex support planned.

Backstory uses a SessionEnd lifecycle hook in .claude/settings.json to capture transcripts automatically — no env vars or manual paths needed:

{
  "env": {
    "CLAUDE_CODE_SESSIONEND_HOOKS_TIMEOUT_MS": "120000"
  },
  "hooks": {
    "SessionEnd": [{
      "hooks": [{
        "type": "command",
        "command": "backstory session-end",
        "timeout": 600,
        "statusMessage": "Archiving session..."
      }]
    }]
  }
}

backstory init writes this config for you.

Backstory also supports Claude Code v2.1+'s JSONL transcript format natively.

See the integration guide for step-by-step setup.

Reference

Storage

.backstory/
  config.json
  transcripts/
    latest.jsonl
  knowledge/
    index.md
    sessions/
      index.md
      latest.md
      sha256-<session>.md
  redactions/
    tombstones.log

Session memory is stored as Google's OKF-style markdown — human-readable, Git-friendly, and agent-friendly.

Documentation

• Integration guide — Set up with Claude Code and other tools
• Engineering walkthrough
• Product spec
• Retrieval model

If you find this useful, starring the repo helps others discover it.