HookStack — Claude Code Hooks Catalogue
Your AI agent runs fast. Hooks keep it honest.
A catalogue of production-ready Claude Code hooks — also for OpenAI Codex and GitHub Copilot.
Install them in one command — your agent gets guardrails in under a minute.
Unit-test coverage (agrégat) · gate CI : lines/statements/branches ≥ 80 %, functions ≥ 75 %
Installation
Installation takes under a minute.
npx hookstack-cli@latest install
That's it. The CLI detects your project's setup — its language stack (no Biome in a pure Python project, no google-java-format in a pure JS project) and the systems it uses (i18n, an okf/ knowledge bundle, Next.js, a front-end codebase, a GitHub-hosted repo, a test suite, Claude Code skills, a hook registry, a system TTS voice, a Slack webhook, a multi-surface docs setup) — then walks you through picking hooks, writes the hook scripts (.mjs, or .py variants on Python projects), and patches the right config file. No manual copy-paste, no JSON editing. The interactive menu lets you pick your target agent; --no-detect skips detection.
Want to fine-tune your Hookstack? Go to hookstack.app — browse the full catalogue, select exactly what you need, copy the generated command and paste it in your terminal
Language-aware by default. The CLI detects your project's toolchain (TypeScript/Node: package.json/tsconfig.json · Python: pyproject.toml/requirements.txt/… · Java: pom.xml/build.gradle/gradlew) and only installs hooks that match it — a Python repo gets the ruff/pyright/pytest stack, a Java repo the google-java-format/compile/test stack, never hooks that shell out to another ecosystem's tools. Mixed repos get both. When no TypeScript/Python/Java toolchain is detected (Go, Rust, bare JS…), only the universal hooks are installed — never tsc/biome/ruff/pytest/java hooks the project can't run — and the CLI says so. Override with --stack=typescript|python|java|all or --no-detect.
Python hooks, Python tests. On a Python project the hooks are installed as real .py scripts (python3 … commands) and --with-tests writes pytest tests instead of vitest tests — vitest is never installed on Python projects, so your GitHub Actions CI stays Python-only with no npm added to test the hooks. Every hook in the default stack carries a Python variant: a default Python install currently lands 63 hooks, 100 % as .py, zero .mjs fallback (see the install summary).
Same gates, everywhere. --pre-commit adds a git pre-commit hook, and --github-action adds CI — both replay the exact same quality/test gates your agent runs at Stop, so the agent, your terminal, and GitHub all enforce one identical set of checks. See the breakdown →
# In a Python project — ruff format, ruff check, pyright, pytest, uv guard
npx hookstack-cli@latest install
# Force one toolchain, or install everything regardless of the detected stack
npx hookstack-cli@latest install --stack=typescript
npx hookstack-cli@latest install --stack=java
npx hookstack-cli@latest install --stack=all
The same gates, everywhere
HookStack's quality gates aren't just for your agent. One install can wire the exact same checks into three surfaces, all driven by the same hook scripts — so they can never drift apart:
| Surface | When it fires | Enable with | What it checks |
|---|
| 🤖 Agentic session | at Stop, automatically | the default install | changed files |
| 💻 Your terminal | git commit | --pre-commit | changed files |
| ☁️ GitHub CI | every PR & push to main/master | --github-action | the whole repo |
npx hookstack-cli@latest install --pre-commit # gates on every git commit
npx hookstack-cli@latest install --github-action # gates on every PR & push
npx hookstack-cli@latest install --pre-commit --github-action # all three
- One source of truth. The pre-commit and the workflow call the installed hooks themselves — no duplicated
tsc/biome/ruff/pytest commands to keep in sync.
- Toolstack-aware & cross-OS. A Python project gets ruff/pyright/pytest, a TypeScript project gets tsc/biome + its test runner. POSIX
sh with a python3 → python fallback covers macOS, Linux, and Windows (Git Bash).
- Never clobbers you. Your own pre-commit is appended to, not replaced; a
hookstack-gates.yml that isn't ours is left untouched.
- You validate. Interactive installs list the gates and ask y/N before writing anything;
--yes --pre-commit --github-action installs both non-interactively.
See packages/cli/README.md → Same gates, everywhere for the full reference.
Updating
npx hookstack-cli@latest update
No need to remember which hooks you picked — the CLI reads the @hookstack <slug> fingerprint each installed script carries (// @hookstack on .mjs, # @hookstack on .py variants), re-fetches those exact hooks from the live registry, and overwrites only the scripts that changed. settings.json is re-merged but only actually touched if a hook's config fragment changed (the merge is idempotent). Installed somewhere other than the default project scope? Pass the same flag you installed with, e.g. update --global or update --codex-project. See packages/cli/README.md for the full breakdown.
Contributing changes back
Edited a hook in your own project and think the catalogue should have it too?
npx hookstack-cli@latest contribute
It finds the hooks you've locally modified and opens a PR with your changes — forking this repo for you, or pushing a branch straight to it when your gh account owns it (no fork needed). Hooks are detected by their @hookstack fingerprint, so even renamed local files get contributed under their canonical name, and locally edited unit tests (tests/hooks/) ride along with their hook so the contribution keeps the CI coverage gate green. No manual git/GitHub dance required. Requires the GitHub CLI (gh), already authenticated. See packages/cli/README.md for details.
The HookStack evolution
106 hooks and counting — every one dogfooded on this repo, unit-tested, and shipped in public.
First hook 2026-05-29 · latest 2026-09-02 · explore the live timeline → hookstack.app/evolution
Latest additions
→ Full timeline on hookstack.app/evolution
Promise
Install a production-ready HookStack in one command — up and running in 60 seconds, on Claude Code, OpenAI Codex, or GitHub Copilot.
How it works
The moment your agent starts a session, it knows absolutely nothing about your environment. It doesn't know which branch you're on, doesn't know your .env has secrets, doesn't know that rm -rf / is a terrible idea. It just runs.
Hooks change that.
A hook is an ordinary Node.js script wired into the agent lifecycle via a config file. No SDK, no plugin system — just events. When the agent is about to run a shell command, a PreToolUse hook fires first. It reads the full command, and it can block it. When the agent writes a file, a PostToolUse hook can reformat it automatically. When a long task finishes, a Stop hook can ping your phone.
Hookstack is the catalogue of these scripts — written, tested, and ready to install. You pick the ones you want, run one npx command, and your project gets a hooks folder and a patched config file. Done.
Agent-agnostic by design. Claude Code, OpenAI Codex, and GitHub Copilot share the same lifecycle event model, so the hook code is identical across all three — only the config file format differs (.claude/settings.json vs .codex/hooks.json). Write a hook once, deploy it on whichever agent you (or your team) run.
The result: your agent still moves fast. It just can't do the dumb things anymore.
Sponsorship
If Hookstack has saved your production secrets or stopped a runaway rm -rf, I'd love it if you'd give the repo a star or sponsor the work.
Thanks!
— Steve
The Lifecycle
Hooks fire at 25 distinct points in the Claude Code agent loop. Here is how the most important ones fit together:
1. SessionStart — set the stage
Fires the instant a session opens. Use it to inject context: current branch, recent commits, open issues. Your agent starts informed instead of cold.
2. PreToolUse — intercept before it's too late
Fires before any tool executes and can block it outright. The right place for security: secrets in commands, destructive filesystem ops, pushes to main, writes to .env. The agent sees your reason and adjusts — it doesn't just get a wall.
3. PostToolUse — observe and react
Fires after a tool completes, non-blocking. Run Biome + Prettier after every file write. Record what the agent touched. Validate that the file it wrote actually parses. The agent keeps moving; the hook handles the cleanup.
4. Stop / StopFailure — close the loop
Fires when the agent finishes (success or failure). Ping Slack. Send a push notification. Write a session summary to disk. The work is done — now you find out about it.
5. WorktreeCreate — bootstrap new environments
Fires when a new worktree is created. Copy .env, assign a free port, run pnpm install. Every worktree starts ready, not broken.
What's Inside
Security
- pre-bash-secret-detection — Catches API keys, tokens, and passwords before any shell command runs
- pre-write-secret-detection — Blocks the agent from hardcoding a secret into any file it writes
- pre-bash-block-destructive — Blocks
rm -rf /, DROP TABLE, direct disk writes, and other foot-guns
- pre-edit-protect-paths —
.env and key files stay untouched by the agent, always
- pre-read-env-guard —
.env secrets never enter the model context in the first place
- pre-bash-guard-force-push-any — Blocks bare
git push --force, steering you to --force-with-lease
Context
- session-start-load-git-context — Injects current branch, status, and last commit at session start
- session-start-github-context — Open PRs and CI check status loaded before you ask
- worktree-create-setup-env — Copies
.env, assigns a free port, runs install — every worktree, every time
- pre-read-file-to-markdown — Read any PDF, DOCX or PPTX as clean Markdown — slash token usage
Validation
- stop-per-file-coverage — After each session, flags any file touched without test coverage ≥ 80 %
- stop-per-file-lint — Biome runs on every file the agent modified before Stop fires
- post-write-biome — Biome formats and lints silently after every Write or Edit
- pre-bash-enforce-package-managers — Blocks
npm or yarn commands when the project uses pnpm
- post-edit-typecheck — Runs
tsc --noEmit on touched TypeScript files right after an edit
- post-edit-conflict-marker-check — Leftover merge conflict markers caught the moment a file is written
Notification
- notification-slack — Pings your Slack when the agent needs you mid-session
- stop-tts-completion — Get told out loud the moment work is done
Workflow
- session-start-worktree-if-main — Start a session on
main and you're moved to a fresh worktree
- post-bash-command-log — A full history of every command Claude ran
- registry-changed-auto-sync — Re-syncs
registry.json whenever a hook .mjs is edited (meta: powers this repo)
Documentation
Philosophy
- Hooks are not plugins. They are ordinary shell scripts. No SDK, no agent modification — just events and
settings.json.
- Block early, not late. A
PreToolUse hook that stops a bad command costs nothing. A runaway rm -rf costs everything.
- Zero overhead by default. Hooks that don't match exit in milliseconds. A
PostToolUse hook that can't find Biome is silent, not crashing.
- Tested like production code. Every hook in the catalogue ships with a Vitest unit test. The CI gate rejects any hook without coverage ≥ 80 %.
- Dogfooded. The hooks in this catalogue are active on this very repository. They run on every Claude Code session that touches
hookstack. Bugs surface fast.
Contributing
See CONTRIBUTING.md for the full guide: local setup, hook authoring contract, registry metadata, CI gates, and the pull request process.
Quick path for adding a hook:
# 1. Write the script
touch .claude/hooks/<slug>.mjs # follow the run() + guard pattern
# 2. Write the test
touch tests/hooks/<slug>.test.mjs # coverage ≥ 80 % required
# 3. Add metadata to registry/registry.json, then sync
node .claude/sync-hooks.mjs
# 4. (Optional) ship a Python variant for pure-Python installs
touch .claude/hooks/<slug>.py # same run() contract, stdlib only
# 5. Open a PR — CI runs typecheck, tests, schema validation, and drift checks
Run locally
git clone https://github.com/steve-magne/hookstack.git
cd hookstack
pnpm install
pnpm dev # → http://localhost:3000
# pnpm typecheck \
# pnpm lint > Don't need those — Hookstack does it for you.
# pnpm test /
pnpm build # Production build
| Layer | Technology |
|---|
| Framework | Next.js 15 — App Router, Server Components |
| Language | TypeScript 5.x |
| Styling | Tailwind CSS v4 |
| Animations | Motion (ex-Framer Motion) — springs, split-flap, FLIP |
| State | Zustand — persisted selection |
| CI enrichment | GitHub Actions + Claude Code (ANTHROPIC_API_KEY) |
| Package manager | pnpm 9.x |
Guides
Five short guides on Claude Code hooks — from first principles to production debugging:
- What are Claude Code hooks? — the concept explained in plain language: what an event is, how settings.json wires it, and when to reach for a hook vs a slash-command.
- PreToolUse vs PostToolUse — when to block (PreToolUse) vs when to observe and react (PostToolUse), with concrete examples of each.
- Claude Code hooks vs slash commands — the two extension points compared: trigger model, blocking capability, and the right choice for each use-case.
- Claude Code hooks not working? — a practical troubleshooting checklist: permissions, shebang, stdin parsing, exit codes, and the most common mistakes.
- Write your first Claude Code hook — a step-by-step walkthrough from an empty
.mjs to a tested, wired hook in under 10 minutes.
Community
Hookstack is built by Steve Magne with contributions from the Claude Code community.
