Hermes Agent Kanban: the task board for agents that work in parallel

What Hermes Kanban is, and how it differs from delegating

Every task on the board is a row in a SQLite database, ~/.hermes/kanban.db for the default board. Hand-offs between agents are recorded on the board too, where you can read them. Each worker is a real operating-system process running as one of your profiles, with that profile’s own memory, model and settings.

Hermes already has a way to hand a job to a sub-agent inside one conversation, the delegate_task tool. Upstream is explicit that the two are different things:

• delegate_task starts subagents inside the current session. Depending on where you are chatting, results come back later or the call waits for them, but a subagent has no durable task record to resume if it fails.
• Kanban is a work queue. The creator does not wait, the worker is a named profile, a task can be blocked, commented on by a human and picked up again, a crash is detected and the task is reclaimed, and the record stays in the database after the conversation that started it is gone.

Use delegate_task for a short piece of reasoning you need back right now. Use Kanban when work should survive a restart, may need a human’s input, or may be picked up by a different specialist. The two can be combined: a Kanban worker can itself call delegate_task.

Boards, tasks, statuses, links and workspaces

The vocabulary is small:

• Board. A separate queue with its own database, workspaces and logs. A new install has one board, default. You can add more, for example one per project, with hermes kanban boards create, and a worker only ever sees the board it was started for.
• Task. A title, an optional body, an optional assignee (a profile name) and a status. The statuses in the code are triage, todo, scheduled, ready, running, blocked, review, done and archived.
• Link. A parent-to-child dependency. A child waits in todo until every parent is done or archived, then moves to ready by itself.
• Comment. The note thread on a task. When a worker is started or restarted it reads the whole thread, which is how a human steers a task without touching the worker.
• Tenant. An optional label inside a board, for one set of specialists serving several businesses. Upstream calls it a soft filter: boards are the hard separation.

Each task also gets a workspace, the folder its worker operates in. There are three kinds:

• scratch (the default): a fresh temporary folder, deleted when the task completes. Files the worker declares as artifacts are copied to the task’s attachment storage first.
• dir:<path>: an existing shared folder, such as a documents directory. The path must be absolute, and it is kept after completion.
• worktree: a git worktree for coding tasks. Hermes removes it after completion only when it is clean and its commits are safely pushed; otherwise it is kept.

You can attach files to a task (up to 25 MB each) and the worker is shown their absolute paths, so source documents do not need to be pasted into the task body.

Create your first tasks from the command line

The commands below are for you. Once a task is assigned, the model running it uses a separate set of kanban_* tools, covered in the next section.

These commands assume you have already created a profile named researcher and installed the gateway service with hermes gateway install. Use your own profile name in its place.

hermes kanban init
hermes gateway start
hermes kanban create "Summarise this week's customer emails" --assignee researcher
hermes kanban watch
hermes kanban list
hermes kanban stats

init creates the database if it is missing, gateway start runs the gateway that hosts the dispatcher, watch streams events to your terminal as they happen, and list and stats show the board and per-status counts. Without a running gateway, ready tasks simply wait, and hermes kanban create warns you about that.

The options you will use most when creating a task:

• --parent <id> makes the new task wait for another one to finish. Repeat it for several parents.
• --workspace dir:/path/to/folder picks the workspace kind.
• --skill <name> loads an installed skill into that one worker, on top of the standard board instructions. It must already be installed on the assignee’s profile.
• --triage parks a rough idea in the triage column instead of making it ready.
• --body supplies the opening task brief, including requirements and acceptance criteria.
• --idempotency-key reuses an existing non-archived task with the same key, which helps automation that retries. Two creates at the same moment can still produce duplicates.
• --max-runtime and --max-retries cap how long one run may take and how many failures the task is allowed.

The same verbs work as a /kanban slash command inside a Hermes chat and on gateway platforms such as Telegram. A task created that way from a chat subscribes that chat to the outcome, so you get a message when the task completes or blocks.

Workers and lanes: who actually does the work

