Build agent teams with the Hermes kanban board

What is the Hermes kanban board?

The Hermes kanban board is a durable task queue that all your Hermes profiles share, so several named agents can pass work to each other. Every task is a row in ~/.hermes/kanban.db, every handoff is a row any profile or human can read, and every worker is a full operating-system process running as one of your profiles.

The docs list the kinds of work it is built for:

• Research triage with parallel researchers, an analyst and a writer
• Scheduled operations, such as daily briefs that build up over weeks
• Persistent named assistants that accumulate memory over time
• Engineering pipelines: decompose, implement in parallel, review, iterate
• Fleet work, where one specialist manages many subjects

Kanban is single-host by design. The board, the dispatcher and the workers run on one machine.

When should you use kanban instead of delegate_task?

Use delegate_task when the current agent needs a quick answer back before it continues, and use kanban when work crosses agent boundaries, has to survive restarts or might need a human. The docs sum it up as: delegate_task is a function call, kanban is a work queue.

The two can work together: a kanban worker can call delegate_task during its own run.

What is the difference between orchestrator and worker profiles?

An orchestrator profile breaks a goal into tasks and assigns them, and worker profiles do the tasks. A well-behaved orchestrator does not do the work itself. It decomposes the goal, links tasks that depend on each other, assigns each one to a profile that exists, and steps back.

• Workers are spawned by the dispatcher for one task at a time. They get the task tools automatically, plus guidance in their system prompt that teaches them the task lifecycle. There is nothing to install per profile.
• Orchestrators need the kanban toolset turned on so they can create and route tasks. The docs suggest restricting an orchestrator's toolsets to board operations, such as kanban, gateway and memory, so it cannot start doing implementation work.

Two practical tips from the docs. First, give each worker profile a description with hermes profile create <name> --description "..." or hermes profile describe <name>, because routing uses those descriptions. Second, since each profile has its own config.yaml, you can run the orchestrator on a frontier model and point workers at cheaper models, where most of the tokens are spent.

How do you set up the board?

Create the board once, then keep the gateway running, because the dispatcher that starts workers runs inside the gateway by default.

hermes kanban init       # create the board database
hermes gateway start     # hosts the dispatcher

The dispatcher checks the board every 60 seconds by default. Without a running gateway, ready tasks stay where they are, and hermes kanban create warns you about this. The old standalone hermes kanban daemon is deprecated.

Then enable the kanban toolset for the profile that should orchestrate:

hermes -p planner tools enable kanban                       # CLI, TUI and Desktop chats
hermes -p planner tools enable kanban --platform telegram   # a messaging platform

Start a new chat after changing this, because existing conversations keep their old tool list. Note that the Desktop kanban view only displays the board. It does not give the chat agent permission to manage tasks.

How do you create tasks with --assignee and --parent?

Create a task with hermes kanban create, name the profile that should do it with --assignee, and make it wait for another task with --parent.

hermes kanban create "research AI funding landscape" --assignee researcher
hermes kanban create "write launch post" --assignee writer --parent <research-task-id>

A task whose parents are still open waits in todo and moves to ready when the last parent is done. A task whose parents are all done starts in ready straight away. You can repeat --parent for several parents.

Other useful options include --body for instructions and acceptance criteria, --skill to load extra skills for that task, --workspace to choose where the worker runs, --priority, --max-retries and --goal, which keeps the worker going until a judge agrees the task is done or its turn budget runs out.

The default scratch workspace is deleted when the task completes, apart from files the worker declares as artifacts. Use dir:<absolute path> or worktree when the files need to stay.

Every command also works as a slash command inside a chat, for example /kanban create "write launch post" --assignee writer --parent t_research. When you create a task from a messaging chat, that chat is subscribed to the task and gets a message when it completes or blocks.

How do handoffs between agents work?

Workers talk to the board through kanban_* tools rather than the CLI, and each worker ends its run with a handoff call that the next agent can read. The lifecycle injected into every worker is:

1. Call kanban_show() to read the task, parent handoffs, prior attempts and comments.
2. Work in the task's workspace.
3. Call kanban_heartbeat() during long operations.
4. Finish with kanban_complete(summary=..., metadata=...), hand code off for review with kanban_request_review, or stop with kanban_block(reason=...).

When a child task starts, its context includes a ## Parent task results section with each parent's summary and metadata, word for word. That is how a writer receives the researcher's findings. Comments are the other channel: you can add one to any task, and the next run of that task reads the whole thread.

For follow-up work on a finished task, create a new task with --parent pointing at it rather than reopening it. If a worker exits without a final board call, Hermes nudges it up to twice and the dispatcher retries a limited number of times before blocking the task.

How do you watch the board?

Watch from the terminal or open the dashboard.

hermes kanban watch          # live stream of events
hermes kanban list           # tasks and their status
hermes kanban stats          # counts per status and per assignee
hermes kanban show <id>      # one task in detail
hermes kanban log <id>       # a worker's log
hermes dashboard             # Kanban tab in the web dashboard

The dashboard's Kanban tab shows columns for triage, todo, ready, running, blocked and done. You can drag cards, create tasks, edit dependencies, comment, and nudge the dispatcher. With Auto orchestration on, which is the default, a task dropped into triage is passed to a decomposer that splits it into child tasks routed to your profiles by their descriptions.

Do not start the dashboard with --host 0.0.0.0 on a shared host. The kanban plugin routes are unauthenticated because the dashboard binds to localhost by default.

How do you set up a planner, researcher and writer team?

This minimal setup uses one orchestrator and two workers. Replace the topics and descriptions with your own.

# 1. Create the profiles with role descriptions
hermes profile create planner --description "Breaks goals into kanban tasks and assigns them. Does not do the work itself."
hermes profile create researcher --description "Finds sources and writes short research notes with links."
hermes profile create writer --description "Turns research notes into a finished draft."

# 2. Configure each profile's model and keys
planner setup
researcher setup
writer setup

# 3. Let the planner manage the board, then start the board and dispatcher
hermes -p planner tools enable kanban
hermes kanban init
hermes gateway start

Now either chat with planner chat and describe the goal, or create the two tasks yourself:

hermes kanban create "Research: how heat pumps perform in cold climates" \
    --assignee researcher \
    --body "Find 4 to 6 recent sources. Return key findings with links."

# Use the task id printed by the command above
hermes kanban create "Draft: 700-word explainer on cold-climate heat pumps" \
    --assignee writer \
    --parent <research-task-id> \
    --body "Use the research handoff. Plain language. Cite sources inline."

hermes kanban watch

The writer task waits in todo until the research task is done. When the writer starts, it finds the researcher's summary and metadata under Parent task results.

FAQ

Sources

• Kanban: Multi-Agent Profile Collaboration
• Profiles: Running Multiple Agents
• Subagent Delegation