Claude Code hooks

Hover ships a second bin, hover-hook, that wires its deterministic checks into Claude Code's hook events. The MCP is what the agent calls; the hooks are what fire automatically around the agent loop — no AI, no browser, running at the right moments so the agent starts oriented and finishes honest.

Install

The hover-hook bin comes with @hover-dev/mcp. Install it once per repo:

npm i -g @hover-dev/mcp@latest   # ships the hover-hook bin
hover-hook install               # run in your repo

install merges a Hover block into .claude/settings.json (creating it if needed) without touching your other hooks, then tells you to reload. It's idempotent — re-run any time and it replaces only its own block. Reload Claude Code (or restart the session) to activate.

What it wires

Three hooks, all zero-AI:

• SessionStart → orientation. At the start of a session, the hook reads your active environment and (if you're signed in) Hover Cloud, and injects a short context block: the active environment + URL a drive/heal targets, the connected Cloud project, and any specs that drifted in CI — each with /mcp__hover__heal <slug>. The agent begins already knowing the state of your suite, without you saying a word. It's the proactive form of the cloud_context tool.
• UserPromptSubmit → guard-first nudge. When a prompt looks like new behavior (a verb like add / build / implement plus a feature-ish noun), the hook suggests declaring the contract first: /mcp__hover__guard to record the acceptance criteria + business rules, then /mcp__hover__build to drive it to green — so the change lands with a crystallized regression, not just code. The heuristic is deliberately conservative so it doesn't nag.
• Stop → end-of-turn wiki health. When the turn ends, the hook runs the deterministic .hover/ lint (no browser): a business-map line pointing at a deleted spec, a covered line whose spec last ran red (a heal candidate), a spec no line maps. If anything's off, it surfaces the issues with a heal hint.

It stays out of the way

hover-hook calls no model and touches no browser. On any error it prints {} and exits 0, so a hiccup never blocks your session. Only install writes files.

Adding your own hooks

The subcommands (session-start, user-prompt, stop) are plain commands, and Claude Code's hook system is general, so you can wire stronger gates yourself. Common additions:

• PostToolUse on mcp__hover__crystallize_spec — the moment a spec is saved, replay it to confirm it's green (a record == replay self-check), and git add it.
• Stop as a hard gate — run your regression and return {"decision":"block","reason":"…"} (or exit 2) so "done" means the suite is deterministically green, not that the agent felt finished. Claude Code caps consecutive blocks and sets stop_hook_active to prevent loops.
• PreToolUse on Bash(git push*) — deny the push while specs are still drifted.

For the reasoning behind each of these, see Hooks that make the agent finish green.