# Harness Council

[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
[![Node.js 22+](https://img.shields.io/badge/node-%3E%3D22-brightgreen.svg)](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)