io.github.naruminho/synod-council
Durable symmetric deliberation between two AI agents, with isolated worktrees and peer review.
Open source Open in the app JSON README (API)
About
Durable symmetric deliberation between two AI agents, with isolated worktrees and peer review.
Details
- Kind
- MCP servers
- Topic
- No topic detected
- Publisher
- naruminho
- Origin
- official
- Category
- ferramentas
- Transport
- desconhecido
- Version
- 0.2.0
- Last push
- 2026-08-26T04:19:15Z
- Repository state
- ativo
- Language
- Python
- License
- MIT
- Added
- 2026-08-29 04:00:52
- Updated
- 2026-08-29 04:00:52
- Origin id
io.github.naruminho/synod-council
README
# 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)