Hooks
Declare a hook once in tackroom.yaml and sync registers it in every harness that has a hook surface, using that harness's event names. tackroom hook list shows what is registered natively, including entries tackroom did not write.
tackroom sync # register the hooks you declared
tackroom hook list # every native registration, managed or not
tackroom hook remove --dry-run <query>
Declare a hook
There is no hook add command yet: write the entry in hooks: of tackroom.yaml, or in tackroom.local.yaml for one machine. A hook with the same name in the local file replaces the shared one.
hooks:
- name: notify-stop
enabled: true # entries stay off unless enabled
event: Stop # Claude Code event names
command: ~/.agents/hooks/notify.sh
timeout: 10 # seconds; omit for the harness default
agents: [claude, codex, gemini] # optional; default: every harness with hooks
nameis unique andeventandcommandare required.timeoutis in seconds and cannot be negative.commandis written as given and run by the harness. tackroom does not create the script, so it has to exist on every machine that syncs the hook.agentsuses harness keys. Without it, harnesses that have no hook surface are skipped silently.- Event names are Claude Code's. Each harness below gets its own name for the event, or reports it as unsupported.
A memory tool's hook is declared the same way; memory.md has one. Memory hooks that an older tackroom setup --memory wrote are ordinary hooks now.
Which harnesses run hooks
Twelve harnesses get hooks. OpenCode, DeepSeek Harness and Amp have no hook surface, and Devin loads Claude Code's hooks itself; tackroom writes nothing for those four.
| Harness | Written to | Events |
|---|---|---|
| Claude Code | ~/.claude/settings.json |
Any, as given |
| Codex | ~/.codex/hooks.json |
Any, as given |
| Factory Droid | ~/.factory/hooks.json |
Any, as given |
| Qwen Code | ~/.qwen/settings.json |
Any, as given |
| Grok Build | ~/.grok/hooks/tackroom.json |
Any, as given |
| Gemini CLI | ~/.gemini/settings.json |
See below |
| Cursor | ~/.cursor/hooks.json |
See below |
| GitHub Copilot CLI | ~/.copilot/hooks/tackroom.json |
SessionStart, SessionEnd, UserPromptSubmit, PreToolUse, PostToolUse, PostToolUseFailure, Stop, SubagentStop, ErrorOccurred, PreCompact |
| Antigravity CLI | ~/.gemini/config/hooks.json |
SessionStart, Stop, PreToolUse, PostToolUse |
| Kimi Code | ~/.kimi-code/config.toml |
SessionStart, SessionEnd, UserPromptSubmit, PreToolUse, PostToolUse, Stop, SubagentStop, PreCompact |
| Pi | ~/.pi/agent/extensions/tackroom-<name>.ts |
SessionStart, SessionEnd |
| OMP | ~/.omp/agent/hooks/post/tackroom-<name>.ts |
SessionStart, SessionEnd |
A hook whose event a harness cannot take is skipped for that harness and tackroom status lists it under the harness as hooks unsupported: <name>. That line does not change the exit code. A hook that names a harness with no hook surface in its agents: is reported the same way.
Gemini CLI renames UserPromptSubmit to BeforeAgent, Stop to AfterAgent, PreToolUse to BeforeTool, PostToolUse to AfterTool and PreCompact to PreCompress. SessionStart, SessionEnd and Notification keep their names. No other event maps.
Devin gets no hooks from tackroom. By default it loads Claude Code's hooks from ~/.claude/settings.json (setting read_config_from.claude), so a second copy written by tackroom would run each hook twice on a machine that has both. With that import turned off, Devin runs none of your tackroom hooks.
Cursor uses sessionStart, sessionEnd, stop, preToolUse, postToolUse, beforeSubmitPrompt (for UserPromptSubmit), subagentStop and preCompact. If Cursor's third-party configs setting is on, it also runs Claude Code's hooks, so a hook synced to both runs twice there.
Pi and OMP run hooks as TypeScript extensions, so tackroom generates one module per hook. The module runs the command with /bin/sh -c and sends a Claude Code-style JSON payload (hook_event_name, cwd and agent) on stdin. Without a timeout it waits 60 seconds.
For SessionStart, an additionalContext value in the command's JSON output reaches the model with the next prompt. Stop and the tool events would need block-and-continue behavior the module does not reproduce.
Timeouts are seconds in tackroom.yaml. Qwen Code and Gemini CLI take milliseconds, and tackroom converts. Codex gives SessionEnd hooks at most 3 seconds, so a larger timeout is written as 3 there. Codex also needs hooks = true under [features] in ~/.codex/config.toml, which sync sets.
Factory Droid uses ~/.factory/settings.json instead when hooks.json does not exist and settings.json already has a hooks block.
List native registrations
tackroom hook list [--agents a,b] [query]
claude SessionStart managed ~/.agents/hooks/session-context.sh
claude Stop unmanaged stale=/path/to/old-tool/hook.sh /path/to/old-tool/hook.sh
gemini AfterAgent managed ~/.agents/hooks/notify.sh
unsupported hook surfaces: amp, dsh, opencode
3 native hook registration(s)
Each line is tab-separated: the harness key, the event under the harness's own name, the ownership, and the command.
managedmeans an enabled hook intackroom.yamlmatches the event and command. Anything else isunmanaged, whoever wrote it.stale=PATHappears when the command names a script (.sh,.py,.cmdor.ts, under~,$HOMEor an absolute path) that does not exist.- The command has its whitespace collapsed and is cut at 180 characters.
queryis an optional case-insensitive substring of the harness, event, command or file path.
The list covers the enabled harnesses in your config, or the ones named by --agents, whether or not they are installed. tackroom doctor has a native hooks check that warns about stale registrations.
Remove native registrations
tackroom hook remove --dry-run <query> # show the matches, change nothing
tackroom hook remove <query> # remove them
Put flags before the query. remove prints the matching registrations, removes each one, and reports how many files it changed. Other entries in those files are kept; for Pi and OMP the generated module is deleted. A query is required, and a query with no match prints no native hooks match and exits 0.
remove does not check ownership and writes no backup, so preview first. It also removes registrations of hooks that are still declared and enabled; the next sync writes those again.
What sync does with registrations:
- It adds and updates them.
- It removes one when the hook is still declared but no longer wanted for that agent:
enabled: false, or anagentslist that no longer names it.statusshows it ashooks staleuntil then. - The registration is matched by event and command, and stays when another enabled hook for that agent has the same event and command.
syncnever removes the native entry of a hook that is no longer declared at all. It shows up asunmanagedinhook listuntil you remove it.
To retire a hook you declared, set enabled: false and run tackroom sync; delete the entry afterwards if you like. If you deleted the entry first, run hook remove. Use the same steps for hooks left behind by a tool you uninstalled (troubleshooting.md).