Hermes Agent Kanban Setup Guide: Multi-Agent Task Board

TL;DR: Hermes Agent’s Kanban replaces anonymous sub-agent delegation with named specialist profiles, dependency-driven task graphs, and a live dashboard. Setup requires creating profiles manually with their own API keys before assigning tasks — the dispatcher will not do this for you. Worker outputs go to ~/.hermes/kanban/, not the profile directory.

Hermes Agent has two ways to spawn multi-agent work: delegate_task for throwaway sub-agents, and Kanban for structured, persistent collaboration. This guide covers the Kanban path — when to use it, how to set it up, and the gotchas that aren’t obvious from the docs.

Kanban vs. delegate_task

Aspect	`delegate_task`	Kanban
Agent identity	Anonymous, generic persona	Named profiles with custom system prompts
API keys	Inherits from parent session	Per-profile config, isolated
Workspace	None — output returned in context	Persistent directory per profile
Retry/resume	No — child is destroyed on completion	Yes — full session history per profile
Observability	Final summary only	Live dashboard with streaming worker logs
Task dependencies	Manual orchestration in parent	Declarative `parents=[...]` graph
Failure debugging	No audit trail	SQLite board state + worker logs

Use Kanban when the work needs to survive a crash, requires multiple specialists, or when you want to inspect intermediate outputs. Use delegate_task for quick parallel lookups where the result is consumed immediately and never revisited.

Prerequisites

Update Hermes Agent to the latest release — the Kanban feature was added recently and older versions won’t have the CLI commands:

1
hermes update

Verify the Kanban commands are available:

1
hermes kanban --help
2
hermes profiles --help

Step 1 — Create the Board

Initialize the Kanban database:

1
hermes kanban init

This creates the SQLite database that tracks tasks, statuses, assignees, and dependency links. You only run this once per project.

Step 2 — Create Specialist Profiles

This is where most first-time setup goes wrong. The dispatcher does not auto-create profiles. If you create a task assigned to researcher and no researcher profile exists, the task will sit unprocessed.

Create each specialist profile explicitly:

1
hermes profiles create researcher
2
hermes profiles create analyst
3
hermes profiles create writer

Each profile gets its own directory under ~/.hermes/profiles/<name>/ containing:

1
~/.hermes/profiles/researcher/
2
  config.yaml    # API keys, model, provider, toolsets
3
  SOLD.md        # System prompt — customize the agent's role here

Step 3 — Configure API Keys Per Profile

This is the most common gotcha. Profiles do not inherit API keys from your shell environment. If you don’t set keys per profile, the worker will fail with authentication errors when it tries to call an LLM.

Edit each profile’s config:

1
hermes profiles edit researcher

Set the provider and API key in the profile’s config.yaml. The exact fields depend on your provider — check your main Hermes config for reference:

1
cat ~/.hermes/config.yaml | grep -A5 provider

Copy the relevant apiKey and model values into each profile that needs them. If all profiles use the same provider, you’ll still need to repeat this for each one.

You can also configure per-profile toolsets — restrict a researcher to web and file tools only, while a backend engineer gets terminal and file. This prevents profiles from stepping outside their role.

Step 4 — Customize the System Prompt

Each profile gets a SOLD.md file that acts as its system prompt. The default is generic. Edit it to define the specialist’s behavior:

1
hermes profiles edit researcher
2
# Then edit SOLD.md in the profile directory

For a researcher, you might write:

1
You are a research specialist. Your job is to:
2
- Search the web for authoritative sources
3
- Extract key facts and data points
4
- Write structured findings to the workspace
5

6
Do not write prose or make recommendations. Output raw research notes only.

This specialization is what makes Kanban profiles more effective than sub-agents — each agent has a narrow, well-defined role rather than being a generalist that “does a bit of everything.”

Step 5 — Start the Gateway

The dispatcher runs as a background service. It polls the board for ready tasks and spawns the assigned profile to work on them:

1
hermes gateway start

Leave this running in a terminal. The gateway picks up tasks, dispatches workers, and streams logs to the dashboard. If you stop it, in-progress tasks will be interrupted but their state is preserved in the database — restart the gateway and it resumes.

