Hermes Kanban Internals: Multi-Agent Orchestration from SQLite to Dashboard

Tasks

Each task is a row with:

• title, body (markdown)
• assignee — a profile name (e.g., researcher, backend-dev)
• status — triage → todo → ready → running → blocked → done → archived
• tenant — optional namespace for multi-client fleets
• idempotency key — dedup for automated task creation
• priority, workspace kind, max_runtime

Links (Dependencies)

task_links rows record parent → child edges. The dispatcher promotes todo → ready when all parents reach done. This is the dependency engine — no manual coordination.

Runs (Attempt History)

A task is a logical unit; a run is one attempt. When the dispatcher claims a ready task, it creates a task_runs row. When the attempt ends (completed, blocked, crashed, timed out, spawn_failed, reclaimed), the run closes with an outcome.

Why two tables: you need full attempt history for postmortems and a clean place to hang per-attempt metadata. A task attempted three times has three task_runs rows.

Events

Every transition appends a row to task_events. Three clusters:

• Lifecycle: created, promoted, claimed, completed, blocked, unblocked, archived
• Edits: assigned, edited, reprioritized, status (drag-drop)
• Worker telemetry: spawned, heartbeat, reclaimed, crashed, timed_out, spawn_failed, gave_up

Step 1 — Orient

1
# Worker tool call (NOT a shell command)
2
kanban_show()

Returns title, body, worker_context (parent handoffs, prior attempts, comment thread), workspace path, and tenant. The worker reads this to understand what to do and what’s already been tried.

Step 2 — Work

1
# cd to workspace, do the actual work
2
# terminal tool calls happen here

Step 3 — Heartbeat (for long operations)

1
kanban_heartbeat(note="scanned 1.2M/2.4M rows")

Every few minutes max. Skip for tasks under ~2 minutes.

Step 4 — Complete or Block

1
kanban_complete(
2
    summary="migrated limiter.py to token-bucket; added 14 tests, all pass",
3
    metadata={
4
        "changed_files": ["limiter.py", "tests/test_limiter.py"],
5
        "tests_run": 14,
6
        "decisions": ["user_id primary, IP fallback for unauthenticated requests"],
7
    },
8
)

Or if stuck:

1
kanban_block(reason="Rate limit key choice: IP (simple, NAT-unsafe) or user_id?")

Step 5 — Handoff

The summary and metadata are the primary handoff channel. When a downstream worker calls kanban_show(), it sees:

• Prior attempts on its own task (outcome, summary, error, metadata) — so retrying workers don’t repeat failed paths
• Parent task results — the most-recent completed run’s summary and metadata — so downstream workers know what upstream decided

This replaces the “dig through comments and output” dance. A PM writes acceptance criteria in metadata; the engineer’s worker sees them structurally. An engineer records test results; the reviewer has that list before opening a diff.

Step 6 — Cleanup

The dispatcher detects the worker is done (via the completed/blocked status change) and moves to the next ready task.

Fan-out + Fan-in (Most Common)

N researchers in parallel, one analyst synthesizing:

1
# Create parallel research tasks
2
R1=$(hermes kanban create "Postgres cost analysis" --assignee researcher --json | jq -r .id)
3
R2=$(hermes kanban create "Postgres perf benchmarks" --assignee researcher --json | jq -r .id)
4
R3=$(hermes kanban create "Postgres operational complexity" --assignee researcher --json | jq -r .id)
5

6
# Synthesis depends on all three
7
hermes kanban create "migration recommendation report" \
8
  --assignee analyst \
9
  --parent $R1 --parent $R2 --parent $R3 \
10
  --body "1-page recommendation with explicit trade-offs and go/no-go call"

Only R1, R2, R3 start in ready. The synthesis task auto-promotes when all three hit done.

Pipeline with Gates

PM writes spec → engineer implements → reviewer approves or blocks → engineer iterates:

