Grepathy captures the agent decisions your repo forgot

Code review gets awkward when an agent slips in design choices nobody explicitly approved. Grepathy is a new CLI that tries to fix that by extracting those decisions from Claude Code session transcripts and saving them as markdown files in the repo.

The pitch is simple: when a reviewer asks why a change was made, the answer should live next to the code, not in a chat log on one developer’s machine. That matters because Claude Code deletes transcripts after 30 days by default.

What Grepathy does

Grepathy reads transcripts locally, identifies decisions made during an agent session, and writes them into a branch-specific file at .ai/why/<branch>.md. Those summaries are meant to survive beyond the original session and give reviewers, teammates, and future agents a record of the reasoning behind a change.

Recommended reading

Hinge founder Justin McLeod readies Overtone AI matchmaker

The project’s example comes from a contract job where an agent chose to pre-create guest users in Clerk without that being requested in the plan or prompts. The CTO later asked why it was done. The developer didn’t know, because the decision had been made by the agent.

With Grepathy, that decision would have been captured as a repo-visible entry, including:

• Status: agent-initiated
• Touches: lib/clerk/*, db/schema/guests.ts
• inferred rationale
• reviewer attention points
• explicit risk notes

That also makes it easy to search for unapproved agent choices with commands like grep -rn “agent-initiated” .ai/why/.

Hooked into the workflow

Grepathy is designed to run through hooks rather than as a separate tool developers have to remember to launch. The intended flow is:

• run claude and work normally
• let the agent commit as it goes
• on git push, Grepathy writes the why file and shows it for review

According to the project, it never blocks a push, never touches your staging area, and never pushes anything itself. It also supports multiple agents and worktrees.

There are two ways future agents get this context. A note in CLAUDE.md points them to the why files at session start, and a PreToolUse hook injects relevant entries right before an agent edits a file with matching history.

Privacy and limits

The project says transcripts stay on the local machine. The only shared output is the markdown summary, and the summarizer is described as following strict rules:

• it never quotes user messages
• it never describes confusion or back-and-forth
• it never includes business or money details
• it strips secrets

The writeup also says two deterministic checks sit behind the prompt: a secret/finance scanner and a rule that every entry must point at real code. Users review the file before pushing, and if an entry is edited or deleted, Grepathy respects that forever.

Where it helps — and where it doesn’t

The author says the team ran a blind, pre-registered eval against a baseline and published the results in docs/REPORT.md, including cases where the tool lost.

The strongest use cases are narrow but concrete. Grepathy helps preserve reasoning before transcripts disappear, and it can capture decisions that never show up in code, like rejecting a CDN or noting that an agent acted on its own. In those tests, agents with the why file could answer correctly; agents without it produced plausible but wrong explanations.

The project is also candid about what it does not solve. It won’t stop an agent from refactoring away important code, and it doesn’t make agents smarter in general. If the answer is already obvious from the code, the author says agents do fine without it.

Commands and compatibility

Key commands include grepathy init, status, doctor, context <path>, and sync. The tool can also backfill old sessions if transcripts are still available.

For now, writing these summaries requires Claude Code, though any tool can read the markdown files once they exist. The author says a Codex adapter is next.

Under the hood

Grepathy is released under the MIT license and built with pure TypeScript with zero runtime dependencies. The project says its tests are hermetic, with the LLM mocked and git running in temporary repos, so npm test works anywhere with Node >= 20 and git.

That focus on durable, repo-level context is the core bet here: not making agents better at coding, but making their unasked-for decisions visible before the transcript that explains them disappears.