synod-council

# Synod

**Durable, symmetric deliberation between two AI agents** — with isolated git worktrees,
peer review, automated validation, and an explicit approval workflow.

Synod started life as the "council" inside a personal AI infrastructure where two
autonomous agents (an orchestrator and an executor) needed to make *real* decisions and
*real* code changes together — without one of them silently becoming the other's rubber
stamp.

## Why

Most multi-agent frameworks are orchestration theater: one agent calls another as a tool
and calls the output "collaboration". Synod is built around a different premise — two
agents that are **peers by construction**:

- **Symmetric protocol** — either agent can initiate; the protocol has no privileged side.
- **Identity contract** — every prompt re-establishes who the agent is, so a weak or
  distracted model can't drift into answering *as* its peer.
- **Bias-resistant synthesis** — the synthesizer for each problem is chosen by hashing
  the problem text, not by who spoke first.
- **Durable state** — every session lives in SQLite with explicit stages (`plan`,
  `review`, `synthesize`, `ratify`, ...). A crashed run leaves an inspectable trail, not
  a mystery.
- **Code changes land through worktrees** — each session gets its own git worktree and
  branch. Agents never push to `main`; a human-facing approval step stands between
  "looks done" and "published".
- **Validation with remediation** — checks run after implementation, failures go back to
  the implementing agent with bounded retries before a human ever sees it.

## Install

```bash
pipx install synod-council
```

Or from source:

```bash
git clone https://github.com/naruminho/synod-council
cd synod && pip install .
```

## Usage

### Library

```python
from synod.deliberation import Deliberator, Store, HTTPAdapter

adapters = {
    "Alice": HTTPAdapter("Alice", "http://127.0.0.1:9001/ask"),
    "Bob":   HTTPAdapter("Bob",   "http://127.0.0.1:9002/ask"),
}
synod = Deliberator(adapters, Store("council.db"))
result = synod.run("Should we use SQLite or Postgres for this workload?", initiator="Alice")
print(result.decision, result.confidence, result.status)  # consensus | reconciled
```

### MCP server

Synod ships an [MCP](https://modelcontextprotocol.io) server so any MCP-capable client
(Claude Desktop, Claude Code, Cursor, ...) can start a deliberation:

```
synod-mcp   # stdio transport
```

Add it to your client config and ask your agents to *deliberate* instead of guessing.

### HTTP server

```bash
synod-server --port 8790
curl -X POST http://127.0.0.1:8790/run -d '{"problem": "...", "initiator": "Alice"}'
```

## How a deliberation flows

```
plan (parallel) → cross-review (parallel) → synthesis → [ratification → reconciliation?]
```

If reviewers raise unresolved blockers, or confidence lands below 0.7, the candidate
decision goes to ratification by the non-synthesizing peer; a rejection forces explicit
reconciliation instead of silent consensus.

## Status

Extracted and battle-tested from a production personal infrastructure where it has been
deciding architecture and shipping code since 2026. The two-agent design is intentional;
N-participant support is on the roadmap.

## License

[MIT](LICENSE)