Hermes Kanban: Durable Multi-Agent Task Boards

Hermes Kanban's durable CLI, dispatcher, worker tools, and web dashboard first shipped in Hermes Agent 0.13.0. The native Desktop plugin was merged to main and announced on July 31, 2026, after the 0.19.1 release tag (v2026.7.30); that tag does not contain the native Desktop implementation. Verify that a Desktop build includes the merged plugin before expecting its native board. The useful part is not the visual columns. It is the shared state machine behind them: the CLI, web dashboard, slash commands, agent tools, and compatible Desktop builds read and mutate the same board database.

A coding task can move from planner to implementer to reviewer without hiding the handoff in a parent agent's context. If a worker crashes, the next run sees what happened. If it needs a decision, a human can comment and unblock it. If a task depends on two research lanes, it does not become ready until both parents finish.

Why Kanban exists

Temporary subagent calls are good at bounded reasoning. A parent asks for research, waits, receives the answer, and continues. They become fragile when the workflow needs to survive a restart, cross several identities, or pause for a person.

Hermes documents the distinction this way:

They can coexist. A Kanban worker may call delegate_task internally for a small read-only analysis, then finish its durable card with an evidence-backed handoff.

Use the Hermes Agent and Buzz VPS guide when the problem is getting one persistent Hermes identity into a collaboration channel. Kanban solves the next problem: coordinating durable work across several Hermes profiles.

Understand the board and worker model

The default board is stored at:

~/.hermes/kanban.db

Named boards get separate databases, workspaces, logs, and attachments under:

~/.hermes/kanban/boards/<board-slug>/

The main objects are:

• Task: title, body, assignee, status, priority, optional tenant, model override, and idempotency key.
• Link: parent-to-child dependency. A child remains in todo until every parent is done.
• Run: one execution attempt with worker identity, outcome, timing, summary, metadata, and errors.
• Comment: durable communication among workers and humans.
• Attachment: task-scoped source file or URL.
• Workspace: scratch directory, existing directory, or Git worktree where the worker operates.
• Dispatcher: loop that promotes, atomically claims, spawns, monitors, and recovers tasks.

Tasks move through:

triage -> todo -> ready -> running -> done
                    |          |
                    |          +-> blocked -> ready/todo
                    +------------------------^

triage is intentionally separate from todo. It can hold rough requests for automatic or manual decomposition. todo usually means the task is formed but not runnable because it is unassigned or waiting for parents.

The gateway hosts the dispatcher by default. It sweeps all boards on each interval while pinning each spawned worker to one board through HERMES_KANBAN_BOARD. Do not run the deprecated standalone daemon alongside the gateway dispatcher; two dispatchers against the same database can race for claims.

Start with one board and two profiles

Initialize the default board and open the visual interface:

hermes --version
hermes kanban init
hermes dashboard

Initialization is also lazy: the first hermes kanban operation can create the default database. The dashboard defaults to the loopback interface on port 9119; keep it bound there unless you have configured the documented authentication gate and private remote-access controls.

The dispatcher normally runs inside the messaging gateway:

hermes gateway start

Its documented defaults are equivalent to:

kanban:
  dispatch_in_gateway: true
  dispatch_interval_seconds: 60

Before creating tasks, ensure the assignee names match real Hermes profiles. The dispatcher cannot turn a job title such as security-reviewer into a configured profile by intuition.

Create a small task:

hermes kanban create \
  "Inventory authentication entry points" \
  --assignee researcher \
  --priority 2 \
  --body "Return paths, trust boundaries, and the commands used to verify them."

Observe it:

hermes kanban list
hermes kanban watch
hermes kanban stats

When the dispatcher claims the card, it starts the researcher profile as a new OS process. The model receives the task context and dedicated Kanban tools. It does not need to parse the human-facing CLI output.

For automation, add a stable idempotency key:

hermes kanban create \
  "Nightly read-only deployment review" \
  --assignee ops-review \
  --idempotency-key "ops-review-2026-08-01" \
  --json

Repeating the same key returns the existing task rather than creating duplicates. Use a deterministic event or schedule identifier; do not use a random UUID if deduplication is the goal.

Build a dependency graph

A durable board becomes valuable when the workflow is a graph rather than a pile of cards. Suppose two researchers feed one writer and one reviewer:

A=$(hermes kanban create \
  "Research official product documentation" \
  --assignee researcher-a --json | jq -r .id)

B=$(hermes kanban create \
  "Inspect repository, release, and license" \
  --assignee researcher-b --json | jq -r .id)

DRAFT=$(hermes kanban create \
  "Draft implementation guide from evidence" \
  --assignee writer \
  --parent "$A" --parent "$B" \
  --json | jq -r .id)