A lane is a kind of worker the dispatcher can route a task to. In practice a lane is a Hermes profile: the assignee on the task is the profile name, and the dispatcher starts hermes -p <profile> --cli --accept-hooks chat -q with the task prompt, inside the task’s workspace. So you set up lanes by creating profiles with distinct jobs, such as a researcher, a writer and a reviewer, each with its own memory, model and skills. The dispatcher matches assignee names to profiles that exist; a task whose assignee does not resolve stays in ready and is flagged rather than run by a fallback.

A worker does not type hermes kanban commands. The dispatcher gives it a dedicated set of tools: kanban_show to read the task, its history and its comments; kanban_heartbeat to show it is alive; kanban_comment and kanban_attach for notes and files; and one of three ways to finish a run:

• kanban_complete with a summary and optional structured metadata: the task becomes done.
• kanban_block with a reason: the task waits for a human or a dependency.
• kanban_request_review: the task moves to review for a reviewer profile (or a person) to approve or send back with kanban_request_changes.

Orchestrator profiles also get kanban_create, kanban_link, kanban_list and kanban_unblock, so one agent can split a goal into child tasks and step back. Implementation workers create follow-up tasks for work outside their scope, and orchestrators split work into specialist tasks instead of doing it themselves. Every run must end in one of the finishing calls. A worker that exits without one is booked as a protocol violation, and the dispatcher retries a bounded number of times before blocking the task.

Failure handling is built in. A worker whose process has died is detected and its task reclaimed. A task that fails repeatedly is blocked automatically instead of being restarted forever, and the default threshold for consecutive start failures is 2. A provider that rejects the profile’s key or model blocks the task on the first attempt, with the provider’s own message, so you know to fix the profile. Rate-limit and quota errors requeue the task without counting as failures.

Skills matter here: a worker is only as capable as the profile behind it. See Hermes Agent skills for what a profile can be taught.

The dispatcher: what it does and when it holds back

The dispatcher is a loop that runs inside the gateway by default, once every 60 seconds. Each tick it reclaims stale or crashed work, promotes tasks whose parents are done, claims ready tasks atomically and starts their assigned profiles. The relevant settings live under kanban: in ~/.hermes/config.yaml:

kanban:
  dispatch_in_gateway: true
  dispatch_interval_seconds: 60
  max_in_progress: 2
  failure_limit: 2

The first two lines show the defaults. max_in_progress caps how many tasks run at once. The upstream documentation says it is unlimited when unset, but the code does something more careful: if you leave it unset, the cap is derived from the machine’s memory, total memory divided by 512 MiB, never below 2 and never above 8. Where memory cannot be read, as on some non-Linux machines, there is no cap. A separate max_in_progress_per_profile limits a single slow or rate-limited profile without stopping the others.

There is also a live memory check on every tick. The dispatcher treats the machine as under elevated pressure when available memory is below 128 MiB or below 15 percent of total, and as critical below 64 MiB or 5 percent. At critical it starts no new workers that tick; at elevated it starts at most one. Deferred tasks are not dropped, they wait for a later tick. If a ready task is not starting, hermes kanban dispatch --dry-run reports most of the reasons a task was skipped, though not a full overall concurrency cap, and hermes kanban diagnostics flags tasks stuck in ready for too long, typically from a mistyped assignee.

Several gateways. If you run one gateway per profile, exactly one of them should own the dispatcher, so that two gateways do not race to start the same task. The owner keeps dispatch_in_gateway at true; every other gateway sets it to false, in config.yaml or with the environment variable HERMES_KANBAN_DISPATCH_IN_GATEWAY=false. Delivering notifications is separate: each gateway still sends the task messages for the platforms and profiles it hosts. If several Hermes homes share one database, upstream also offers kanban.dispatch_profiles to say which assignees each home may claim, because every home has a profile called default.

The standalone hermes kanban daemon is deprecated; use the gateway.

Triage, orchestration and using the board from chat

