Hooks
Your own scripts, run by komrad at moments in an agent's or a task's life.
Hooks run your own code when something happens in komrad.
Hooks cover setup that komrad cannot handle out of the box, such as configuring a network.
Hooks also clean up when a task or agent is deleted. For instance, a task.pre-delete hook can kill any processes the task needed for local development, or tear down a docker stack.
Writing a hook#
Hooks are executable files in hooks.dir, which is ~/.config/komrad/hooks by default. An agent’s hooks run in the agent’s directory. A task’s hooks run in its worktree, or in the workflow’s directory when it has none.
For example, the Neovim repository keeps a .git-blame-ignore-revs file listing the commits that only reformatted code, so git blame can skip them. Git honours the file only when told to, and that setting lives in git’s config rather than in the tree, so checkouts don’t carry it. A hook can set it for each agent:
mkdir -p ~/.config/komrad/hooks
cat > ~/.config/komrad/hooks/ignore-revs <<'EOF'
#!/usr/bin/env bash
#KOMRAD description="make git blame skip neovim's reformatting commits"
git config blame.ignoreRevsFile .git-blame-ignore-revs
EOF
chmod +x ~/.config/komrad/hooks/ignore-revs
The #KOMRAD line is optional. Comment lines like it at the top of the file declare a hook’s description and timeout. Komrad stops a hook that runs past hooks.timeout, 60 seconds by default, and counts it as failed. A header timeout can shorten that limit but never lengthen it. A hook that declares a longer timeout, or "none", runs under the setting.
Hanging it on a workflow#
On the workflow’s row, open the menu with space and press E, move down to “hooks” under Settings and press enter, pick ignore-revs for “Agent pre-launch hook”, and press enter. Every agent spawned from now on runs it after its worktree exists and before its CLI starts.
Agent Lifecycle#
Every moment in a writer agent’s life has a hook before it and a hook after it. Komrad waits for a pre- hook, and a failing pre- hook refuses the step. Komrad never waits for a post- hook.
| Moment | Fires | If it fails |
|---|---|---|
agent.pre-launch | Once the agent’s directory exists, before its CLI starts. | The agent is not started and stays in the list marked as failed, so you can fix the cause and retry. |
agent.post-launch | Once the CLI is up. | The run’s log says so. |
agent.pre-resume | Before a dormant agent’s CLI starts again. | The agent is not resumed and stays dormant. |
agent.post-resume | Once a dormant agent’s CLI is back up. | The run’s log says so. |
agent.pre-archive | While the CLI is still running, before its pane is closed. | Nothing in the archive call is archived. |
agent.post-archive | Once the pane is closed and the agent is in the archive. | The run’s log says so, and the agent stays archived. |
agent.pre-restore | While the agent is still in the archive. | Nothing in the restore call is restored. |
agent.post-restore | Once the agent is back in the list, dormant. | The run’s log says so. |
agent.pre-delete | Once the panes are closed, while the worktree is still there. | The delete stops, and the agent is marked as failed to clean up. |
agent.post-delete | Once the agent’s row is gone, along with its task’s worktree. | Komrad’s own log says so, since the agent has no run log left. |
Hooks run one at a time, in the order the lifecycle events happen. A call that waits on a hook, such as archive_agents from MCP or komrad rpc, waits as long as its hooks run. hooks.timeout already bounds each one.
Only writer agents run agent hooks. Reviewers and orchestrators do not.
Task Lifecycle#
A task has moments of its own, which fire for the task as a whole. Hang anything that belongs to the task’s worktree here instead of on an agent, because the writer can restart and reviewers come and go while the worktree stays.
| Moment | Fires | If it fails |
|---|---|---|
task.pre-open | When the task’s writer starts, whether the task is created, retried or restored. | The writer is not started, as when its agent.pre-launch hook fails, or nothing is restored. |
task.post-archive | Once the task is archived, along with every agent on it. | The run’s log says so, and the task stays archived. |
task.pre-delete | When the task’s worktree is deleted, before komrad gives it back. It runs once per task. | The task stays archived with the reason, and its worktree stays where it was. |
task.pre-open and task.post-archive run as the agent that triggered them, and their logs sit with that agent’s own. task.pre-delete doesn’t run as an agent, so it doesn’t get a KOMRAD_AGENT_ID. A later delete of the task’s records does not run it again. A task’s hooks run one at a time, so task.pre-open waits for a task.post-archive still running from the last time the task closed.
Komrad ships two hooks for its own checkouts: komrad-checkout-archive for task.post-archive, which gives back a checkout’s test instance and drops what it rebuilds, and komrad-checkout-teardown for task.pre-delete, which takes the test instance down.
Examples#
You can use agent.post-launch to tell you an agent is up:
#!/usr/bin/env bash
osascript -e "display notification \"$KOMRAD_AGENT_ID is up\" with title komrad"
You can use the agent.post-archive hook to stop a dev server the agent started in a tmux session named after it:
#!/usr/bin/env bash
tmux kill-session -t "dev-$KOMRAD_AGENT_ID" 2>/dev/null || true
Use task.pre-open to start the database the task’s code talks to:
#!/usr/bin/env bash
[ -n "${KOMRAD_WORKTREE_NAME:-}" ] || exit 0
docker compose -p "$KOMRAD_WORKTREE_NAME" up -d db
And use the task.pre-delete hook to take that database down with its data:
#!/usr/bin/env bash
[ -n "${KOMRAD_WORKTREE_NAME:-}" ] || exit 0
docker compose -p "$KOMRAD_WORKTREE_NAME" down -v
What a hook knows#
Komrad tells a hook about its agent and its task through environment variables. A task hook sees the agent that triggered it, except task.pre-delete, whose KOMRAD_AGENT_ID is empty.
KOMRAD_AGENT_IDnames the agentKOMRAD_AGENT_CWDis the directory the hook runs inKOMRAD_TASK_IDandKOMRAD_TASK_SLUGname the taskKOMRAD_WORKTREE_NAMEnames the task’s worktree, and is unset when the task has noneKOMRAD_WORKTREE_BRANCHis that worktree’s branch,task/<task id>KOMRAD_TRIGGERsays which moment fired the hookKOMRAD_ADDRis where to reach the APIKOMRAD_AGENTholds the whole agent as JSON
The komrad binary is on the hook’s path, so it can ask the API anything else.
When a hook fails#
Every run writes its own log. Here the workflow’s agent.pre-launch hook tries to build Neovim with cmake --build build and fails. The hook’s own output says why.
