io.github.naruminho/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

pipx install synod-council

Or from source:

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

Usage

Library

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 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

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