# Hermes Kanban Guide > A guide to Hermes Kanban: the durable queue that Hermes Agent profiles work out > of. You create cards; a dispatcher claims them and spawns the assigned profile > as a real OS process. Aimed at operators who already run Hermes and are > confused by the board specifically. An independent guide to Hermes Agent, a product of Nous Research. Not published or endorsed by them. Every machine fact is quoted from the hermes-agent repository: website/docs/user-guide/features/kanban.md, kanban-tutorial.md, and plugins/kanban/dashboard/plugin_api.py. The complete content of this site is available as structured JSON at https://hermes-kanban-guide.pages.dev/index.json, which is generated from the same source as the HTML. ## The one-paragraph answer A card names a profile. The dispatcher sweeps the board every 60 seconds (default), and one pass does five things in this order: reclaim stale claims; reclaim crashed workers; promote todo to ready where every parent is done; claim atomically, one worker per card; spawn the assigned profile. The worker calls kanban_show to read its own card and worker context, works, then calls kanban_complete with a summary and metadata. Nothing is held in a session; every handoff is a row in ~/.hermes/kanban.db. Kanban is not delegate_task. delegate_task is a function call: fork, join, one anonymous subagent, answer returns to your context, and failed is failed. Kanban is a queue with a state machine: fire and forget, named profiles with their own memory, block/unblock/re-run, crash and reclaim. They are not alternatives, and a kanban worker can call delegate_task inside its own run. ## Pages - [Hermes Kanban](https://hermes-kanban-guide.pages.dev/): Hermes Kanban is a durable queue your agent profiles work out of. How the dispatcher claims cards and spawns workers, and how it differs from delegate_task. - [The board](https://hermes-kanban-guide.pages.dev/board): Step a simulated Hermes Kanban board one dispatcher tick at a time. Watch a card get claimed, spawned, completed, and promote its dependents. - [Your first board](https://hermes-kanban-guide.pages.dev/first-board): Four commands, in order, to get a Hermes Kanban card running on your own machine, with the two steps that most often leave a board silent. - [Common situations](https://hermes-kanban-guide.pages.dev/situations): Ten shapes of real work on a Hermes Kanban board: fan out, chain, decompose, long runs, review gates, boards, lanes, and when to skip the board. - [Best practices](https://hermes-kanban-guide.pages.dev/practices): Rules for writing Hermes Kanban cards, wiring dependencies, running a board and knowing when to stop, each naming the failure it prevents. - [When it breaks](https://hermes-kanban-guide.pages.dev/troubleshooting): Nine Hermes Kanban failure symptoms with their cause and the one command that diagnoses each, plus the five reasons a board sits completely still. - [Reference](https://hermes-kanban-guide.pages.dev/reference): Hermes Kanban reference: the columns, the agent toolset, the CLI commands, the config defaults under kanban:, and where the board files live on disk. ## Vocabulary that is Kanban-only These words behave differently in Kanban than elsewhere in Hermes. This is the model gap the guide exists to close. - **Tick** (kanban dispatch · 60 s): One pass of the dispatcher. Default 60 seconds. Nudge dispatcher forces one now instead of waiting for the timer. - **Claim** (claimed event): The atomic step that moves a card to running and pins it to one worker. Two dispatchers cannot claim the same card. - **Worker** (HERMES_KANBAN_BOARD pinned in the child env): A full OS process running the assigned profile, spawned for one card. Not a subagent: its own identity, its own memory, its own tools. - **Run** (task_runs): One attempt. Outcome, summary, metadata, error. Retry history is the primary representation, not a latest-state field on the card. - **Worker context** (build_worker_context): What the worker is handed when it calls kanban_show: the card, its own prior attempts, each parent's most recent completed summary and metadata, the comment thread, attachment paths. - **Link** (task_links): A parent to child dependency. The dispatcher promotes todo to ready once every parent is done. You do not move it yourself. - **Triage** (kanban.auto_decompose_per_tick: 3): Where a one-line idea lands. With auto-decompose on, the decomposer splits it into assigned children, at most 3 cards per tick. - **Workspace** (~/.hermes/kanban/workspaces//): Where the worker works. scratch is deleted on completion; dir: must be an absolute path and is preserved; worktree is preserved. - **Artifacts** (kanban_complete(artifacts=[...])): Files the worker declares when it completes. They are copied into per-task attachment storage before the scratch directory is removed. - **Heartbeat** (dispatch_stale_timeout_seconds · 4 h): A long-running worker reporting in, so the dispatcher does not reclaim its card as a stale claim. - **Tenant** (--tenant auth-project): A soft label inside one board. Boards are the hard boundary. A worker cannot see another board, and links across boards are refused. - **Comment** (kanban_comment): The inter-agent protocol. A re-spawned worker reads the whole thread as part of its context, so notes you leave are instructions. ## Failure symptoms, keyed by the event name on the board - `no events` — Nothing moves at all. Cause: The gateway is not running, so no dispatcher is sweeping the board. Diagnose: `hermes gateway start`. Check the gateway before anything else. No gateway means no ticks, and the board looks identical to a board with no work. - `no runs` — One card sits in Todo forever. Cause: It is waiting on a parent, or its assignee is not a profile that exists. Diagnose: `hermes profile list`. Compare the assignee on the card with that list. A typo here is silent by design. - `gave_up` — Two failed attempts, then it stopped. Cause: The circuit breaker tripped after failure_limit attempts, which is 2 by default. Diagnose: `hermes kanban runs t_abcd`. Read the error on the attempts. Identical messages mean the environment is wrong, not the work. - `crashed` — The worker vanished mid-job. Cause: The process died: out of memory, killed, or the machine slept. Diagnose: `hermes kanban runs t_abcd`. The dispatcher reclaims the card and a fresh worker gets it, which can read why the last one died. - `stale` — A card came back after hours of silence. Cause: It missed its heartbeat, so the dispatcher stopped believing the worker was alive. Diagnose: `hermes kanban show t_abcd`. Long jobs must heartbeat at least hourly. The stale timeout is 4 hours. - `blocked` — It stopped and asked me something. Cause: A worker called kanban_block on purpose rather than guessing. Diagnose: `hermes kanban unblock t_abcd`. Answer or fix the thing it names, then unblock. It returns to Ready and a fresh worker picks it up. - `block_loop_detected` — It keeps blocking on the same thing. Cause: The same card blocked for the same reason twice, so the board stopped the loop. Diagnose: `hermes kanban show t_abcd`. Two identical blocks mean the card is unanswerable as written. Rewrite the card, do not unblock it again. - `protocol_violation` — The worker did something malformed. Cause: The agent produced output the board could not accept, three times. Diagnose: `hermes kanban runs t_abcd`. Usually a profile without the kanban tools, or a model too small to follow the contract. Change the profile, not the card. - `timed_out` — It ran out of time. Cause: The card exceeded its allowed run time and was cut off. Diagnose: `hermes kanban runs t_abcd`. Either the card is too big for one worker, or it needed to be several cards with parents. A board that does nothing at all has five candidate causes, in the order worth checking: the gateway is not running (`hermes gateway start`); the assignee is not a profile that exists (`hermes profile list`); the card is in Todo waiting on a parent; you are looking at a different board (`hermes kanban boards show`); or a second gateway owns the dispatcher, when exactly one may keep `kanban.dispatch_in_gateway` true. ## When to use a board, and when not to - **Fan out · independent cards** — Five of the same job, and you do not want to sit through them `hermes kanban create "transcribe call 4" --assignee transcriber` Skip it when: If the five are really one job cut into five, write one card. Five cards rebuild the same context five times and you pay for it five times. - **Chain · parents and children** — Each step needs the answer from the step before it `hermes kanban create "write the tests" --assignee qa-dev --parents t_23f6` Skip it when: Do not chain steps that do not truly depend on each other. A false chain turns work that could have run at once into a queue. - **Triage · decompose** — You know what you want but cannot yet name the tasks `hermes kanban decompose t_abcd` Skip it when: If you can already name the tasks, name them yourself. Decomposition spends a model call to invent structure you would have written better. - **Long run · heartbeat** — The job runs for hours and you want to walk away `hermes kanban runs t_abcd` Skip it when: The machine has to stay awake. A sleeping laptop is the single most common reason a long card comes back as crashed. - **Human in the loop · review** — Nothing ships until you have looked at it `hermes kanban list --status review` Skip it when: Do not gate everything. A board where every card waits for you is a to-do list with extra steps. - **Scheduled · recurring** — The same sweep every morning that you keep forgetting `hermes kanban list --status scheduled` Skip it when: If the sweep produces nothing you read, deleting the habit beats automating it. - **Boards · hard boundary** — Two clients whose work must never mix `hermes kanban boards create client-b` Skip it when: For work that is merely different, use --tenant on one board. Tenants filter; boards isolate. Reach for the heavier tool only when a leak would actually matter. - **Lanes · one workspace each** — Two agents editing the same repository `hermes kanban show t_abcd --json` Skip it when: One agent and one branch is fine. Parallel edits to one repo need a plan for merging, and the plan is your job. - **Queue · notify on endings** — Fill the board at night, read it with coffee `hermes kanban notify-subscribe --kinds completed,gave_up` Skip it when: Subscribe to endings only. Subscribe to every event and you will mute the channel within a day, which is worse than no notifications. - **The honest one** — When not to use the board at all `hermes chat` Skip it when: The board earns its keep when work is genuinely parallel, genuinely dependent, or genuinely long. Not before. ## Quickstart ``` hermes kanban init hermes dashboard hermes kanban create "summarise my inbox" --assignee researcher hermes gateway start ``` The dashboard serves http://127.0.0.1:9119. The assignee must name a profile that exists; a card addressed to a name that does not exist sits in Todo silently and nothing tells you why. That is the most common first failure. ## Defaults - `kanban.dispatch_in_gateway`: true. Exactly one gateway may keep this on. - `kanban.failure_limit`: 2. Consecutive spawn failures before the circuit breaker blocks the card. - `kanban.auto_decompose`: true. - `kanban.auto_decompose_per_tick`: 3. - `kanban.dispatch_stale_timeout_seconds`: 4 hours. - `kanban.orchestrator_profile`, `kanban.default_assignee`: unset. - Default board: `~/.hermes/kanban.db`. Named boards: `~/.hermes/kanban/boards//kanban.db`. - Card workspace: `~/.hermes/kanban/workspaces//`, deleted on completion except declared artifacts.