sequential-hooks

sequential-hooks runs coding-agent hooks in a strict order. Without a wrapper, a host may start several hooks concurrently or in an undocumented order. A validator can then inspect an old tool input while another hook is still replacing it. Register one wrapper hook and place the former hook commands inside it as ordered steps.

Installation

sequential-hooks requires native CPython 3.13 or newer. Install the current checkout from the repository root with uv:

uv tool install .

To update an existing installation after pulling changes:

uv tool install --reinstall .

make install and make reinstall run the same commands.

Quick start

sequential-hooks has no configuration file. Choose the coding agent that will run the wrapper, then add the registration from its setup guide:

• Claude Code
• Codex
• Antigravity

Check compatibility for supported hosts and known host limits, and platforms for process handling. The guides use first-hook, second-hook, and audit-hook as sample child commands. Replace them with hooks you have installed and want to run in order. Move those child hooks into the wrapper and remove their separate registrations, or the host may still start duplicate copies concurrently.

The wrapper command expects a native host payload on stdin. Configure it as a host hook rather than running the hook command interactively. After saving the registration, inspect it with the matching read-only report:

sequential-hooks doctor --agent claude
sequential-hooks doctor --agent codex
sequential-hooks doctor --agent agy

Exit 0 means the findings are informational. Exit 1 means at least one warning or error is present. Some warnings describe inspection limits and persist after host-side review. The troubleshooting guide explains common findings.

Antigravity requires an explicit event in each hook command. An all-neutral Antigravity pre-tool chain emits the host's real automatic allow decision; it does not preserve the ordinary permission prompt. Review the Antigravity setup guide before enabling it.

How commands compose

-a, --agent selects the installed host adapter for a coding agent. The built-in names are claude, codex, and agy; a third-party adapter installed with uv tool install . --with PACKAGE is selected by its own name. Nothing is inferred from the payload. See adding a host.

-h, --help prints help for wrapper mode; doctor -h and doctor --help print doctor help.

sequential-hooks --agent codex --step-timeout 30 first-hook --agent codex -- second-hook --agent codex

The exact -- token separates steps and cannot be passed to a step. Each child receives its own literal arguments, including its own --agent; wrapper options are not inherited by child commands.

Documentation

Development

See the development guide for the required tools, CI, and dependency locks. With those tools installed, run:

make setup
make check

License

sequential-hooks is available under the MIT License.