capt-hook

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:

Animated terminal: a hook blocks git push --force at PreToolUse, then 'uvx capt-hook test' passes both inline tests

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, 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.

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

capt_hook-12.26.0.tar.gz (368.8 kB view details)

Uploaded Sep 3, 2026 Source

Built Distribution

If you're not sure about the file name format, learn more about wheel file names.

The dropdown lists show the available interpreters, ABIs, and platforms. Enable javascript to be able to filter the list of wheel files.

capt_hook-12.26.0-py3-none-any.whl (463.1 kB view details)

Uploaded Sep 3, 2026 Python 3

File details

Details for the file capt_hook-12.26.0.tar.gz.

File metadata

Download URL: capt_hook-12.26.0.tar.gz
Upload date: Sep 3, 2026
Size: 368.8 kB
Tags: Source
Uploaded using Trusted Publishing? Yes
Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for capt_hook-12.26.0.tar.gz
Algorithm	Hash digest
SHA256	`143b584096db5162fb8de1d38419c102bb0ce1bd143dda5052f3a02b2e2cc312`
MD5	`30dbca759d79af79008e2ecbfaf79c9a`
BLAKE2b-256	`a6f543cedb558960605ab632693b595a6f71d0f863d99088afccf6195202fd95`

See more details on using hashes here.

Provenance

The following attestation bundles were made for capt_hook-12.26.0.tar.gz:

Publisher: release-pypi.yml on yasyf/captain-hook

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Statement:
- Statement type: https://in-toto.io/Statement/v1
- Predicate type: https://docs.pypi.org/attestations/publish/v1
- Subject name: capt_hook-12.26.0.tar.gz
- Subject digest: 143b584096db5162fb8de1d38419c102bb0ce1bd143dda5052f3a02b2e2cc312
- Sigstore transparency entry: 2702312399
- Sigstore integration time: Sep 3, 2026
Source repository:
- Permalink: yasyf/captain-hook@658ff058f0a3cc88644a4b89be47e9767b1f3a19
- Branch / Tag: refs/tags/v12.26.0
- Owner: https://github.com/yasyf
- Access: public
Publication detail:
- Token Issuer: https://token.actions.githubusercontent.com
- Runner Environment: github-hosted
- Publication workflow: release-pypi.yml@658ff058f0a3cc88644a4b89be47e9767b1f3a19
- Trigger Event: push