# 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.

> Do not use hooks to copy or link dependencies into a worktree. A [workflow](https://komrad.dev/latest/guides/workflows.md#worktrees) already does that: its [`copy_paths`](https://komrad.dev/latest/api/workflow/list-workflows.md#komrad-workflow-v1-WorktreeConfig-copy_paths) and [`symlink_paths`](https://komrad.dev/latest/api/workflow/list-workflows.md#komrad-workflow-v1-WorktreeConfig-symlink_paths) on the worktree config, are copied or linked into every new worktree before the agent starts.

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`](https://komrad.dev/latest/config.md#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:

```sh
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`](https://komrad.dev/latest/config.md#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`](https://komrad.dev/latest/config.md#keybindings.menu.open) and press [`E`](https://komrad.dev/latest/config.md#keybindings.menu.edit_row), 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.

[Video: Writing the ignore-revs hook in a shell, picking it as the neovim workflow's agent.pre-launch hook, and spawning an agent that confirms git blame skips the listed commits.](https://komrad.dev/media/hook-setup.mp4)

## 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`](https://komrad.dev/latest/cli/rpc.md), waits as long as its hooks run. [`hooks.timeout`](https://komrad.dev/latest/config.md#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:

```sh
#!/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:

```sh
#!/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:

```sh
#!/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:

```sh
#!/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_ID` names the agent
-   `KOMRAD_AGENT_CWD` is the directory the hook runs in
-   `KOMRAD_TASK_ID` and `KOMRAD_TASK_SLUG` name the task
-   `KOMRAD_WORKTREE_NAME` names the task’s worktree, and is unset when the task has none
-   `KOMRAD_WORKTREE_BRANCH` is that worktree’s branch, `task/<task id>`
-   `KOMRAD_TRIGGER` says which moment fired the hook
-   `KOMRAD_ADDR` is where to reach the API
-   `KOMRAD_AGENT` holds the whole agent as JSON

The [`komrad`](https://komrad.dev/latest/cli.md) 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.

![An agent whose agent.pre-launch hook failed, marked as never having launched, with the reason it failed beside it.](https://komrad.dev/media/hook-failed.png)