hermes kanban create \
  "Review draft claims and commands" \
  --assignee reviewer \
  --parent "$DRAFT"

The writer remains in todo until both research cards are done. Completing only one parent does not make the child runnable. When both finish, the database promotes the child to ready; the next dispatcher tick can claim it.

Workers can also create and link tasks through kanban_create and kanban_link. Use that broader surface only for an orchestrator profile. Implementation workers should not expand unrelated work simply because the tool is available.

A good orchestrator:

1. discovers the actual profile roster;
2. decomposes only where parallelism helps;
3. writes acceptance criteria into each task body;
4. links dependencies explicitly;
5. assigns work to an existing specialist;
6. steps back instead of implementing every child itself.

Keep the graph acyclic. Hermes rejects link operations that would create a dependency cycle.

Make structured handoff part of the worker protocol

Humans and scripts use hermes kanban. Dispatcher-spawned models use a dedicated tool surface such as:

• kanban_show to load the current task, comments, parents, and previous runs;
• kanban_heartbeat during long work;
• kanban_comment for durable notes;
• kanban_block when dependency, input, capability, or transient failure prevents completion;
• kanban_complete for the final result and machine-readable evidence;
• attachment tools for source and deliverable files.

A well-behaved worker turn looks like:

kanban_show()

# The worker performs the actual research, edits, or tests.

kanban_heartbeat(
  note="implementation complete; running targeted tests"
)

kanban_complete(
  summary="added idempotent webhook handling and verified duplicate delivery",
  metadata={
    "changed_files": ["src/webhook.py", "tests/test_webhook.py"],
    "verification": ["pytest tests/test_webhook.py -q"],
    "residual_risk": ["provider retry timing was simulated, not live"]
  }
)

The summary is the human handoff. Metadata is the reusable evidence packet. Downstream workers receive the latest completed parent run, while retries receive their own previous attempts.

A practical metadata convention is:

{
  "changed_files": ["path/to/file"],
  "verification": ["exact command or manual check"],
  "dependencies": ["parent task or external issue"],
  "blocked_reason": null,
  "retry_notes": "what failed before",
  "residual_risk": ["what remains unverified"]
}

Do not put tokens, credentials, raw private logs, or unrelated conversation history in task metadata. Store a safe pointer and a concise finding.

The terminal board call is load-bearing. If a worker exits successfully while its task is still running, Hermes records a protocol violation and retries only within a bounded budget. A plain-text “done” is not a state transition.

Choose the workspace boundary

Hermes supports three workspace shapes:

Scratch is the safest default for tasks that need no existing checkout. A worker must explicitly declare deliverable artifacts before cleanup. Missing declared artifacts keep the task in flight so the path can be corrected.

dir: accepts only an absolute path. Relative paths are rejected because the dispatcher working directory can vary. The remaining trust boundary is still strong: the worker runs as your operating-system user and can access whatever that user and its tools can access. A path under / is not safe merely because it is syntactically absolute.

Use one worktree per coding task and preserve branch ownership:

planner task
  -> implementation task in worktree A
  -> independent review task reading the resulting diff
  -> repair task in the same controlled branch/worktree

Do not assign two implementation workers to the same mutable checkout. SQLite can serialize board claims; it cannot make concurrent file edits logically compatible.

Attachments are copied into board-specific storage and exposed to the worker by absolute path. When a worker's terminal backend is remote, mount the attachment directory explicitly or the path will exist only on the host-side agent process.

Use the dashboard for human decisions

The bundled Kanban dashboard plugin provides:

• columns for triage, todo, ready, running, blocked, done, and optionally archived;
• live WebSocket updates;
• task creation, editing, assignment, priority, comments, links, attachments, and run history;
• profile lanes inside the running column;
• drag-and-drop status changes with confirmation for destructive transitions;
• filters for board, tenant, assignee, text, and archived tasks;
• manual dispatcher nudging;
• automatic or manual decomposition from triage;
• per-task model, goal-mode, skills, and workspace choices.

The UI is not a second workflow engine. API endpoints route through the same kanban_db layer as CLI and model tools, which prevents three surfaces from developing conflicting state.

Use the dashboard when a person must:

• decide whether a blocked task has enough input to retry;
• inspect previous attempts before reassigning;
• verify that a dependency really finished;
• compare the claimed result with attached evidence;
• stop an accidental fan-out before it consumes budget.

For headless automation, keep using idempotent CLI calls, explicit task IDs, and structured JSON output rather than browser automation.

Design for retries and crash recovery

A task can have several runs. Each attempt records its own outcome, worker, time, summary, metadata, and error. This makes retry a first-class state transition rather than a rewritten “latest result.”