1
SPEC=$(hermes kanban create "spec: password reset flow" --assignee pm --json | jq -r .id)
2
IMPL=$(hermes kanban create "implement password reset" --assignee backend-dev --parent $SPEC --json | jq -r .id)
3
REVIEW=$(hermes kanban create "review password reset PR" --assignee reviewer --parent $IMPL --json | jq -r .id)

If the reviewer blocks, you don’t re-run the same task. You create a new task linked from the reviewer’s task, assigned back to the engineer. Each iteration is a fresh task with its own run history.

Human-in-the-Loop

Workers block when they need a decision. You respond via comment, then unblock:

1
# Worker blocked itself
2
# hermes kanban show t_xyz
3
# → status: blocked, reason: "Which schema: v1 (simple) or v2 (normalized)?"
4

5
hermes kanban comment t_xyz "Use v2 — normalized. We need the flexibility for the analytics pipeline."
6
hermes kanban unblock t_xyz

The next spawn of that task reads the comment thread in kanban_show(), so the worker sees your decision without you having to find its terminal session.

1. Write Structured Handoff Metadata

Every kanban_complete should include metadata that answers four questions for the next reader:

1. What changed?
2. How was it verified?
3. What can unblock or retry this if it fails?
4. What risk is still deliberately left open?

1
kanban_complete(
2
    summary="shipped rate limiter — token bucket, 14 tests pass",
3
    metadata={
4
        "changed_files": ["rate_limiter.py", "tests/test_rate_limiter.py"],
5
        "verification": ["pytest tests/ -q"],
6
        "dependencies": ["parent task t_schema"],
7
        "blocked_reason": None,
8
        "residual_risk": ["no load testing yet — needs staging deploy"],
9
    },
10
)

2. Restrict Orchestrator Toolsets

Pair the orchestrator with a profile that only has kanban, gateway, and memory tools. If the orchestrator can’t call terminal or file, it can’t “just fix this quickly” and break the routing contract.

3. Use Triage for Vague Ideas

Don’t create fully-specified tasks for half-baked ideas. Park them in triage:

1
hermes kanban create "something about the landing page" --assignee pm --triage

A specifier profile can then flesh out the body and promote to todo.

4. Set Max Runtime

Prevent zombie workers from burning API credits:

1
hermes kanban create "bulk translate 500 files" \
2
  --assignee translator \
3
  --max-runtime 2h

When the limit is exceeded, the dispatcher SIGTERMs the worker, then SIGKILLs after 5 seconds grace.

5. Use Idempotent Keys for Automation

Prevent duplicate tasks from cron jobs or webhooks:

1
hermes kanban create "nightly ops review" \
2
  --assignee ops \
3
  --idempotency-key "nightly-ops-$(date -u +%Y-%m-%d)" \
4
  --json

First call creates the task. Subsequent calls with the same key return the existing task ID.

6. Profile Sessions Are Invisible to the Main Agent

1
hermes sessions list                    # ← your main agent only
2
hermes sessions list --profile researcher  # ← profile sessions
3
hermes chat --profile researcher --resume <session-id>

7. Heartbeats Should Name Progress

Good: "epoch 12/50, loss 0.31", "uploaded 47/120 videos" Bad: "still working", empty notes

8. Block Reasons Should Be One Sentence

The block message appears in dashboard notifications and gateway pings. Keep it scannable. Put the long context in a comment:

1
kanban_comment(
2
    task_id=os.environ["HERMES_KANBAN_TASK"],
3
    body="Full context: I have user IPs from Cloudflare headers but some users are behind NATs with thousands of peers.",
4
)
5
kanban_block(reason="Rate limit key: IP (NAT-unsafe) or user_id (requires auth)?")

9. Don’t Bulk-Close with Shared Summaries

1
# This is REFUSED — structured handoff is per-run
2
hermes kanban complete a b c --summary "all done"
3

4
# This works — for admin/batch cleanup
5
hermes kanban complete a b c

10. Watch for Circuit Breaker Trips

