grepathy

grepathy command [options]

grepathy records the *why* behind agent-written code so humans and future agents can review decisions without digging through chat transcripts. It reads coding-agent session transcripts locally, extracts decisions, and writes a per-branch markdown file under .ai/why/ that you can commit with the code.It is designed to run via git/Claude Code hooks rather than mid-task agent logging: after work on a branch, grepathy distills a why-pack, shows it for human review, and respects permanent edits or deletions of entries. It does not block pushes, does not stage unrelated files, and never pushes for you. A pointer in project agent docs and a pre-edit hook can inject relevant why entries when an agent touches matching paths.Privacy-oriented: transcripts stay on the machine; only the sanitized markdown summary is meant for the repo. Summaries avoid quoting user messages, strip secrets, and pass deterministic scanners before you review.Writing why files currently targets Claude Code session data; anything can read the committed markdown. Requires Node.js 20+ for install and use via npx grepathy or a local build.

init

Install hooks and directories. Safe to re-run. May offer to backfill existing sessions.

Report distillation state and what looks stale.

Health checks for installation and configuration.

Print why-pack entries that apply to the given file or path.

Distill and commit why content immediately (still never pushes).

Run distillation without the full sync flow (see --help).

Repair grepathy state or hooks.

Temporarily disable or re-enable hooks.

Remove grepathy integration from the repository.

Does not stop agents from refactoring away important code; it only captures reasoning that is not visible in the source. Write-side support is Claude Code-oriented today. Why files are only as good as the summarizer and your review before commit. Empty or expired local transcripts cannot be recovered after the agent deletes them.

git(1), claude(1)

Source code