hermes kanban Command — Complete Reference & Examples

Overview

hermes kanban is a durable SQLite-backed task board shared across Hermes profiles. Tasks can depend on other tasks, are claimed atomically, and are executed by a named profile in an isolated workspace.

hermes kanban [--board <slug>] <subcommand>

Global option

• --board <slug> — Operate on a specific board. Defaults to the current board (set via hermes kanban boards switch <slug> or the HERMES_KANBAN_BOARD environment variable).

Subcommands

Board setup

init

Create kanban.db if missing (idempotent).

hermes kanban init

boards

Manage boards. One board per project/workstream.

hermes kanban boards list [--json] [--all]
hermes kanban boards create <slug> [--name NAME] [--description DESCRIPTION] [--icon ICON] [--color COLOR] [--switch] [--default-workdir PATH]
hermes kanban boards rm <slug> [--delete]
hermes kanban boards switch <slug>
hermes kanban boards show
hermes kanban boards rename <slug> <name>
hermes kanban boards set-default-workdir <slug> [path]

• list / ls — List all boards with task counts.
• create / new — Create a new board.
• rm / remove / delete — Archive a board (default) or hard-delete it with --delete.
• switch / use — Set the active board.
• show / current — Print the currently-active board slug.
• rename — Change a board’s display name (slug is immutable).
• set-default-workdir — Set or clear the default workspace path for a board.

Task lifecycle

create <title>

Create a new task.

hermes kanban create "Implement auth" --body "Add OAuth login" --assignee work --workspace worktree --priority 1

list / ls

List tasks.

hermes kanban list [--mine] [--assignee ASSIGNEE] [--status STATUS] [--tenant TENANT] [--session SESSION] [--archived] [--json] [--sort SORT]

show <task_id>

Show a task with comments and events.

hermes kanban show <task_id> [--json] [--state-type {status,outcome}] [--state-name VALUE]

assign <task_id> <profile>

Assign or reassign a task. Use none to unassign.

hermes kanban assign <task_id> work

set-model <task_id> [model]

Set or clear a task’s model/provider override.

hermes kanban set-model <task_id> claude-sonnet --provider anthropic
hermes kanban set-model <task_id> none

reclaim <task_id>

Release an active worker claim on a running task.

hermes kanban reclaim <task_id> [--yes]

reassign <task_id> <profile>

Reassign a task to a different profile, optionally reclaiming first.

hermes kanban reassign <task_id> <profile> [--reclaim] [--yes]

claim <task_id>

Atomically claim a ready task.

hermes kanban claim <task_id> [--ttl 900]

complete <task_id>...

Mark one or more tasks done.

hermes kanban complete <task_id> --result "Done" --summary "Implemented" --metadata '{"files": ["auth.py"]}'

edit <task_id>

Edit recovery fields on an already-completed task.

hermes kanban edit <task_id> --result "Updated" --summary "..."

block <task_id> [reason...]

Mark one or more tasks blocked.

hermes kanban block <task_id> "waiting for API" --kind dependency

unblock <task_id>...

Return blocked/scheduled tasks to ready or todo.

hermes kanban unblock <task_id> --reason "API ready"

schedule <task_id> [reason...]

Park one or more tasks in Scheduled.

hermes kanban schedule <task_id> "deploy window" --ids t2 t3

promote <task_id> [reason...]

Manually move todo/blocked tasks to ready.

hermes kanban promote <task_id> "ready to start" [--force] [--dry-run] [--json]

archive <task_id>...

Archive one or more tasks. Use --rm to permanently delete already-archived task ids.

hermes kanban archive <task_id>... [--rm PURGE_IDS...]

Task decomposition

specify [task_id]

Flesh out a triage-column task into a concrete spec and promote it to todo.

hermes kanban specify <task_id> [--all] [--tenant TENANT] [--author AUTHOR] [--json]

decompose [task_id]

Decompose a triage-column task into child tasks routed to specialist profiles.

hermes kanban decompose <task_id> [--all] [--tenant TENANT] [--author AUTHOR] [--json]

swarm <goal>

Create a Kanban Swarm v1 graph: parallel workers → verifier → synthesizer.

hermes kanban swarm "Refactor auth" --worker backend:Backend --worker frontend:Frontend --verifier reviewer --synthesizer writer

Dependencies

link <parent_id> <child_id>

Add a parent→child dependency.

hermes kanban link parent-task child-task

unlink <parent_id> <child_id>

Remove a parent→child dependency.

hermes kanban unlink parent-task child-task

Execution & monitoring

dispatch

One dispatcher pass: reclaim stale claims, promote ready tasks, spawn workers.

hermes kanban dispatch [--dry-run] [--max N] [--failure-limit N] [--json]

daemon

Deprecated — dispatcher now runs in the gateway. Use hermes gateway start.

watch

Live-stream task events to the terminal.

hermes kanban watch [--assignee ASSIGNEE] [--tenant TENANT] [--kinds KINDS] [--interval 0.5]

tail <task_id>

Follow a task’s event stream.

hermes kanban tail <task_id> [--interval SECONDS]

log <task_id>

Print the worker log for a task.

hermes kanban log <task_id> [--tail N]

runs <task_id>

Show attempt history for a task.

hermes kanban runs <task_id> [--json] [--state-type {status,outcome}] [--state-name VALUE]

heartbeat <task_id>

Emit a heartbeat event for a running task.

hermes kanban heartbeat <task_id> --note "still running"

Context & attachments

context <task_id>

Print the full context a worker sees for a task.

comment <task_id> <text...>

Append a comment to a task.

hermes kanban comment <task_id> "Waiting on review" --author user

attach <task_id> <path>

Attach a local file to a task.

hermes kanban attach <task_id> ./log.txt --name deploy.log

attachments <task_id>

List a task’s attachments.

hermes kanban attachments <task_id> [--json]

attach-rm <attachment_id>

Delete an attachment by id.

Notifications

notify-subscribe <task_id>

Subscribe a gateway source to a task’s terminal events.

hermes kanban notify-subscribe <task_id> --platform telegram --chat-id 123456

notify-list [task_id]

List notification subscriptions.

hermes kanban notify-list [<task_id>] [--json]

notify-unsubscribe <task_id>

Remove a gateway subscription from a task.

hermes kanban notify-unsubscribe <task_id> --platform telegram --chat-id 123456

Diagnostics & maintenance

diagnostics / diag

List active diagnostics on the current board.

hermes kanban diagnostics [--severity {warning,error,critical}] [--task TASK] [--json]

assignees

List known profiles and per-profile task counts.

hermes kanban assignees [--json]

stats

Show per-status and per-assignee counts plus oldest-ready age.

hermes kanban stats [--json]

gc

Garbage-collect old task events, worker logs, and archived workspaces.

hermes kanban gc [--event-retention-days N] [--log-retention-days N]

repair

Check DB integrity and auto-repair index-only corruption.

hermes kanban repair [--json]

Examples

# Create and switch to a new board
hermes kanban init
hermes kanban boards create sprint-42 --switch

# Add a high-priority task
hermes kanban create "Refactor auth module" --assignee backend --workspace worktree --priority 1

# List ready tasks assigned to the current profile
hermes kanban list --mine --status ready

# Run one dispatch pass
hermes kanban dispatch --max 3

Tips

• Run hermes kanban init once before other commands to create the database.
• Use --board <slug> for one-off commands, or hermes kanban boards switch <slug> to change the default.
• Task statuses include: triage, todo, ready, running, review, blocked, scheduled, done, archived.
• Use claim to atomically pick up ready work; dispatch is the main execution loop.
• daemon is deprecated. Run dispatch through hermes gateway start or schedule hermes kanban dispatch.