Grepathy Auto-Documents Claude Code Architecture Decisions directly in Git
Grepathy parses local Claude Code transcripts via git hooks to extract undocumented agent decisions and saves them as Markdown files. This solves the 30-day retention limit of Claude transcripts, ensuring teammates and future agents understand the architecture.
Impact: High
Why it matters
You can now review and preserve every silent decision your coding agent makes without interrupting your vibe-coding workflow.
TL;DR
- 01Claude Code deletes your chat history after 30 days, losing crucial decision context.
- 02Grepathy automatically extracts these decisions upon git push.
- 03Historical summaries are fed back to future agents via pre-tool hooks.
Key facts
- Runtime Dependencies
- 0 (Pure TypeScript)
- Transcript Retention
- 30 days (Claude Code default)
- Supported Tools
- Claude Code (Codex upcoming)
The Vanishing History Problem
Coding agents like Claude Code perform dozens of micro-decisions during a feature build. By default, Claude Code deletes local session transcripts after 30 days, leaving developers with zero context when reviewers ask why a certain architecture path was chosen.
How Grepathy Automates Context
Instead of asking the LLM to write logs mid-task, Grepathy hooks into git push. It parses local chat histories, filters secrets, and distills the logic into .ai/why/ directory. If an agent edits a file that matches a touched path glob, Grepathy's PreToolUse hook automatically injects the historical reasoning back into the active prompt context.
Evaluation Results and Integration
In blind evals, agents supplied with Grepathy's why-pack significantly outperformed baseline runs by avoiding hallucinations regarding undocumented design patterns. It requires zero servers and relies purely on TypeScript with zero runtime dependencies.
Try it in 2 minutes
npm install -g grepathy
grepathy initbash
✓ When to use
- When using Claude Code for continuous autonomous development
- To share agentic design decisions with human code reviewers
- To prevent long-term transcript data loss on local machines
✕ When NOT to use
- If you only use web UI-based LLM chats
- For non-git projects with no version control workflow
What to do today
- Install grepathy globally
- Run grepathy init inside your active Claude Code project
- Verify the pre-push hook configuration
What the community says
“Amazing to me how little these companies respect the historic value of the transcripts. Most of my work is captured in them now.”
Sources