Stop repeating yourself to Claude. captain-hook mines your transcripts for the corrections you keep giving and opens PRs that turn each one into a typed, tested Python hook.
Get started
brew install --formula yasyf/tap/captain-hook
uvx capt-hook helper install
uvx capt-hook init
The formula fills the Cellar and helper install deploys the fixed, signed host at
~/Applications/Captain Hook.app; init scaffolds
.claude/hooks/, wires Claude Code's settings, and arms the session reviewer. Every event runs
the exact capt-hook build the installed app names — nothing resolves "latest" mid-session, and
the app keeps itself current in the background. One block_command later, a force-push dies
at PreToolUse and the hook's inline tests run green:
Driving with an agent? Paste this:
/plugin marketplace add yasyf/captain-hook
/plugin install captain-hook@captain-hook
Prefer a prompt over the plugin?
Install the `yasyf/tap/captain-hook` Homebrew formula, run `uvx capt-hook helper install`,
then run `uvx capt-hook init` in this repo, write one hook that blocks force-pushes,
and verify it with `uvx capt-hook test`. Read https://yasyf.github.io/captain-hook/
if you get stuck.
Use cases
Block force-push and rm -rf before they run
One bad Bash call rewrites shared history or eats a directory, and by the time you spot it in the transcript it already ran. Declare the block once, tests inline:
# .claude/hooks/safety.py
from captain_hook import Allow, Block, Input, block_command
block_command(
["git", "push", "--force"],
reason="Force-pushing rewrites shared history",
hint="Use `git push --force-with-lease` instead",
tests={
Input(command="git push --force"): Block(),
Input(command="git push origin main"): Allow(),
},
)
The next git push --force never executes: the agent sees BLOCKED: Force-pushing rewrites shared history plus the hint, and reaches for --force-with-lease instead. And when a pattern can't decide, walk the parse — this is the heart of the shipped rm guard:
for call in evt.command.calls("rm"):
if call.targets.expand().exhausted:
return evt.block("rm targets too broad to verify")
return call.sub("rm", "trash", args=call.targets)
evt.command is the parsed command line: every rm across && and pipes, each target resolved against the working directory, the rewrite quote-safe.
Turn repeated corrections into rules Claude can't forget
You've typed "use uv, not pip" in a dozen sessions, and session thirteen makes the same mistake. After init, the session reviewer reads each transcript as the session ends, keeps the corrections that are standing rules, and — once a pattern proves itself across sessions — opens a PR that codifies it as a hook. Watch the pipeline:
uvx capt-hook status
The dashboard lists every correction it's tracking, staged from first sighting to open PR. You review the PR like any other; merged hooks enforce the rule from then on.
Gate "done" until the tests actually pass
The agent declares victory while the suite is red. A Stop gate holds the line:
# .claude/hooks/quality.py
from captain_hook import RanCommand, Regex, TouchedFile, gate
gate(
"You edited Python files but never ran the tests. Run `uv run pytest` before finishing.",
only_if=[TouchedFile("**/*.py")],
skip_if=[RanCommand(Regex(r"\bpytest\b"))],
)
The agent can't end the turn until a pytest run shows up in the transcript, and the gate stands down on its own once one does.
More in the docs
- Interactive tutorial — block your first command in the browser, verified against the real engine — start it
- Session reviewer — the full corrections lifecycle, from transcript to merged hook PR — guide
- Conditions — typed filters over tools, files, commands, and transcript history — guide
- LLM hooks — gate on a model's verdict when a regex can't decide — guide
- Workflows — multi-step Stop gates with artifact checks and checklists — guide
- Packs — the shipped
general,python, andgohook packs — guide - Testing — run
uvx capt-hook test --jsonin CI so a regressed hook fails the build — guide - The inspiration — where this came from, and why steering agents belongs in tested hooks instead of prompts — check out the blog post
Read the docs for the full guide. Licensed under PolyForm Noncommercial 1.0.0, free for noncommercial use.
1 maintainer
Metadata
1 maintainer
Release files for capt-hook 12.94.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| capt_hook-12.94.0.tar.gz | 639.7 kB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| capt_hook-12.94.0-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 1.4 MB
Release files / capt_hook-12.94.0.tar.gz
| Download URL | capt_hook-12.94.0.tar.gz |
|---|---|
| Size | 639.7 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
2778b152a4ba4ddc8fd5439eb386cfe06e818fa987bde7f681c118f74aaa90f5
|
|
BLAKE2b-256 checksum How to use checksums |
27c5b25e4bca0d0c412a3f2d93c81234f1384c7417aab1c29e78636d4edc706f
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 14, 2026.
Transparency logRelease files / capt_hook-12.94.0-py3-none-any.whl
| Download URL | capt_hook-12.94.0-py3-none-any.whl |
|---|---|
| Size | 764.9 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
145b5d46c100042047f802e6f36c9ebeddeb9ded1df31cb5805d20c97a28d4be
|
|
BLAKE2b-256 checksum How to use checksums |
ac0ec8a585d86f37bd9967ddd290fc3cdf207c84b05a259afe1785a07c5b1120
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 14, 2026.
Transparency log
