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 init
The formula 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, 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, 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(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
Read the docs for the full guide. Licensed under PolyForm Noncommercial 1.0.0, free for noncommercial use.
1 maintainer
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Filter files by name, interpreter, ABI, and platform.
If you're not sure about the file name format, learn more about wheel file names.
Copy a direct link to the current filters
File details
Details for the file capt_hook-12.22.4.tar.gz.
File metadata
- Download URL: capt_hook-12.22.4.tar.gz
- Upload date:
- Size: 362.8 kB
- Tags: Source
- Uploaded using Trusted Publishing? Yes
- Uploaded via:
twine/7.0.0 CPython/3.13.14
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
b1dbd1bae7479b748ba1a7619e4289afcef930ee5dd0f1326f7e9484e8184658
|
|
| MD5 |
bec1c567c7143df7eed3d6d5b92ff493
|
|
| BLAKE2b-256 |
f5f528d306b871197b4ecc7cadf27a77ae987dbc86ed1e83e515139aae731aaa
|
Provenance
The following attestation bundles were made for capt_hook-12.22.4.tar.gz:
Publisher:
release-pypi.yml on yasyf/captain-hook
-
Statement:
-
Statement type:
https://in-toto.io/Statement/v1 -
Predicate type:
https://docs.pypi.org/attestations/publish/v1 -
Subject name:
capt_hook-12.22.4.tar.gz -
Subject digest:
b1dbd1bae7479b748ba1a7619e4289afcef930ee5dd0f1326f7e9484e8184658 - Sigstore transparency entry: 2646632330
- Sigstore integration time:
-
Permalink:
yasyf/captain-hook@b7890c8bb4faf54a280e0a151dfdc9bdc4591cb0 -
Branch / Tag:
refs/tags/v12.22.4 - Owner: https://github.com/yasyf
-
Access:
public
-
Token Issuer:
https://token.actions.githubusercontent.com -
Runner Environment:
github-hosted -
Publication workflow:
release-pypi.yml@b7890c8bb4faf54a280e0a151dfdc9bdc4591cb0 -
Trigger Event:
push
-
Statement type:
File details
Details for the file capt_hook-12.22.4-py3-none-any.whl.
File metadata
- Download URL: capt_hook-12.22.4-py3-none-any.whl
- Upload date:
- Size: 456.1 kB
- Tags: Python 3
- Uploaded using Trusted Publishing? Yes
- Uploaded via:
twine/7.0.0 CPython/3.13.14
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
21e6c00cb8e6408ea63a1b8e8a5bfa49bfec587df3b34f431da51125915fc7d8
|
|
| MD5 |
e2ba7657d6e7abd29a95be38b8dbba63
|
|
| BLAKE2b-256 |
2d6de75f74b9b7e208461b443206e90d0a9bcfa91ee003045244afd879ec382a
|
Provenance
The following attestation bundles were made for capt_hook-12.22.4-py3-none-any.whl:
Publisher:
release-pypi.yml on yasyf/captain-hook
-
Statement:
-
Statement type:
https://in-toto.io/Statement/v1 -
Predicate type:
https://docs.pypi.org/attestations/publish/v1 -
Subject name:
capt_hook-12.22.4-py3-none-any.whl -
Subject digest:
21e6c00cb8e6408ea63a1b8e8a5bfa49bfec587df3b34f431da51125915fc7d8 - Sigstore transparency entry: 2646632376
- Sigstore integration time:
-
Permalink:
yasyf/captain-hook@b7890c8bb4faf54a280e0a151dfdc9bdc4591cb0 -
Branch / Tag:
refs/tags/v12.22.4 - Owner: https://github.com/yasyf
-
Access:
public
-
Token Issuer:
https://token.actions.githubusercontent.com -
Runner Environment:
github-hosted -
Publication workflow:
release-pypi.yml@b7890c8bb4faf54a280e0a151dfdc9bdc4591cb0 -
Trigger Event:
push
-
Statement type:
