The Hermes Kanban system is a durable, SQLite-backed task coordination framework designed for multi-profile and multi-project collaboration. Unlike transient subagent delegations (like delegate_task), the Kanban system persists tasks, state transitions, and inter-agent communication in a shared database, allowing work to survive restarts and involve human intervention website/docs/user-guide/features/kanban.md32-51
The system operates as a cross-profile coordination primitive. While individual profiles maintain their own identities and memories, they all converge on a shared kanban.db located at the Hermes root (typically ~/.hermes/kanban.db) hermes_cli/kanban_db.py1-9 This architecture enables a Dispatcher to claim tasks and spawn specialized Worker profiles to execute them.
The following diagram illustrates how natural language concepts map to specific code entities and storage locations.
Natural Language to Code Entity Space
Sources: hermes_cli/kanban_db.py1-69 hermes_cli/kanban_db.py87-102 website/docs/user-guide/features/kanban.md11-20
The system is divided into three primary layers: the Database Kernel, the CLI/Interface layer, and the Agent Toolset.
The core logic resides in kanban_db.py, which manages the SQLite schema: tasks, task_links, task_comments, and task_events hermes_cli/kanban_db.py55-59 It implements a robust concurrency strategy using WAL mode and BEGIN IMMEDIATE transactions to ensure atomic task claiming by workers via compare-and-swap (CAS) updates on tasks.status and tasks.claim_lock hermes_cli/kanban_db.py61-68
The CLI surface (hermes kanban ...) provides human-facing commands for task management, including creation, listing, and manual state overrides hermes_cli/kanban.py1-13 It also includes a diagnostics engine (kanban_diagnostics.py) for identifying stuck tasks or hallucinated references.
For details, see Kanban Core and CLI.
Agents interact with the board through a specialized toolset (kanban_tools.py) rather than the CLI. This ensures backend portability across different execution environments like Docker, Modal, or SSH, as tools run in the agent's Python process and can always reach the local DB tools/kanban_tools.py9-15 The system also includes a web-based Dashboard Plugin (plugin_api.py and dist/index.js) that provides a visual board view and real-time updates via WebSockets plugins/kanban/dashboard/plugin_api.py1-12
For details, see Kanban Tools and Dashboard.
Tasks follow a strict state machine: triage, todo, scheduled, ready, running, blocked, review, done, and archived hermes_cli/kanban_db.py102
The Dispatcher is a background loop (usually embedded in the Hermes Gateway) that ticks every 60 seconds to website/docs/user-guide/features/kanban.md69-70:
todo tasks to ready once dependencies (links) are satisfied.ready tasks using the assigned profile.BLOCK_RECURRENCE_LIMIT (2) to prevent infinite unblock/re-block loops hermes_cli/kanban_db.py134Task State Machine and Code Transitions
Sources: hermes_cli/kanban_db.py102 hermes_cli/kanban.py36-44 tools/kanban_tools.py132-161 website/docs/user-guide/features/kanban.md62-70
Users can isolate unrelated workstreams by creating separate boards. Each board is a directory under <root>/kanban/boards/<slug>/ containing its own database, workspaces, and logs hermes_cli/kanban_db.py11-18 The system resolves the active board via the HERMES_KANBAN_BOARD environment variable or the kanban/current pointer file hermes_cli/kanban_db.py25-37
| Feature | Description | Code Reference |
|---|---|---|
| Shared Root | All profiles share the same board by default to facilitate coordination. | hermes_cli/kanban_db.py1-9 |
| Workspaces | Supports scratch (ephemeral), worktree (git), and dir:<path> (persistent). | hermes_cli/kanban_db.py135 |
| Circuit Breaker | Auto-blocks tasks after BLOCK_RECURRENCE_LIMIT or DEFAULT_FAILURE_LIMIT. | hermes_cli/kanban_db.py134 |
| Block Kinds | Typed reasons: dependency, needs_input, capability, transient. | hermes_cli/kanban_db.py125 |
| Heartbeat | Workers must call heartbeat_claim within a timeout to prevent reclamation. | hermes_cli/kanban_db.py106-112 |
| Idempotency | Prevents duplicate task creation via an idempotency_key field. | hermes_cli/kanban_db.py550-575 |
Sources: hermes_cli/kanban_db.py1-155 hermes_cli/kanban_db.py550-575 website/docs/user-guide/features/kanban.md57-71
Refresh this wiki
This wiki was recently refreshed. Please wait 3 days to refresh again.