claude-consensus

Purpose

claw-consensus solves the coordination problems commonly encountered when running AI agents (such as Claude Code) on multiple computers: state drift between machines, humans being forced to act as copy-paste messengers between terminals, "sent" being misread as "done", and synchronization links silently failing. It provides a multi-machine coordination layer that enables agents on different machines to negotiate decisions, commit results, verify each other, and wake humans only when money or irreversible operations are involved.

Main Capabilities

• Consensus protocol: propose → counter → accept → commit, with an append-only event log, round limits, timeouts, a fixed leader to break ties, and split-brain detection.
• Dual-track message bus: every inter-machine message is sent over two tracks simultaneously—a file mailbox on a sync folder, and a group chat that both machines and humans can read. A single entry point, bus_send.py, makes single-track sends impossible.
• Single-writer files: each sender only appends to its own file, and each recorder only writes its own shard, avoiding whole-file sync conflicts.
• ACK discipline: direct commands require an explicit ACK and result report; silence beyond the SLA triggers follow-up and escalation.
• Independent verification: the machine that applies a change cannot be the sole verifier; "globally complete" requires an independent check by a second machine, with protection against rubber-stamping.
• Leader/follower specification: exactly one machine (the always-on hub) commits the shared specification, while followers receive it read-only and propose changes via the bus.
• Three-layer self-healing synchronization: a watchdog alerts on state changes, bounded automatic nudging, and automatic failover to the chat track when a peer node is unreachable.
• Pure standard-library Python: no packages, no servers, no databases; if you can run python, you can run the whole system.

Usage

Quick start (about 15 minutes, 2 machines):

1. Choose a folder that syncs between machines (Syncthing, Dropbox, or a git repository), and set MACHINE_BUS_DIR to a subfolder within it on both machines.
2. Copy reference/ to both machines, and create <bus>/machines.json according to the example in docs/BUS.md.
3. Send the first message: python bus_send.py OTHER-MACHINE "hello from HUB-1"; on another machine: python machine_bus.py read.
4. Connect the second rail: set BUS_RAIL2_CMD to a command that posts one text parameter to a group chat (Telegram group, Slack channel, Discord webhook).
5. Create <bus>/_decisions/consensus.json and fill in the leader machine name. Run the first negotiation: python consensus.py propose "test: adopt rule X" --tier 0, have another machine respond with python consensus.py respond <id> accept, then commit and execute two verification calls.
6. On the always-on machine, schedule sync_monitor.py about every 20 minutes, and run consensus.py tick at the same time.

The project also provides demo/evaluation commands that can simulate two machines locally and drive five scenarios (normal path, Tier-2 human gate, dangerous action mislabeled triggering a tripwire, capturing split-brain during partition recovery, corrupted ledger row not swallowing subsequent events), with exit code 0 meaning all terminal states are correct.

Applicable scenarios

• Running AI agents on multiple machines (laptop, desktop, always-on hub, home computer) and needing to coordinate decisions.
• Teams or individuals who want to reduce manual copy-pasting between terminals and avoid state drift.
• Needing agents to autonomously reach consensus on routine decisions and notify humans only for risky or irreversible operations.

Limitations

• All measurement data comes from the author's own six machines and is a reference implementation rather than independent results.
• Interesting failure scenarios require multiple machines to reproduce; a single-machine demo cannot cover all cases.
• The project is still evolving, and some failure modes do not yet have corresponding safeguards.
• The arXiv submission (cs.MA) is still awaiting endorsement, and the repository copy is the current canonical preprint.
• Specific charges, prices, platform support, etc. are not provided in the materials.