komrad

Workflows

The templates tasks and agents are created from, and what each one decides for them.

Edit on GitHub

Everything you do in komrad happens inside a workflow. A workflow is a bucket of settings. It holds the directory work starts from, whether each task gets a worktree of its own, and how each role launches. Writers, reviewers and the orchestrator each get the harness they run, like Claude or Codex, and the flags they launch with.

Think of a workflow as a shared blueprint for one kind of work in one repository. You might keep one for bug fixes and another for feature work in the same repository, each with its own flags and context.

Creating your first workflow#

Clone a real repository to work in. This guide uses Neovim.

git clone https://github.com/neovim/neovim ~/neovim
cd ~/neovim

Run komrad open, open the menu with space and press w. Name the workflow neovim. Its directory defaults to the one you opened komrad in, and its provisioner decides whether each task gets a worktree. Press enter to create it.

The orchestrator#

Creating a workflow also starts its orchestrator, an agent that belongs to the workflow itself. The list folds it into the workflow’s row, and pressing enter on the workflow opens it.

The orchestrator doesn’t write code itself. You tell it what you want done, and it creates tasks for the work and puts agents on them. It passes messages between those agents and gathers what they find. Think of it as a lead who splits the work up and keeps track of it.

To give the orchestrator a clean slate, open the workflow’s menu with space and pick restart orchestrator with o. Komrad starts it on a new conversation and keeps the old one in its transcript, where the orchestrator can still read it.

The neovim workflow holds an orchestrator that hands work to its tasks, fix-login, rfc-truncate and more.

You don’t have to go through the orchestrator. You can start a task yourself, which the next guide shows.

Shared context#

A workflow can carry shared context, which every agent it starts reads. Use it for anything you would otherwise tell each agent by hand, such as how tests run and how commits are written.

In the Neovim example, that might be “Run make lint before committing any Lua change.”

The workflow’s context comes after your global context, which every agent reads in any workflow. In the video below the global context says only that Neovim is the best editor, and the agent has read both.

Settings for each role#

A workflow’s settings list writers, reviewers and the orchestrator. Each one opens the same four settings: the agent’s harness, its flags, a context of its own, and the conversation size it compacts at. Reviewers also take how many can be on one task at once and whether komrad archives them once they approve. The orchestrator also takes how many live tasks it may have started at once.

A setting you leave empty takes the matching setting from the role’s section of your config, such as reviewer.harness. An empty harness there takes default_harness. A role never takes another role’s setting, so reviewers don’t run the writers’ harness unless you name it for them too.

Flags belong to the harness they were written for. When you name a harness for a role without flags, the agent launches with no flags rather than the config’s.

A role’s context comes after the workflow’s shared context, and only agents in that role read it. It adds to what komrad tells each agent about its role and never replaces it. Your config can name a file of context for each role too, such as reviewer.context_file. Komrad reads your global context first, then the role’s file, then the workflow’s shared context, then the role’s context.

Worktrees#

Komrad has first-class support for git worktrees. Set the workflow’s provisioner to worktree and each new task gets a worktree of its own, cut from the workflow’s base branch. Every agent on that task works inside it, isolated from every other task. Komrad locks each worktree, so a git worktree prune in your own checkout keeps its registration. Deleting the task unlocks and removes the worktree.

Komrad puts worktrees in worktrees.dir unless the workflow names a directory of its own. The worktree section of the workflow’s settings also lists files to copy or link into each new worktree, such as a .env file git does not track.

A workflow can also name a setup command. Komrad runs it in the worktree before an agent starts or resumes there. Point it at whatever prepares the repository, such as mise trust && mise install, npm ci or a script the repository keeps. mise refuses the config in a directory it has not trusted, and each worktree is a new directory, so the example trusts it first. When the command fails, the agent does not start.

When you start a task, you can run it in the workflow’s base directory instead of a worktree.

This is helpful if you want to spawn an agent to make a change to your local directory, or if you do not want the agent to write any changes at all.

Changing a workflow#

Hover the workflow, open the menu with space and pick edit with E. The settings are the same as when you created it, plus the hooks and the prompts komrad sends agents when something happens.

Archiving and restoring#

Archiving a workflow puts it in cold storage. Open its menu with space and press a. Komrad archives the workflow’s orchestrator, its tasks, and every live agent in it. Nothing is deleted. The workflow moves to the archive, where you can restore it or delete it for good later.

Next steps#

You don’t have to build the whole workflow right away. Start with a directory and a provisioner. Add context once you notice yourself telling every agent the same thing.

Next, start a task in it.