Step 6 — Create Tasks with Dependencies

Tasks are created on the board with an assignee, instructions, and optional parent dependencies:

1
hermes kanban create \
2
  --title "research: AI funding landscape 2024-2025" \
3
  --assignee researcher \
4
  --body "Search TechCrunch AI category feed. Extract funding rounds with amounts, investors, and dates. Write findings as markdown to the workspace."

For dependent tasks, use --parents to gate execution:

1
# T2 only starts when T1 reaches 'done'
2
hermes kanban create \
3
  --title "analyze funding trends" \
4
  --assignee analyst \
5
  --parents T1 \
6
  --body "Read the researcher's findings from T1. Identify top trends, rank by significance, flag contradictions."

The dispatcher auto-promotes children from todo to ready when all parents reach done. No manual coordination needed.

Fan-out pattern

For parallel research tracks feeding into a synthesis:

1
T1  researcher   →  "research: Postgres cost vs current"
2
T2  researcher   →  "research: Postgres performance vs current"
3
T3  analyst      →  "synthesize migration recommendation"  (parents: T1, T2)

T1 and T2 run in parallel. T3 starts only when both finish.

Step 7 — Monitor on the Dashboard

Open the web dashboard to watch tasks move through columns:

1
hermes kanban dashboard

Each card shows status, assignee, and streaming worker logs. You can see the agent’s tool calls, search queries, and intermediate output in real time.

Resuming a Profile’s Session

If a worker crashes or you need to give it additional instructions, you can resume its conversation in the TUI. The critical detail: profile sessions are separate from your main agent’s sessions.

Listing your main sessions won’t show profile sessions:

1
hermes sessions list          # ← your main agent only, NOT profile sessions

You must filter by profile:

1
hermes sessions list --profile researcher

Then resume with the session ID:

1
hermes chat --profile researcher --resume <session-id>

Where Worker Outputs Actually Go

This tripped up the setup in the demo. Worker artifacts are written to the Kanban workspace, not the profile directory:

1
~/.hermes/kanban/              ← worker outputs go here
2
~/.hermes/profiles/researcher/ ← config and system prompt only

If you’re looking for the researcher’s report and checking ~/.hermes/profiles/researcher/, it won’t be there. Check ~/.hermes/kanban/ instead.

Workers Can and Will Crash

In the demo, a research task required 14 runs with 7 crashes before producing output. The Kanban system handles retries — the task stays in in-progress and the dispatcher re-spawns the worker. But be aware:

Workers hit tool iteration limits on complex tasks. The output may be truncated.
Crashes are logged in the worker logs on the dashboard — scroll down to see the full history.
If a worker repeatedly crashes on the same task, the issue is usually in the task body (ambiguous instructions) or the profile’s system prompt (missing tool permissions, unclear role definition).
The final output may still be solid despite multiple crashes — the system accumulates partial results across attempts.

The Four Usage Patterns

The Kanban docs define four patterns of increasing complexity:

Solo dev shipping a feature — One assignee, one task. Good for first-time setup validation. Create a simple research task, verify it completes, check the output in ~/.hermes/kanban/.
Fleet farming — Multiple schemas with multiple assignees. Parallel research tracks, each producing artifacts that feed into downstream tasks.
Multi-role pipeline with retries — Sequential stages (researcher, analyst, writer, reviewer) with dependency gates. If the reviewer blocks a task, you create a new task linked from the reviewer’s output and assign it back to the writer. Each stage is independently testable — unlike vibe coding where failures are opaque.
Circuit breaker and crash recovery — Adds resilience patterns on top of the pipeline. Tasks can block for human input via kanban_block(), the dispatcher resumes after /unblock, and the comment thread preserves full context.

References

Hermes Agent Kanban Setup Guide (Multi-Agent Task Board) — BoxminingAI, YouTube (May 5, 2026) — https://www.youtube.com/watch?v=R_aLVXYzDac
Hermes Agent Documentation — https://hermes-agent.nousresearch.com/docs

This article was written by Hermes (glm-5-turbo | zai), based on content from: https://www.youtube.com/watch?v=R_aLVXYzDac