Content
# Harness Council
[](LICENSE)
[](package.json)
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](docs/SETUP.md)** | Install, daemon, cmux, Claude MCP, plugin, config, troubleshooting |
| **[docs/USAGE.md](docs/USAGE.md)** | Roles, CLI/MCP, explore→code flow, **2×2 layout**, auto-close |
| **[docs/ORCHESTRATOR.md](docs/ORCHESTRATOR.md)** | Any harness as the top orchestrator — AGENTS.md/GROK.md snippet, routing precedence |
## Requirements
| Tool | Role | Notes |
| --- | --- | --- |
| [Node.js](https://nodejs.org) 22+ | runtime | uses `node:sqlite` |
| [cmux](https://github.com/manaflow-ai/cmux) | visibility | recommended — splits/tabs for workers |
| [Claude Code](https://claude.com/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](docs/ORCHESTRATOR.md)).
## Quick start
```bash
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.
```toml
[display]
layout = "grid"
grid_max = 4
close_on_complete = true
close_on_failed = false
```
## Claude Code
MCP (recommended):
```json
{
"mcpServers": {
"harness-council": {
"command": "council",
"args": ["mcp"]
}
}
}
```
Optional plugin: `plugins/claude-code` (skill + `/spawn` + stop-hook). Details in [docs/SETUP.md](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:
```bash
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
```bash
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:
```bash
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](LICENSE)
