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
  • name is unique and event and command are required. timeout is in seconds and cannot be negative.
  • command is 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.
  • agents uses 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.

  • managed means an enabled hook in tackroom.yaml matches the event and command. Anything else is unmanaged, whoever wrote it.
  • stale=PATH appears when the command names a script (.sh, .py, .cmd or .ts, under ~, $HOME or an absolute path) that does not exist.
  • The command has its whitespace collapsed and is cut at 180 characters.
  • query is 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 an agents list that no longer names it. status shows it as hooks stale until then.
  • The registration is matched by event and command, and stays when another enabled hook for that agent has the same event and command.
  • sync never removes the native entry of a hook that is no longer declared at all. It shows up as unmanaged in hook list until 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).

Edit this page on GitHub