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

Starting agents#
Most of the time you start an agent by 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.
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.
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, 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, then say what you want looked at. The orchestrator can also spawn reviewers for tasks.
Set 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 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 and press A. 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 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 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 on GitHub with the pane that’s missing/wrong.