Skip to content

captain-hook

Declarative hooks for Claude Code. Define rules that intercept tool calls, enforce policies, and guide agent behavior — in pure Python.

from captain_hook import block_command

block_command(["git", "stash"], reason="Use jj instead", hint="Run `jj shelve`")

That's it. One line blocks git stash across your entire project.

  • Declarative by default

    Most hooks are a single function call. No classes, no boilerplate, no YAML. Define what to block, warn, or enforce — captain-hook handles the rest.

  • Composable conditions

    Filter hooks with typed conditions: match tools, file paths, commands, transcript history, and more. Combine with only_if / skip_if for precise targeting.

  • LLM-powered evaluation

    Gate or nudge with LLM verdicts. Signal scoring detects patterns in transcript text, then an LLM decides whether to intervene.

  • Inline testing

    Test hooks where you define them. Input(command="git stash") / Block("jj") — run with capt-hook test.

  • Multi-step workflows

    Enforce checklists before the agent stops. Tests, linting, artifacts — each step must pass before the agent can proceed.

  • Rich transcript API

    Query conversation history with a typed API. Filter tool uses, extract commands, check what files were edited or read.

Get started

uv add capt-hook

capt-hook init

from captain_hook import gate, RanCommand

gate("Run tests before stopping", skip_if=[RanCommand(r"pytest")])

Installation Quickstart