The dispatcher handles several failure modes:

• Spawn failure: release the claim and retry within the configured limit.
• Crashed process: detect the missing host-local PID and reclaim the task.
• Stale run: reclaim work that exceeds the stale timeout without a recent heartbeat.
• Runtime timeout: terminate the worker and return the card to the queue according to policy.
• Protocol violation: retry a worker that exited without completing or blocking the card.
• Repeated failure: trip a circuit breaker and move the card to blocked.
• Repeated unblock/re-block loop: route the task to triage for a human decision.

Long tasks should heartbeat periodically:

kanban_heartbeat(note="processed 42 of 80 files; no errors")

A heartbeat proves process liveness, not correctness. The completion handoff must still report what changed and how it was verified.

When a failure is permanent-looking—missing credentials, nonexistent profile, inaccessible directory—do not keep increasing retries. Fix the capability or assignment, attach the decision as a comment, and then unblock.

Respect the security boundaries

Hermes Kanban is deliberately single-host and assumes a trusted local operating-system user. That has concrete implications:

• dir: workspaces can expose everything that user can read or write.
• Named tenants are a soft organizational filter, not a hard authorization boundary.
• Separate boards provide stronger queue isolation through separate databases and directories, but workers still share the host account unless you add OS or container isolation.
• A task body, comment, or attachment is untrusted input to an agent with tools.
• Model or provider overrides can change data-processing and cost boundaries.
• Automatic decomposition can multiply tasks and usage.
• Dashboard access can mutate assignments, dependencies, statuses, and attached files.

The dashboard is a machine-level privileged management surface, not a read-only Kanban viewer. It can manage profiles, edit config.yaml and .env, expose chat sessions, and run agent commands. Keep the default loopback bind for local use. A non-loopback bind engages Hermes' authentication gate; place remote access behind the documented OAuth/OIDC path or a trusted VPN rather than exposing a password-only dashboard directly to the public internet.

Start with:

1. one private host and one test board;
2. narrow worker profiles with only required tools;
3. scratch workspaces for untrusted documents;
4. explicit budgets and concurrency;
5. manual orchestration until decomposition behavior is understood;
6. non-production repositories and accounts;
7. reviewed dashboard exposure;
8. task metadata that excludes secrets.

Boards cannot substitute for filesystem permissions, Git branch protection, cloud IAM, sandboxing, or approval gates. For wider controls, use the Agent Baseline implementation guide.

Verify one complete workflow

Run a harmless acceptance pipeline before putting real work on the board:

1. Create a new named test board.
2. Create two test profiles with distinct, low-risk roles.
3. Add two independent parent tasks and one dependent child.
4. Confirm only the parents enter ready.
5. Start the gateway and confirm each parent is claimed once.
6. Have one worker heartbeat and complete with structured metadata.
7. Have the other block with a clear needs_input reason.
8. Comment with the missing input and unblock it.
9. Confirm the second run sees the previous block reason.
10. Confirm the child promotes only after both parents are done.
11. Kill one disposable test worker and verify task reclamation.
12. Inspect task runs, events, attachments, and the dashboard after restarting the gateway.

For coding workflows, add:

• separate worktrees;
• branch and remote checks before push;
• tests recorded in completion metadata;
• an independent reviewer task;
• human approval before merge or deployment.

The board should make those gates visible. It should not silently perform them because a card reached done.

Know the current limitations

• One board does not span multiple hosts.
• SQLite and process-ID recovery assume local host semantics.
• Tenants do not provide hard security isolation.
• Workers still inherit the authority of their operating-system account and configured tools.
• Automatic decomposition quality depends on profile descriptions, model behavior, and task acceptance criteria.
• Remote terminal backends need explicit workspace and attachment mounts.
• Structured handoffs remain model-authored claims until a reviewer checks the cited files, commands, URLs, or external effects.
• A visual board can make activity look controlled even when permissions, budget, or data boundaries are too broad.

If the work is one short reasoning call, Kanban is unnecessary overhead. If it needs a distributed queue across machines, Hermes' local board is not that queue.

Practical verdict

Hermes Kanban fits software, research, editorial, and operations workflows where named specialists hand work to one another over hours or days. Its strongest property is not parallelism; it is durable, inspectable state around every handoff and retry.

Use it after profiles, workspaces, acceptance criteria, and human gates are clear. Otherwise it will faithfully make an ambiguous process durable.

Official sources

• Hermes Kanban reference
• Hermes Kanban tutorial
• Hermes Agent v0.13.0 release
• Hermes Agent v2026.7.30 release
• Native Desktop Kanban pull request
• Hermes web dashboard security and remote access
• Hermes Agent documentation
• Hermes Agent repository