Hermes Kanban Guide

SQLite-backed task board shared across profiles • Hand-crafted reference

What is Hermes Kanban?

A durable task queue built into Hermes. Tasks live in SQLite, survive restarts, and can be claimed atomically by different profiles. Think of it as a shared todo list that multiple agents/workers can pull from.

Unlike cron (scheduled), kanban is demand-driven. Tasks sit until someone claims them.

Core Concepts

Boards

Each board is a separate SQLite database. One board per project or work stream.

$ hermes kanban boards --create my-project

Task States

Status Meaning Badge
triage New task, needs specification triage
todo Specified but waiting todo
ready Unclaimed and ready to run ready
running Currently being worked on running
blocked Waiting on dependency or external blocked
done Completed done

Lifecycle Flow

Create
→
Triage
→
Todo
→
Ready
→
Running
→
Done

Essential Commands

Create a Task

# Basic task
hermes kanban create "Fix the login bug"

# With body
hermes kanban create "Refactor auth" --body "Move JWT to utils/ folder"

# Auto-assign to a profile
hermes kanban create "Research MCP" --assignee tina

# Start in triage (needs spec)
hermes kanban create "Big feature" --triage

# Set max runtime (minutes)
hermes kanban create "Scraping job" --max-runtime 60

List Tasks

# All tasks on current board
hermes kanban list

# Filter by status
hermes kanban list --status ready
hermes kanban list --status running

# Just my tasks
hermes kanban list --mine

# Specific assignee
hermes kanban list --assignee tina

Claim & Work

# Claim next ready task (atomic - only one wins)
hermes kanban claim

# Claim specific task
hermes kanban claim --id t_abc123

# After working, mark complete
hermes kanban complete t_abc123

# Or mark blocked
hermes kanban block t_abc123

Task Operations

# Show task details + comments
hermes kanban show t_abc123

# Add comment
hermes kanban comment t_abc123 "Stuck on API rate limits"

# Reassign
hermes kanban assign t_abc123 --assignee other-profile

# Edit task (even after done, for recovery)
hermes kanban edit t_abc123 --body "Updated requirements..."

# Archive old tasks
hermes kanban archive t_abc123

Worker Pattern

The kanban dispatcher runs automatically with Hermes gateway. It:

  1. Reclaims stale tasks (workers that died)
  2. Promotes todo → ready
  3. Spawns workers for ready tasks
# Check what task worker sees (full context)
hermes kanban context t_abc123

# View worker logs
hermes kanban log t_abc123

# See all attempts/runs
hermes kanban runs t_abc123

# Watch live events
hermes kanban watch
Run hermes kanban dispatch to force a dispatcher pass manually (useful for testing).

Task Dependencies

Tasks can block on other tasks. Parent must complete before child becomes ready.

# Create parent task
PARENT=$(hermes kanban create "Setup database" --json | jq -r '.id')

# Create child with dependency
hermes kanban create "Seed data" --parent $PARENT

# Link existing tasks
hermes kanban link t_parent t_child

# Remove dependency
hermes kanban unlink t_parent t_child

Board Management

# List all boards
hermes kanban boards

# Create new board
hermes kanban boards --create side-projects

# Switch board (set env var)
export HERMES_KANBAN_BOARD=side-projects

# Or use --board flag
hermes kanban list --board side-projects

# Board stats
hermes kanban stats

Quick Reference Card

Command Purpose
hermes kanban init Create kanban.db if missing
hermes kanban create "Title" New task
hermes kanban list Show all tasks
hermes kanban claim Grab next ready task
hermes kanban complete ID Mark done
hermes kanban block ID Mark blocked
hermes kanban unblock ID Resume blocked task
hermes kanban show ID Task details + comments
hermes kanban context ID What worker sees
hermes kanban watch Live event stream

When to Use Kanban

Good for:

Use cron instead when: