Hermes Conductor

One Hermes conductor. Many coding CLIs. Zero trust in self-reports.

Production orchestration patterns for running external coding agents — Claude Code, OpenCode, Codex CLI, MiMo, agy, or anything else that edits files — under a single Hermes Agent kanban controller.

Distilled from 18 production boards, 367 cards, 566 agent dispatches — and every incident that tried to ruin them.

                          ┌──────────────────────┐
                          │   Hermes Conductor   │
                          │  (route-only profile) │
                          │  "Don't do the work.  │
                          │      Route only."     │
                          └──────────┬───────────┘
                 decompose / fan-out / verify / integrate
          ┌──────────────────┬─────┴────────┬──────────────────┐
          ▼                  ▼              ▼                  ▼
   ┌─────────────┐   ┌─────────────┐  ┌─────────────┐  ┌─────────────┐
   │  worktree   │   │  worktree   │  │  worktree   │  │  worktree   │
   │  lane A     │   │  lane B     │  │  lane C     │  │  lane D     │
   │ Claude Code │   │  OpenCode   │  │  Codex CLI  │  │    MiMo     │
   └──────┬──────┘   └──────┬──────┘  └──────┬──────┘  └──────┬──────┘
          │  diff/tests/commits — verified by the controller, never   │
          ▼  trusted from the agent's own report          ▼
   ┌─────────────────────────────────────────────────────────────────┐
   │              canonical integration branch + evidence            │
   └─────────────────────────────────────────────────────────────────┘

Demos

Both are real runs, no cuts; only idle time is compressed.

1. Native dispatch cycle — the controller creates a card, the gateway dispatcher hands it to a worker profile, the worker implements and tests, and the controller re-runs the tests itself before accepting the evidence. That last step is the whole point.

Cast: demo.cast · narrated cut: SVG / MP4

2. Claude Code as the lane executor (pattern 01) — the controller keeps the card controller-owned, Claude Code works an isolated git worktree headlessly (claude -p), then the controller re-runs the tests and closes the card with evidence. Same board API, any CLI executor.

Cast: demo-claude-code.cast · video: MP4

Lane executor modes: CLI or SDK

Pattern 01 shows the raw CLI lane (claude -p). For production lanes we run a structured runner built on the official Claude Agent SDK instead — same board lifecycle, tighter contract:

• per-lane budget caps (max_budget_usd), max_turns, hard timeout
• explicit allowed/disallowed tool grants per lane (no ambient toolset)
• fail-closed provenance checks: the lane refuses to start if the runtime is not on the expected_model / expected_context_window the card was planned for
• every run emits a JSON receipt (turns, cost, result) that the controller attaches as card evidence instead of parsing chat output

That last point matters more than it sounds: receipts turn "the agent said it went fine" into machine-checkable evidence. The runner is being packaged for separate publication — watch this repo.

Why this exists

The multi-harness wave is here — "Hermes as the brain, other agents as the arms." What the bridge demos don't show you is what happens on day 3:

Every pattern in this repo exists because we hit the failure above it — in production, at 2am, more than once.

The golden rules

1. The orchestrator never implements. Its SOUL.md says: "Do not implement. Do not research. Do not write code. Route only."
2. External agent self-reports are never card-completion evidence. The controller verifies the worktree diff, reruns gates, and completes cards with commit IDs + command output.
3. Every mutating lane gets its own worktree. Parallel cards sharing a checkout is not a workflow, it's a race condition. --workspace worktree or dir: — never the canonical checkout.
4. --parent is a dependency edge, not a folder. Children stay blocked until the parent completes with evidence.
5. Controller-sequential for dependent chains. "Implement all" on a dependency graph is an ordered queue, not a parallel fan-out — unless the plan proves independence.
6. Completing a dependency may auto-promote stale lanes. After every unblock: git worktree list, check each promoted lane's HEAD, block-and-restart anything stale.
7. Standing lanes stay blocked; bounded cron owns execution. Ready + normal assignee on an eternal lane card = the dispatcher will spawn uncontrolled one-shots.
8. Complete with evidence or don't complete. kanban complete <id> --result "commit abc123, gates green" — status flips without evidence get reverted.

Install

The role playbooks are installable Hermes skills:

# on your orchestrator profile's machine/home:
hermes skills install forcewake/hermes-conductor/skills/kanban-orchestrator

# on each worker profile:
hermes skills install forcewake/hermes-conductor/skills/kanban-worker

hermes skills install accepts any owner/repo/path GitHub identifier —
no registry listing needed. The patterns/ docs are meant to be read by
the human operating the controller, not installed.

What's inside

patterns/ — the playbooks

skills/ — installable role playbooks

examples/ — cheatsheet

• kanban-cheatsheet.md — the commands, in the order you'll actually use them.

Quickstart

You have Hermes Agent v0.20+ running with the kanban dispatcher enabled (kanban.dispatch_in_gateway: true).

# 1. Board + first controller-managed card
hermes kanban init
hermes kanban create "Ship feature X" \
  --assignee your-worker-profile \
  --workspace worktree \
  --body "Implement per 01-spec.md. Tests green. Complete with commit ID as evidence."

# 2. Give the orchestrator profile its constitution (SOUL.md):
#    "Do not implement. Do not research. Do not write code. Route only."

# 3. Watch the controller — not the agents — close cards
hermes kanban watch

Then read pattern 01 before your second card. It's the difference between a demo and a pipeline.

Battle scars (where these came from)

• A "successful" overnight swarm where three lanes silently built on a base that no longer existed → patterns 01, 05.
• Two worker cards editing the same checkout for hours before anyone noticed → patterns 02, 05.
• A card auto-promoted by its dependency completing, dispatched into a worktree two days stale → pattern 01's stale-base check.
• A dispatcher loop respawning a worker stuck on an approval, all night → the standing-lane rule.
• Review findings that "fixed" themselves because the reviewer card and the fix card raced → the remediation loop in skills/.

None of these are hypothetical. All of them have a recovery checklist here.

Requirements

• Hermes Agent v0.20+ (kanban CLI + gateway dispatcher)
• External coding CLIs installed and authenticated (any subset — Claude Code, OpenCode, Codex, MiMo, agy, custom)
• git worktrees enabled in your environment

Contributing

Questions, feedback, or your own adaptations of the patterns — post in the discussion board (it's the pinned thread).

Ran a multi-harness board and hit a failure none of these patterns cover? Open an issue with the incident — recovery playbooks from real failures are exactly what this repo collects.

Related

The lane runtimes in these patterns were not picked by vibes — they were picked by measurement. coding-agent-battles is the public benchmark harness: 12 scenarios, 6 agent scaffolds, 72 runs, with per-run token/cost telemetry, correctness evidence, and an audit pack.

License

MIT — battle-tested by necessity, shared so you can skip the 2am part.