You do not have to break work into tasks by hand. A task created with --triage (or dropped in the Triage column) is picked up by the decomposer when kanban.auto_decompose is on, which is the default. It reads your profiles and their descriptions and turns the idea into a small graph of child tasks routed to the best fit. At most three tasks are decomposed per tick, set by kanban.auto_decompose_per_tick. Set auto_decompose to false for manual control, and run hermes kanban decompose or hermes kanban specify yourself. Routing depends on the description you give each profile, for example with hermes profile describe.

Whether your ordinary chat agent can create tasks is a separate switch. The kanban toolset is off by default and upstream describes it as opt-in. To let a profile manage tasks from chat, enable it for that profile and platform, then start a new chat:

hermes -p planner tools enable kanban --platform telegram

An agent with the toolset can create a task from a message and is subscribed to its result, so a finished or blocked task comes back into the same chat. The Desktop Kanban view can create and move tasks, but opening it does not give the chat agent that permission. For channel setup, see Hermes Agent on Telegram.

Viewing the board

There are four ways to look at it:

• The dashboard. Run hermes dashboard and open the Kanban tab. It has columns for triage, todo, ready, running, blocked, review and done, with archived as a toggle. You can drag cards between columns, open a card to edit it and read its comments, runs and last events, filter by assignee or tenant, switch between boards, and group the running column by profile, which is the lanes view. A Nudge dispatcher button runs a tick immediately instead of waiting for the next one. The dashboard binds to localhost by default, and a non-local bind or public URL requires authentication.
• The Desktop app, which has a Kanban page and in-app notifications for completed and blocked tasks. See Hermes Desktop.
• The terminal: hermes kanban list and show inspect tasks, watch and tail stream board and task events, and log <id> reads a worker’s output.
• Your chat, with /kanban list or /kanban show, which work even while an agent is mid-turn. Long output is truncated in messaging apps.

Practical uses for a small business

Kanban earns its keep when work has stages, a person needs to weigh in, or you want a record of what happened. Patterns the upstream documentation lists, applied to everyday jobs:

• A pipeline. A researcher gathers competitor pricing, a writer turns it into a one-page summary, and a reviewer checks it. Link the three tasks so each starts when the previous one finishes.
• Parallel research. Several research tasks run at once for different angles, and one task that depends on all of them combines the results.
• A person in the loop. A worker that hits an ambiguous choice, such as which supplier to recommend, blocks with a question. You answer with a comment, unblock it, and it continues with your answer in its context.
• A recurring job. Have an external scheduler, such as cron, run hermes kanban create for each occurrence, with a different idempotency key per occurrence so a retry does not create a duplicate.
• One specialist, many subjects. The same profile works through a list, for example one task per product page to proofread, each recorded separately.

Be realistic about the limits. A worker is a full agent run with a model behind it, so many tasks mean many model calls and a cost that grows with them; upstream suggests running the planning profile on a strong model and the worker profiles on cheaper ones. A task is only as good as its body, so write the goal and what done looks like. The --goal option adds judge-guided continuation turns. If the judge is unavailable or errors, the task is let through, so its approval is not guaranteed. The task is blocked for your review if the judge finds the goal unachievable or it is still unfinished at the turn budget (20 by default, set with --goal-max-turns).

Hermes Agent Kanban on ReadyHermes

The ReadyHermes workspace does not show a Kanban board. There is no board view or task list there, so you cannot create, drag or review tasks in it. What ReadyHermes gives you is a hosted Hermes Agent of the same upstream base, always on, reachable from Telegram, WhatsApp, Discord, WeChat and Lark, with the Channels panel handling the connection. You can also connect Hermes Desktop to your assistant, and Desktop’s Kanban page then shows a board for it, even though the web workspace has none.

If you want the full board with the dashboard, several gateways and dispatcher tuning from this guide, run Hermes yourself. The comparison of self-hosting and managed hosting lays out the trade-off, and managed Hermes Agent hosting describes what the hosted service does cover.