# Agents

The three kinds of agent, how they work together on tasks, and how komrad knows what each one is doing.

Agents do the work in komrad. Each one is a real Claude or Codex session running in a terminal that komrad manages for you. Agents hold no state of their own, so you can create or discard them without losing work.

> This guide assumes you know what a [workflow](https://komrad.dev/latest/guides/workflows.md) and a [task](https://komrad.dev/latest/guides/tasks.md) are.

Agents are also durable. You can shut down or restart your machine without losing an agent’s history or context, and you can restore or search its conversation later. Agents can also start and manage other agents.

## Three kinds of agent

Komrad has three kinds of agents.

There is always one _orchestrator_ agent per [workflow](https://komrad.dev/latest/guides/workflows.md#the-orchestrator). The orchestrator is rendered above the workflow’s tasks, and coordinates the work across them.

Every task has exactly one _writer_. The writer does the task’s work: it makes edits, commits, and opens the pull request. It is the only agent that changes the task’s checkout, and it stays with the task for the task’s whole life. You can [restart](https://komrad.dev/latest/guides/tasks.md#managing-task-agents) it on a new conversation whenever you want, for instance if you want to switch the model working on the task from Claude to Codex.

Finally, _reviewer_ agents read the writer’s change and comment on it. Reviewers work in the task’s checkout but make no changes of their own.

![The neovim workflow holds an orchestrator that coordinates two tasks. The fix-login task has a writer, which does the work and owns the checkout, and a reviewer that reads the writer's change. The rfc-truncate task has only a writer.](https://komrad.dev/latest/diagrams/agents.png)

## Starting agents

Most of the time you start an agent by [starting a task](https://komrad.dev/latest/guides/tasks.md#starting-a-task), which launches its writer. You can also tell the orchestrator in its chat window what you want done, and it’ll create the task for you.

[Video: Asking the neovim workflow's orchestrator to split some reading into three tasks, and the three tasks appearing under the workflow, each with its own agent.](https://komrad.dev/media/agent-children.mp4)

Open an agent by moving the cursor onto it and pressing enter. Its terminal fills the main view, and you can talk to it like any other Claude or Codex session.

[Video: Starting a task on the neovim workflow that asks where :checkhealth is implemented, then opening its agent to read the answer.](https://komrad.dev/media/first-agent.mp4)

## Reviewers

Reviewers review the writer’s work. The writer spawns one when its work is ready. The reviewer reads the change and leaves comments on its lines, the same way you do in a [review](https://komrad.dev/latest/guides/reviews.md), and the writer answers them. The writer can ask for another reviewer while one is still reading. A task can go through many reviews over its life.

You can start a reviewer yourself too. Open a task’s menu and pick new agent with [`c`](https://komrad.dev/latest/config.md#keybindings.menu.new_agent), then say what you want looked at. The orchestrator can also spawn reviewers for tasks.

Set [`reviewer.max_per_task`](https://komrad.dev/latest/config.md#reviewer.max_per_task) to cap how many reviewers one task can hold at a time, however they were started. A request past it is refused until one of them is archived. A workflow can set a cap of its own in its reviewers settings.

Komrad archives a reviewer once it approves. Turn off [`reviewer.archive_on_approval`](https://komrad.dev/latest/config.md#reviewer.archive_on_approval) to keep approved reviewers in the list until you archive them yourself. A workflow can turn archiving on or off for its own reviewers.

## Adopting work

Sometimes the work started outside komrad, such as a colleague’s pull request or a branch you began on another machine. Hover the workflow, open the menu with [`space`](https://komrad.dev/latest/config.md#keybindings.menu.open) and press [`A`](https://komrad.dev/latest/config.md#keybindings.menu.adopt). Name the branch and say what to do with it. Komrad starts a task on that branch with a writer on it, in a worktree of its own when the workflow cuts them.

The branch has to be in the workflow’s repository, either pushed to its origin or already on disk.

## Archiving an agent

Archiving an agent stops it and takes it out of the list. Its conversation stays in the database, so you can still search it or restore it later.

Archive the [task](https://komrad.dev/latest/guides/tasks.md#archiving-restoring-and-deleting-tasks) to archive it’s writer agent and all reviewers.

Reviewers come and go on their own. You can archive one whenever you like, and restore it later once its task is live. A reviewer is only deleted when its task is deleted, which removes its conversation too.

## Agent state

Most agent tools learn what an agent is doing from hooks the agent fires. But hooks can be dropped, reordered, or never sent, for example when the CLI crashes. Other orchestrators have many bug reports about this.

Komrad takes a different approach. It reads each agent’s state directly from what its terminal actually renders, which komrad calls the pane. The [Claude test panes](https://github.com/harrisoncramer/komrad/tree/main/internal/harness/claude/testdata) show what it reads.

Komrad still installs hooks in each agent’s CLI, but they only add detail on top of the pane. They record that a turn ended or failed and why, and which tool the agent is running or waiting on approval to run. Every hook call lands on the agent’s logs screen, and so does any problem a hook hits while komrad can be reached.

If Claude or Codex ever ship real-time state notifications, komrad will move to them! Until then, reading the pane is the more reliable choice.

If the state shown does not match your CLI, please [submit an issue](https://komrad.dev/latest/guides/bugs.md) on GitHub with the pane that’s missing/wrong.
