Are you the author? Sign in to claim
Claude Code hook that writes a forward-only why-block (decisions, trade-offs, assumptions, limitations) into your PR des
English · 简体中文 · 繁體中文 · 日本語 · 한국어 · Español · Português · Русский
Self-documenting PRs. A Claude Code hook that writes the why — decisions, trade-offs, assumptions, limitations — into every pull request, automatically. Composed by your own agent, on your own machine.
AI writes your code. Nobody writes down why. Three weeks in, your git history is a
pile of decisions you technically own but never actually made — the diff says what
changed, git blame says who, and the reasoning is just… gone.
This is a hook that fixes that at the source: right before your agent opens a PR (or lands a commit on your default branch), it writes a short "why" block — the decisions it made, the trade-offs it weighed, what it assumed, and what it knowingly left — straight into the description. From the actual session. Not the diff.
One command:
npx add-reasoning-to-prs
That copies the self-contained, zero-dependency hook to a stable location and registers
it in your Claude Code settings (~/.claude/settings.json) as a PreToolUse hook. No
build step, no account, no config.
Or install the Claude Code plugin from the marketplace (recommended — it registers the hook from the plugin manifest and updates with the plugin, without touching your project settings).
Requirements: Claude Code and Node.js ≥ 22.18. Claude Code only, for now — Cursor and Codex are next.
| Auto "why" block at PR-create | When your agent runs gh pr create (or commits to your default branch) without one, the hook asks it to write the block first, then re-run. Zero manual steps once it's installed. |
| Forward-only — never restates the diff | It captures what a diff can't show: the reasoning and the risks knowingly taken. It leads with the one point a reviewer couldn't get from the code, and never pads with "refactored X, improved Y". |
| Local, your own subscription, no account | The block is composed by your own agent, in-session. No server round-trip, nothing stored, and your source never leaves your machine. |
| Never fabricates | Every line has to trace to a real decision in the session. If the agent didn't actually deliberate, no block is added — an empty block is the correct answer for a routine change. |
Free and MIT, for good. Backthread — the paid hosted layer — does the cross-team, historical, and proactive-push parts a local hook structurally can't: the why pushed to you, searchable across your whole codebase, across everyone's agents. This hook needs none of that to be useful on its own. If you ever want the team view, it's at backthread.dev.
The hook watches for two moments: opening a PR (gh pr create) and landing a direct
commit on your default branch. When it sees one without a why-block, it asks your agent
to compose a grounded, forward-only block from its own session reasoning — the
Decisions, Trade-offs, Assumptions, and Limitations behind the change — and re-run
the command. The block is wrapped in an invisible marker, so it's written once and never
duplicated.
Each block carries a small visible attribution so reviewers can see where it came from — and you can edit or delete it freely.
git config add-reasoning-to-prs.disabled true[skip-why] anywhere in the command.ADD_REASONING_TO_PRS_DISABLE=1 in the environment you
launch Claude Code with.The honest state of the project — what works, what's next, and what it doesn't do yet.
gh pr create, the direct-push commit-message
fallback, multi-session carry-forward across a branch, 100% local (your own model, no
account), never-fabricate, and fail-open.The full list lives in Issues and Discussions — 👍 the limits that matter to you and they move up the list.
Contributions are welcome — especially bug fixes, sharper prompt/guidance copy,
edge-case coverage, and support for more agents. It's a small, single-purpose tool and
means to stay that way, so scope-broadening requests are usually declined (kindly, with
a reason). Start with the contributing guide and the
good first issue label; if you're unsure whether
an idea fits, open a Discussion first.
If this saves you one archaeological dig back through your own PRs, a ⭐ helps other people find it.
MIT © Backthread. Do whatever you want with it.
Hooking implementations and supporting tools for various coding agents (Claude, Cursor, Gemini, etc)
Claude Code hook toolkit that gives vision-blind models a text description of pasted/tool-produced images.
Hook-based token compressor for 5 AI CLI hosts (Claude Code, Copilot CLI, OpenCode, Gemini CLI, Codex CLI). Up to 95% ba
Blocks dangerous git and shell commands from being executed by AI coding agents