After 5 consecutive spawn failures (configurable via --failure-limit), the task auto-blocks with gave_up. Check the error, fix the profile config or workspace, then unblock. The dashboard and hermes kanban runs <id> show the full failure history.

The Old Pipeline: Single-Agent Cron

The original setup was one cron job firing at 9:00 AM HKT, spawning a single sub-agent that:

1. Ran 14 web searches sequentially (no parallelism)
2. Wrote a markdown report
3. Updated a landing page
4. Posted a Discord notification

Problems:

• No parallel execution — one search failure could stall the entire pipeline
• No separation of concerns — the same agent handled research, writing, and publishing
• No verification or retry — failures were final
• Sub-agent limitations — sub-agents only get AGENTS.md and tool docs, no memories or system prompts, making them less capable than the main agent
• Shell date bug — the date command syntax in the prompt was passed literally to search queries instead of being executed, producing stale/literal date strings

The result: report quality degraded over time, with fewer sources and shorter articles.

The New Pipeline: Kanban Multi-Stage

The redesigned pipeline uses a parent task with nine children across three stages:

1
Stage 1 — Research (5 parallel workers)
2
├── Model Releases
3
├── Tool Releases
4
├── Agent Frameworks
5
├── Trending Workflows
6
└── Active Inputs (ad-hoc queries)
7

8
Stage 2 — Verification (2 editors, blocked by Stage 1)
9
├── Editor Alpha — filter duplicates, check dates, rank by importance
10
└── Editor Beta — cross-reference and fill gaps
11

12
Stage 3 — Publishing (2 publishers, blocked by Stage 2)
13
├── Write Report
14
└── Post Notifications

Results: more structured reports with proper tables, categorization, 48-hour verification, and broader source coverage.

Profile Setup Lessons

Key lessons from setting up specialist profiles:

1. Feed the documentation first — don’t assume the agent knows about Kanban features. Link the official docs and ask it to understand them before designing the pipeline.
2. API keys don’t auto-propagate — profile .env files are empty by default. Copy the relevant keys from your main agent’s .env to each profile.
3. Remove empty API key fields from config.yaml — asterisk placeholders cause errors.
4. Reuse the same API key across profiles — especially useful for coding plans with token quotas.
5. Tune reasoning effort per role — research profiles at 90-100 (needs critical thinking), editors at 50-70 (synthesis), publishers at 20-30 (mechanical).

The Cron + Kanban Gap: Four Problems

Combining Kanban with cron jobs revealed fundamental friction:

Problem 1: Gateway exits early. The gateway dispatches ready tasks then exits. If a child is waiting for a parent that completes after the gateway exits, the child never gets dispatched. The solution: run the gateway as a systemd service to keep it alive permanently (works well on VPS, expensive on local).

Problem 2: Duplicate task creation. During test runs, the agent created new parent tasks without checking if one already existed for that date. Orphaned test tasks then confused the production cron run, producing duplicate notifications.

Problem 3: No native synergy. Cron jobs fire on schedule and don’t check the Kanban board before creating tasks. Without custom deduplication logic, every cron run creates a fresh task set regardless of what’s already running or completed.

Problem 4: Task accumulation. Completed parent tasks stay on the board forever unless archived. After a week of daily runs, that’s 7 parents and 63 children cluttering the board, making monitoring harder and increasing the risk of accidental re-dispatch. There’s currently no delete button in the dashboard.

Final Architecture

The working solution combines cron + Kanban with custom safeguards:

1
Cron fires (`9:00 AM` HKT)
2
  → Deduplication check (search existing tasks for today's date)
3
  → Create Kanban parent task + 9 children
4
  → Gateway runs as systemd service (persistent)
5
  → Pipeline executes through all stages
6
  → Discord notifications on completion

The takeaway: Kanban is excellent for multi-agent orchestration, but pairing it with cron requires custom deduplication logic and persistent gateway management. For non-cron projects, Kanban works out of the box with no friction.

Video: Hermes Agent Kanban + Cron Job is POWERFUL (Setup Guide) by BoxminingAI (Superbash)