Hermes Agent Kanban: Multi-Agent Workflow Coordination Guide

Hermes Kanban is a durable task board for coordinating work across multiple AI agents. Unlike ephemeral subagents that forget context between runs, Kanban tasks persist in SQLite, move through human-gated review stages, and pass structured metadata (changed files, decisions, blockers) to downstream workers. It is built for multi-step projects where you need visibility into progress, gates on critical decisions, and reliable handoff between specialized agent profiles. Single-host design: runs on your machine with no distributed setup needed.

What Is Hermes Kanban? (And When Should You Use It?)

Hermes Kanban is a SQLite-backed workflow system for coordinating multiple agents working on the same project. Think of it as a scrum board built into Hermes Agent, but with a critical difference: tasks are first-class durable objects, not just notes. When an agent completes a task, it leaves structured metadata (changed files, decisions made, blockers hit) that the next agent can read and act on. This is why Kanban shines for multi-step projects where handoff quality matters.

When should you use Kanban? When your workflow involves breaking large problems into subtasks, multiple specialized agents (researcher, engineer, reviewer), work worth tracking with an audit trail, or human gates at certain approval points. Kanban excels at recurring multi-step projects: content pipelines, feature development cycles, customer onboarding sequences, and any workflow where "who did what and why" is a question you will ask later.

When should you skip it? Kanban is overkill for single-shot prompts (chat with Claude, get an answer), stateless CLI interactions (hermes ask <query>), fire-and-forget subagent work (spawn a worker, wait for result, done), or simple request-response patterns. If the work is sequential and trivial, simpler tools cost less.

The Kanban board is also single-host by design. It runs on one machine, using a local SQLite database. You cannot (yet) spread the board across multiple machines or set up automatic failover. If you need multi-machine coordination, you will need to run separate Kanban instances or use a different orchestration pattern. This is a hard limitation worth understanding upfront.

Hermes Agent itself has reached 214K+ GitHub stars. Kanban became stable in v0.12 (April 2026) and has since become the go-to feature for teams running recurring, multi-step workflows. The trade-off is clear: you gain durable state and structured handoff at the cost of initial setup complexity (profiles, descriptions, API key management).

The Board at a Glance: Six Columns Explained

When you open the Hermes dashboard, you see a Kanban board organized into six columns. Each column represents a stage in the task lifecycle. Understanding these stages is the key to using Kanban effectively.

Triage is your inbox. Raw ideas, user requests, and auto-decomposed subtasks land here. Tasks in Triage have not been parsed or assigned yet. You decide which ones matter enough to move forward. Think of it as the backlog: rough, unrefined, waiting for human judgment.

To Do / Ready holds tasks the orchestrator has parsed and is waiting to assign. The task description is clear, the subtasks are broken down, and the system knows which agent profile should own it. Nothing is running yet; workers are waiting to claim. This is your sprint backlog.

Running is the active work. A worker (an instance of an agent profile) has claimed the task and is working on it. You can see which profile is working on what. The board groups running tasks by "lanes" (one lane per profile). If you have three workers (researcher, engineer, reviewer), you will see up to three parallel lanes doing work in parallel.

Blocked holds tasks that hit a wall. Common blockers: an external API is down, a worker ran out of retries, a human reviewer rejected the approach, or a task is waiting for another task to complete. Blocked tasks do not consume worker resources; they sit here until resolved. A human reads the block reason and either fixes it or routes the task differently.

Review is the approval gate. Before a task moves to Done, a human (or another agent profile acting as reviewer) checks the work. Did the engineer actually write tests? Did the content writer hit the word count? Did the decision follow the company policy? In review, you can approve, request changes, or reject entirely.

Done / Gallery is the archive. Completed tasks live here with their full history: all attempts, all metadata, all comments, all decisions. This is your audit trail. If you need to understand why a decision was made two months ago, or trace which agent made the change, you can find it in Done.

Setting Up Your First Kanban Workflow

Here is the step-by-step setup. Assume you have Hermes v0.12+ installed. If not, follow the Hermes Agent installation guide.

Step 1: Initialize the board

Run hermes kanban init from your project directory. This creates a local SQLite database (.hermes/kanban.db) and initializes the schema. Hermes will ask you for a board name and description. Accept defaults or customize to your taste. Initialization takes less than a minute.

Step 2: Create agent profiles

You need at least one profile. Let's say you are building an auth module. Create three profiles: researcher, engineer, and reviewer.

hermes profile create researcher --description "Researches authentication patterns, existing implementations, and best practices. Outputs a design doc with recommendations."
hermes profile create engineer --description "Implements the authentication module from the design doc. Writes code, adds unit tests, commits to main."
hermes profile create reviewer --description "Reviews code for correctness, style, test coverage, and security. Approves or requests changes."

Description quality matters. The orchestrator reads these descriptions to decide which profile should claim which task. Vague descriptions lead to wrong assignments. Specific descriptions improve routing and reduce retries. Invest time in writing clear, behavioral descriptions.

Step 3: Set API keys per profile

This is a common pitfall. Do NOT rely on shell environment variables for API keys. Each profile needs its own credentials. This isolates profiles and prevents accidental key exposure or cross-contamination.

hermes profile set-env researcher OPENAI_API_KEY sk-proj-...
hermes profile set-env engineer OPENAI_API_KEY sk-proj-...
hermes profile set-env reviewer OPENAI_API_KEY sk-proj-...

If all profiles use the same key, this is still worth doing explicitly. The isolation is a safety boundary. Each profile gets its own credential set.

Step 4: Start the gateway

The gateway is the unified entry point: CLI, dashboard, and API all talk to the same gateway process.

hermes gateway start

This starts a server on port 9119 (configurable via --port). Leave it running in a terminal or background process. The dashboard, CLI (hermes kanban), and any API clients all use this gateway.

Step 5: Open the dashboard and create your first task

When the gateway is running, open your browser to the local gateway address (port 9119 by default). The Hermes Agent dashboard shows your board in real-time with all six columns. Click "New Task". Write a goal: "Build a stateless JWT authentication module for the API."

Hermes will auto-decompose this into subtasks based on your orchestrator settings (usually something like: research design patterns, implement the module, test it, review it). You will see three tasks appear in the Triage column. Move one or all to To Do / Ready manually or let the orchestrator auto-assign them. Click on a task to see details, add comments, or claim it yourself.

How Tasks Move: A Worked Example (Solo Feature Delivery)

Let's walk through a concrete example: you are building a stateless JWT auth module for your API. One goal task auto-decomposes into three subtasks. You have three profiles ready to work.

Triage to To Do / Ready

The orchestrator reads your goal: "Implement stateless JWT authentication module." It breaks this into three subtasks:

1. Research JWT patterns and choose an implementation strategy. Assign to: researcher.
2. Implement the module in Python, add unit tests. Assign to: engineer.
3. Review code for security and correctness. Assign to: reviewer.

All three land in Triage. You review them (they look sensible), drag them to To Do / Ready.

To Do / Ready to Running

