Capture agent coding decisions for code review and team context

Grepathy makes agent-written code reviewable by capturing the decisions a coding agent made along the way - including ones nobody explicitly approved - and writing them to a markdown file committed alongside the code. The problem it targets: an agent building a feature makes small unreviewed choices, a later PR reviewer asks "why was this done this way," and the answer is buried in a chat transcript that Claude Code deletes after 30 days by default. Grepathy reads session transcripts locally, extracts the decisions, and writes them so the repo itself can answer "why," for reviewers, teammates, and future agents.

It runs off hooks rather than being invoked manually: you work normally with claude, and when you git push, Grepathy writes the why-file and shows it to you for review before anything ships. Each branch gets one file (.ai/why/<branch>.md), containing entries like a status (agent-initiated, i.e. not requested in any plan or prompt), the files touched, the agent's inferred rationale, and flagged risk and reviewer-attention notes - the README's own example is an agent silently deciding to pre-create guest users in Clerk, something the author only learned about when a reviewer asked. Running grep -rn "agent-initiated" .ai/why/ surfaces every unrequested decision an agent made across the repo. Future agents automatically see this context through two triggers: a CLAUDE.md pointer loaded every session, and a PreToolUse hook that injects relevant why-pack entries right before an agent edits a file with prior history - so an agent meets the reasoning before it changes the code, without needing to remember to look. It never blocks a push, never touches the staging area, and never pushes anything itself, working fine alongside multiple agents and worktrees.

Grepathy is careful about extraction rather than logging mid-task, because the team's own earlier attempt at asking agents to "log decisions" as they went simply didn't work - agents don't reliably do it. Privacy is enforced by rule rather than just prompt: the summarizer never quotes raw messages, never describes back-and-forth or confusion, never includes business or financial details, and strips secrets, backed by two deterministic checks (a secret/finance scanner and a rule that every entry must point at real code) before the file is shown to you for review; edits or deletions you make to an entry are respected permanently. A --self-only mode keeps why-packs entirely local (git-excluded, never committed) for trying the tool on a repo you don't own or want to share notes about.

The project ran a blind, pre-registered evaluation against an honest baseline and published results including where the tool lost: it doesn't stop an agent from refactoring away important code, and it doesn't make agents generally smarter - if an answer is readable from the code itself, agents find it fine without Grepathy. What it measurably helped with was preserving reasoning that would otherwise be deleted (two of the team's own projects lost their entire transcript history before the eval could even run) and surfacing knowledge that leaves no trace in the code at all (a rejected alternative, an unrequested change) - agents without the why-file made up plausible-sounding wrong answers to those questions in testing.

Use Grepathy on any repo where Claude Code agents make substantive implementation decisions and you (or reviewers) need to know why later - especially before Claude Code's 30-day transcript deletion erases the only record. It's a fit for teams that want that reasoning committed to the repo itself, shareable and reviewable like any other code artifact, rather than living in someone's local chat history.

It won't stop an agent from making a bad decision or refactoring away something important - it only documents decisions after the fact, it doesn't gate or review them in real time. Writing why-files currently requires Claude Code specifically (a Codex adapter is planned but not shipped); any tool can read the resulting markdown files since they're plain text.

Install with one command, then work normally:

npx grepathy init
claude        # work normally, let the agent commit as it goes
git push      # Grepathy writes the why file and shows it for review

Input is your local Claude Code session transcripts (never sent anywhere) plus the git history of the branch being pushed. Output is a per-branch markdown file (.ai/why/<branch>.md) with one entry per notable decision (status, touched files, rationale, risk), shown to you for review before the push proceeds, and later injected into future agent sessions via CLAUDE.md and a PreToolUse hook. Other commands: grepathy status/doctor (health checks), grepathy context <path> (entries applying to a file), grepathy sync (distill and commit immediately, still never pushes), and grepathy distill/repair/off/on/uninstall.

Grepathy hooks directly into Claude Code's transcript and hook system (PreToolUse) and into git (branch-scoped why-files, commit on push). It has zero runtime dependencies and is pure TypeScript. Reading the output requires nothing beyond a markdown reader or grep; writing why-files currently requires Claude Code, with a Codex adapter planned as the next tool integration.

Teams using Claude Code for substantive feature work who need PR reviewers, teammates, and future agents to know why unreviewed decisions were made - before the only record of that reasoning (the chat transcript) is auto-deleted or lost to someone's local machine. It is licensed under MIT.