Rationale
git blame for AI-generated code. Capture the why behind every non-trivial choice an AI agent makes. Anchored to lines in your repo. Queryable six months later.
AI agents ship code faster than humans can build a mental model of why it exists. Six months later, nobody — not even the person who approved the PR — can explain why a retry was set to 3, why a dependency was added, or why a function was split a particular way. The reasoning dies with the agent session.
Rationale fixes this. The agent records each meaningful decision at the moment it's made, in its own voice, into a .rationale/ directory in your repo. You can query it from the CLI, from inside a future agent session via MCP, or gate it in CI.
How it works
flowchart LR
A[Agent session in<br/>Claude Code / Copilot / Cursor] -->|picks retry count<br/>chooses library<br/>structures API| B[rationale_record<br/>MCP tool]
B --> C[(.rationale/<br/>YYYY-MM/<br/>d-abc123.md)]
C -->|git commit| D[Lives in the repo forever]
D -.->|6 months later| E[Future session:<br/>rationale why payment.py:42]
E --> F[Returns the exact<br/>reasoning + alternatives]
style B fill:#7F52FF,color:#fff
style C fill:#4584b6,color:#fff
style D fill:#2da44e,color:#fff
style F fill:#f79232,color:#fff
Every decision is a markdown file with YAML frontmatter. It's git-tracked, grep-able, and survives any platform migration.
Install
For Claude Code users (one command after pipx)
pipx install rationale-cli
Then inside Claude Code:
/plugin marketplace add shivam2407/rationale
/plugin install rationale@rationale
That's it. The plugin auto-wires the Stop hook (safety-net capture), the rationale MCP server (runtime capture + queries), five slash commands, and a CLAUDE.md that tells the agent when to call rationale_record.
[!TIP]
Don't have pipx? brew install pipx && pipx ensurepath — skip the macOS-default-Python headaches.
For every other agent (Copilot CLI, Cursor, Aider, bare CLI)
pipx install rationale-cli
You now have the rationale and why binaries. Wire them up:
- Querying:
rationale why src/payment.py:42 works anywhere, any time.
- MCP runtime capture: register
rationale mcp as an MCP server in your agent's config.
- Stop-hook capture: only Claude Code ships a session-end hook today; for others, pipe transcripts into
rationale capture --transcript <path>.
From source
git clone https://github.com/shivam2407/rationale.git
cd rationale
pip install -e .
Requires Python 3.10+.
Optional extras
| Extra | Install | What it unlocks |
|---|
[llm] | pipx install 'rationale-cli[llm]' | Use the Anthropic SDK directly with ANTHROPIC_API_KEY. Optional — the default path uses claude -p from Claude Code. |
[crypto] | pipx install 'rationale-cli[crypto]' | Ed25519 signing for EU AI Act JSON-LD exports. |
[mcp] | pipx install 'rationale-cli[mcp]' | Pulls in the official MCP SDK (the built-in stdio server works without it). |
What a decision looks like
A stored decision is a plain markdown file. Here's one:
---
id: d-a3f9c1
timestamp: 2026-04-16T14:22:00Z
agent: claude-code
session_id: sess-7b2
git_sha: 1f3b9c2a08...
files: [src/payment.ts]
anchors:
- file: src/payment.ts
lines: [42, 58]
symbol: PaymentService.retry
content_hash: a1b2c3d4e5f6...
alternatives_considered: [exponential_backoff, circuit_breaker]
chosen: fixed 3x retry
confidence: medium
tags: [reliability, payments]
---
Downstream rate limits already cap traffic, and exponential backoff would
stretch p95 past the 800ms SLO. Circuit breaker was overkill for a single
dependency with low failure correlation.
Querying the past
$ rationale why src/payment.ts:42
d-a3f9c1 fixed 3x retry (exact-line)
when: 2026-04-16T14:22:00Z
sha: 1f3b9c2a08
anchor: src/payment.ts:42-58 [symbol: PaymentService.retry]
rejected: exponential_backoff, circuit_breaker
tags: reliability, payments
Downstream rate limits already cap traffic, and exponential backoff
would stretch p95 past the 800ms SLO. Circuit breaker was overkill
for a single dependency with low failure correlation.
Three query shapes work:
