Declarative hooks for Claude Code

captain-hook

Declarative hooks for Claude Code — rules as data, tested inline.

AI / Agents

Skills
llms.txt
llms-full.txt

Developers

Yasyf Mohamedali

Maintainer

Community

Full license

Meta

Requires: Python >=3.12
Provides-Extra: dev

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