Harness Council

Local multi-harness orchestration for Claude Code, Grok CLI, and AGY CLI — spawn AI coding agents from different vendors as visible terminal workers, pass context between them, and watch them work in a 2×2 grid.

Council owns jobs + shared context. Harnesses own intelligence. cmux owns visibility.

You + Claude (plan)  ──spawn──►  AGY (explore) / Grok (code)
        ▲                              │
        └──────── result + notify ─────┘
                 (visible splits in cmux)

Guides

Doc	Contents
docs/SETUP.md	Install, daemon, cmux, Claude MCP, plugin, config, troubleshooting
docs/USAGE.md	Roles, CLI/MCP, explore→code flow, 2×2 layout, auto-close
docs/ORCHESTRATOR.md	Any harness as the top orchestrator — AGENTS.md/GROK.md snippet, routing precedence

Requirements

Tool	Role	Notes
Node.js 22+	runtime	uses node:sqlite
cmux	visibility	recommended — splits/tabs for workers
Claude Code	orchestrator / worker	optional
Grok CLI	worker	optional, grok login
AGY CLI	worker	optional

Only the harnesses you actually route to need to be installed — any one of them can be the top orchestrator (docs/ORCHESTRATOR.md).

Quick start

git clone https://github.com/dorukanc/harness-council.git
cd harness-council
npm install && npm run build
npm link                       # or: export PATH="$PWD/bin:$PATH"

council setup
council daemon start

council spawn --role explore "Map the auth system"
council spawn --role code --effort high "Implement rate limiting"
council list
council result <job_id>

What you see in cmux

Default layout is a 2×2 grid of splits, then tabs if more workers start:

1. First worker → split right
2. Next → split down
3. Up to 4 worker panes (2×2)
4. More → tabs on worker panes

When a job completes successfully, its surface auto-closes so space frees for the next worker. Failed jobs stay open for inspection.

[display]
layout = "grid"
grid_max = 4
close_on_complete = true
close_on_failed = false

Claude Code

MCP (recommended):

{
  "mcpServers": {
    "harness-council": {
      "command": "council",
      "args": ["mcp"]
    }
  }
}

Optional plugin: plugins/claude-code (skill + /spawn + stop-hook). Details in docs/SETUP.md.

Register the MCP server once at user scope and every project works with no per-project setup — no CLAUDE.md line required. The council-runtime skill loads itself when you ask for delegation.

Per-project overrides (optional)

Only when a repo should route differently from your defaults:

council init            # writes .harness-council.toml + a CLAUDE.md block
council init --file AGENTS.md --no-toml

Both writes are idempotent — re-running updates the managed block between <!-- harness-council:start --> / <!-- harness-council:end --> and leaves the rest of your file alone. The generated TOML is fully commented: it documents what the project resolves to today, and stays inherited from ~/.harness-council/config.toml until you uncomment a key.

Default roles

Role	Harness	Purpose
plan	claude	Planning
code	grok	Implementation
explore	agy	Cheap scout / research
review	grok (read-only)	Second pass

Configure in ~/.harness-council/config.toml or project .harness-council.toml.

Architecture

council CLI / MCP  →  local daemon  →  SQLite jobs + context store
                                   →  adapters (claude | grok | agy)
                                   →  cmux grid layout + auto-close

Development

npm test
npm run typecheck
npm run build
npm run council -- setup

How the daemon talks to cmux

cmux's default socket auth (cmuxOnly) verifies process ancestry, so a detached daemon can never open splits. When started from inside cmux, the daemon therefore runs in its own council · daemon tab; closing that tab stops it. Outside cmux everything still works headlessly.

Status

v0.1 — daemon (cmux-tab hosted), CLI, adapters, grid layout, auto-close, MCP, Claude plugin (local marketplace install), orchestrator-agnostic docs.

Contributing

Issues and PRs welcome. Before submitting:

npm run typecheck && npm test

Adding a new harness is intentionally small: implement the HarnessAdapter interface in src/adapters/ (binary resolution, readiness, command building, result parsing) and register it in src/adapters/index.ts.

License

MIT