Skip to main content

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

CI PyPI License: PolyForm Noncommercial

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, the way the shipped rm guard does:

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, and go hook packs — guide
  • Testing — run uvx capt-hook test --json in 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.

Metadata

Release files for capt-hook 12.121.38

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for capt-hook 12.121.38
File Size Uploaded Provenance Actions
capt_hook-12.121.38.tar.gz 678.2 kB With provenance Details for capt_hook-12.121.38.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for capt-hook 12.121.38
File Interpreter ABI Platform Actions
capt_hook-12.121.38-py3-none-any.whl Python 3 none any Details for capt_hook-12.121.38-py3-none-any.whl

Total release size: 1.5 MB

Release files / capt_hook-12.121.38.tar.gz

Download URL capt_hook-12.121.38.tar.gz
Size 678.2 kB
Tags Source
SHA-256 checksum
How to use checksums
99c242f646abfd3624d1077fe9724ffe940a2afc876e89d1bc475fe593be0191
BLAKE2b-256 checksum
How to use checksums
bc3f4591ba92f0439958f7190b6ef5b22202a0e68613fa8459109146b74f2d0c
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 Nov 6, 2026.

Transparency log

Release files / capt_hook-12.121.38-py3-none-any.whl

Download URL capt_hook-12.121.38-py3-none-any.whl
Size 806.5 kB
Tags Python 3
SHA-256 checksum
How to use checksums
ebf95b1b8d78b6880bd0f792f92745b812ff1d8ab7fec599fdf129d52b663f4c
BLAKE2b-256 checksum
How to use checksums
4142ed9886d14e81d2fc1bc5978cc50bdd7b756d73d6bcb2bbe05fbfbc8e6859
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 Nov 6, 2026.

Transparency log

Security for capt-hook 12.121.38

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.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for capt_hook-12.121.38.tar.gz

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 Nov 6, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release
Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page