Skip to content

Hooks

Hooks run at agent lifecycle events (session start, before shell, after file edit, and more). You declare them once; CAPA translates each hook into the provider-specific config shape and tags its entries as capa:<id> so install/clean stay surgical.

Edit hooks in the capabilities file, or use the CLI:

Terminal window
capa add --hook --id audit-shell --on beforeShell --command 'date >> ~/.capa/audit.log'
capa add --hook --id greet --on sessionStart --type prompt --prompt 'Remember project conventions.'
capa install

See CLI: add for source flags (--source, --command, --prompt, --type).

FieldNotes
idStable id → capa:<id> in provider configs
onCanonical event (beforeShell, afterFileEdit, …) or provider-scoped (cursor:beforeShellExecution)
typecommand (default) or prompt
command / promptInline body when you do not use source
sourceinline, remote, github, gitlab, or local (path in the project)
matcher, timeout, failClosed, sequential, providersOptional controls; failClosed is Cursor-oriented today

Canonical events include sessionStart, sessionEnd, userPromptSubmit, beforeTool, afterTool, afterToolFailure, beforeShell, afterShell, beforeFileRead, afterFileEdit, beforeMcpCall, afterMcpCall, subagentStart, subagentStop, preCompact, and stop.

hooks:
- id: audit-shell
description: Timestamp every shell invocation
on: beforeShell
command: 'date >> ~/.capa/audit.log'
timeout: 5
- id: block-rm-rf
on: cursor:beforeShellExecution
matcher: 'rm -rf *'
failClosed: true
command: 'echo "blocked" && exit 1'
- id: log-bash-commands
on: beforeShell
source:
type: local
path: scripts/log-bash.sh

Non-local sources are materialized under ~/.capa/hooks/<projectId>/. source.type: local references your project file in place (no copy; capa clean will not delete it).

CAPA installs hooks only for providers that support them. Unsupported providers get a warning and are skipped: install does not fail.

ProviderConfig file
Antigravity.agents/hooks.json
Claude Code.claude/settings.json → hooks
Codex.codex/config.toml → [hooks]
Cursor.cursor/hooks.json
Gemini CLI.gemini/settings.json → hooks

matcher is written in each provider’s native field: for Cursor that is matcher on the hook entry (use it, for example, to filter postToolUse to Write|Edit).

Re-installs and capa clean edit only entries tagged capa:<id>. If several CAPA hooks share one config file, CAPA still finds and removes each of its entries even after earlier ones were removed or moved, so no stale CAPA entries are left behind.

On Claude Code and Codex, beforeMcpCall / afterMcpCall install on PreToolUse / PostToolUse with the matcher mcp__.*. (Older releases wrote mcp__, which Claude Code treats as an exact tool name, so those hooks never fired there. Re-run capa install to rewrite them.)

A hook of yours, or one from a plugin, that already names a single MCP server keeps that scope. For example matcher: 'mcp__github__.*' (also written ^mcp__github__.*$) stays limited to the github server instead of widening to every MCP tool:

hooks:
- id: audit-github
on: beforeMcpCall
matcher: 'mcp__github__.*'
command: './hooks/audit-github.sh'

Antigravity’s .agents/hooks.json is keyed by hook name, not by event, so each CAPA hook becomes its own top-level capa:<id> key. Re-installs and capa clean touch only those keys.

{
"capa:lint": {
"PostToolUse": [
{ "matcher": "run_command", "hooks": [{ "type": "command", "command": "./lint.sh", "timeout": 10 }] }
]
}
}
  • Only type: command hooks are supported; type: prompt hooks are skipped with a warning, and failClosed is ignored.
  • Mapped events: beforeTool, afterTool, beforeShell, afterShell, beforeFileRead, afterFileEdit, and stop. Other canonical events, including beforeMcpCall / afterMcpCall, are not mapped. Target Antigravity events directly with the provider-scoped form, for example on: antigravity:PreInvocation.
  • If you set "enabled": false on a capa:<id> key, it stays disabled across re-installs.