The dispatcher (Hermes' internal task-claim daemon) spawns a worker for the researcher profile. The worker gets the task ID injected as HERMES_KANBAN_TASK environment variable. It calls kanban_show() to read the full task:

Task ID: abc123
Task: Research JWT patterns and choose an implementation strategy
Profile: researcher
Profile Description: Researches authentication patterns, existing implementations, and best practices. Outputs a design doc with recommendations.
Goal: Implement stateless JWT authentication module
Dependent tasks: none

The researcher agent reads the task, context, and any related files. It spends 5 minutes thinking about JWT, asymmetric keys, token refresh strategies, looking at industry standards. It writes a design doc. Then it calls:

kanban_heartbeat()  # tells dispatcher I am still working
kanban_complete(
  summary="Chose RS256 asymmetric keys with 30-min expiry and offline refresh tokens. See jwt_design.md.",
  metadata={
    "changed_files": ["jwt_design.md"],
    "key_decision": "RS256",
    "dependencies": ["needs async key generation"]
  }
)

The task moves to Review. A human (you, or another agent) checks the design: does it make sense? Is it secure? Does it fit your architecture? If approved, it moves to Done. If rejected, it goes back to Running with feedback.

Running to Blocked to Done

Meanwhile, the dispatcher spawns an engineer worker for the implementation task. The engineer reads its task and the researcher's Done task metadata:

Previous task summary: Chose RS256 asymmetric keys with 30-min expiry and offline refresh tokens. See jwt_design.md.
Metadata: changed_files=["jwt_design.md"], key_decision="RS256", dependencies=["needs async key generation"]

The engineer now knows the design decision without re-reading the whole discussion. It implements the module, writes unit tests, tries to commit. But it hits an error: missing the async key library. It calls kanban_complete() with outcome="blocked" and reason="missing async library." The task moves to Blocked.

A human reads the block reason and either installs the library manually or sends the task back to Running with instructions. The engineer retries and succeeds. Task moves to Review. The reviewer checks: tests pass? Code style correct? Security scan passes? Approved.

All three tasks are now Done. The whole workflow took 10 minutes, and every decision is recorded in the task history.

Why This Matters

This flow scales to 10+ subtasks. The key insight: each task knows its dependencies (previous tasks), inherits their metadata, and hands off its own metadata to downstream tasks. This is why task quality matters; bad metadata breaks the chain. A clear summary and structured metadata let the next agent pick up without re-reading everything.

Multi-Profile Workflows: Teams, Parallel Work, and Orchestration

Kanban shines when you have multiple specialized profiles working in parallel. Let's call this "fleet farming."

The Setup

You have three profiles:

1. Translator: Takes English content and translates to 5 languages.
2. Transcriber: Takes audio files and generates transcripts.
3. Copywriter: Takes transcripts and writes marketing copy.

You drop a raw goal into Triage: "Create localized marketing content for new product launch." The orchestrator auto-decomposes:

1. Translate English content to DE, FR, ES, PT, JA (assign to translator).
2. Transcribe the product demo video (assign to transcriber).
3. Write short-form copy from the transcript (assign to copywriter).

Parallel Execution

The dispatcher spawns three workers simultaneously. They claim their tasks and work in parallel:

• Translator is writing German, French, Spanish, Portuguese, Japanese versions.
• Transcriber is running speech-to-text on the video.
• Copywriter is reading the English transcript and writing ad copy.

All three run concurrently. The board shows three Running lanes (one per profile). This is where Kanban shines: visibility into parallel work and automatic rebalancing if one worker finishes early and picks up another task.

Dependency Chains

If the copywriter depends on the transcriber (copywriter needs the transcript to write good copy), you can declare that dependency. The dispatcher waits: copywriter task stays in To Do / Ready until transcriber is Done. Then copywriter claims and starts.

This is orchestrator-driven, not manual. Your goal says: "Write copy from the transcript." The orchestrator knows transcript generation is a prerequisite and schedules accordingly. Dependencies prevent wasted work and ensure handoff happens at the right time.

Profile Descriptions Matter

If your researcher profile description is vague ("Does research"), the orchestrator might assign it to simple research tasks, complex synthesis, and weird edge cases. It does not know what the profile is good at.

If your researcher description is specific ("Researches third-party API integrations, evaluates performance and cost, recommends fit for our use case"), the orchestrator learns to assign it only to integration-research tasks.

Spend time on descriptions. They compound: a good description leads to better task routing, which leads to fewer wrong assignments, which means fewer retries and less wasted work. One hour writing clear profiles saves 10 hours in wrong assignments.

Real-World Example: Daily Content Pipeline

A newsletter company runs a daily content pipeline:

1. Researcher scrapes tech news, curates stories, writes summaries.
2. Writer takes summaries and expands them into 500-word articles.
3. Editor reviews, fixes grammar, checks sources.
4. Designer creates thumbnail graphics from article text.
5. Marketer writes social media captions.

All five profiles have their own Kanban lane. New stories enter Triage daily. The dispatcher auto-assigns and parallelizes: five researchers work on five stories; five writers work on five summaries; five editors review five articles. The whole pipeline runs in parallel, bounded only by the number of available workers (and your LLM API quota).

Handling Failures: Retries, Circuit Breakers, and Crash Recovery

Things break. Your job is to make sure breaks are recoverable and visible.

Retry Logic

A task fails if a worker exits with an error. The dispatcher detects this and retries with a fresh worker. By default, Hermes retries 3 times. If all retries fail, the task moves to Blocked with the error reason.

Example: engineer tries to run tests but PostgreSQL is down. Worker fails with error "Unable to connect to database." Dispatcher retries 30 seconds later. PostgreSQL is back up. Retry succeeds. Task moves to Running, then Done.

You can see all attempts in the task history. Click "Show runs" in the dashboard to see all three attempts, all error logs, which attempt succeeded, and timestamps.

Circuit Breakers

If a task fails 3 times with the same error (e.g., missing AWS credentials), Hermes stops retrying and moves the task to Blocked with outcome gave_up. The circuit breaker prevents infinite retry loops that waste resources and API quota.

Example: engineer has AWS_ACCESS_KEY_ID missing. Tries to deploy. Fails with "Unable to assume role: AccessDenied." Retries. Fails again. Retries. Fails a third time. Circuit breaker activated: task blocked, outcome gave_up, reason "AWS credentials missing or invalid."

Now a human reads the block reason, fixes the credentials, and manually moves the task back to To Do / Ready. Dispatcher spawns a fresh worker with fixed credentials. Success. Task flows to Review and Done.

Crash Recovery

A worker process dies mid-task (OOM killer, segfault, network timeout, or manual kill). The dispatcher (a long-running daemon) detects the dead PID and automatically reclaims the task.

Example: migration script hits 2.3M rows and runs out of memory. Worker process is killed by OS. PID is dead. Dispatcher notices within 30 seconds. Reclaims task. Spawns a fresh worker with the same task. Human can adjust the strategy (chunk the migration, reduce parallelism) and re-run.

The key: the task is still in Running. It has not been lost. Retry is automatic and transparent.

Inspecting a Task in Flight

hermes kanban show <task_id>
hermes kanban runs <task_id>

The first command shows the current task state and metadata. The second shows all attempts (runs). You can see logs from each attempt, which worker claimed it, when it started and ended, the outcome (success, blocked, gave_up, etc.), and any error messages.

Best Practices for Failure Handling

1. Write clear error messages in your profiles. "Unable to assume AWS role: check AWS_ACCESS_KEY_ID and ensure it has proper permissions" is better than "Error: 403."
2. Use structured metadata in kanban_complete() to record what was attempted, why a task failed, and what you tried before giving up.
3. Set sensible retry limits. 3 is often good; adjust for your use case (IO tasks might need 5, external API calls might need 10).
4. Review Blocked tasks daily. They are not stuck forever; they are waiting for human action or external fixes.
5. Monitor task run histories. If the same error repeats across multiple tasks, something systemic is broken and needs investigation.

Honest Trade-Offs: When to Use Kanban, When to Skip It

Kanban is not magic. It is a tool with clear strengths and clear limits.

When Kanban is Worth It

Multi-step projects where handoff quality matters: metadata and summaries become the contract between agents. Recurring workflows: you run the same pipeline weekly, monthly, or daily, so amortizing setup cost is worth it. Team-like work: multiple specialized agents or humans involved. Audit trail requirements: you need to prove who did what and why. Retry-heavy work: tasks sometimes fail and need human judgment on how to proceed.

When Kanban is Overkill

One-shot prompts: ask Claude once, get an answer. Stateless request-response work: no state to track between steps. Simple sequential tasks: task A finishes, task B starts, done; no parallelism or branching. Fire-and-forget subagents: spawn a worker, wait for result, discard worker; no handoff or audit required. For these, simpler tools cost less and run faster.

Real Limitations

Single-host only: Kanban runs on one machine. Multi-machine or cloud-distributed boards are not (yet) supported. You cannot run Kanban on AWS Lambda or split it across five servers. SQLite scalability: designed for thousands of tasks, not 10K+ concurrent tasks. If you need massive throughput (enterprise-scale task processing), you will hit the ceiling. Initial setup friction: creating profiles, writing descriptions, setting API keys takes time. It is not zero-friction. Learning curve: six columns, dispatcher, orchestrator, profiles, metadata, structured handoff--there are concepts to learn. Expect team ramp-up time.

The Honest Take

Kanban is best for teams or solo developers running recurring, multi-step workflows where structured handoff and audit trails matter. If you are shipping one feature or running simple one-off tasks, use simpler tools (chat, simple subagents, manual scripts).

If you do need Kanban, invest in profile descriptions and metadata format. Bad descriptions lead to bad routing and wasted retries. Good descriptions compound: better routing, fewer mistakes, faster workflows.

Frequently Asked Questions

What is the difference between Kanban and simple subagents?

Subagents are ephemeral: you spawn them, they work, they die, and all context is lost. Kanban tasks are durable: they survive restarts, include structured metadata for downstream tasks, and have human review gates. Use subagents for simple work; use Kanban for multi-step handoff where history matters.

How do I set up Kanban on managed infrastructure?

Opsily's managed Hermes includes persistent SQLite backups, so your Kanban board survives infrastructure restarts. You still do the same setup (profiles, API keys, dashboard), but Opsily handles database backups and uptime. See the Opsily Hermes Agent pricing page for hosting options and cost.

Can I use Kanban across multiple machines?

Not directly. Kanban runs on a single host and uses a local SQLite database. If you need multi-machine coordination, run separate Kanban instances on each machine or use a custom orchestration layer to sync state.

Do agents automatically know about Kanban tasks?

Yes. The dispatcher spawns a worker with the HERMES_KANBAN_TASK environment variable set to the task ID. The worker calls kanban_show() to read the task, dependencies, and metadata. It all happens automatically; agents do not need special code to opt in.

What happens if my worker crashes mid-task?

The dispatcher detects the dead process and automatically reclaims the task. It spawns a fresh worker with the same task. No manual intervention needed. The task stays in Running; it is not lost.

How do I inspect a task currently running?

Use hermes kanban show <task_id> for the current state and hermes kanban runs <task_id> for the full history of all attempts. You can see logs, start and end times, and outcomes for each attempt.

Why does profile description quality matter?

The orchestrator reads profile descriptions to decide which profile should claim which task. Vague descriptions lead to wrong assignments and wasted retries. Specific descriptions improve routing. A one-sentence description per profile is the minimum; two sentences explaining what the profile is good at is ideal.

The Bottom Line

Hermes Kanban is a durable, human-gated task board for coordinating multi-agent work. It is not for one-shot prompts or simple request-response workflows. It is for recurring, multi-step projects where structured handoff and audit trails matter.

Start with clear profile descriptions. Test on a small workflow (3-5 tasks). Watch the board for a few cycles to understand your failure modes and retry patterns. Once confident, scale to larger pipelines.

The honest trade-off: Kanban adds structure and visibility at the cost of initial setup. If your workflow is truly simple, skip it. But if you are shipping complex features across multiple agent profiles, Kanban removes manual handoffs and gives you a clear audit trail.

Ready to run Hermes Kanban on infrastructure you do not have to manage? Opsily's hosted Hermes Agent includes persistent SQLite backups, multi-profile support, and 24/7 uptime. Check out Opsily's managed Hermes Agent to get started.