claude-consensus
claw-consensus is a multi-machine coordination layer for AI agents, providing a dual-rail bus, consensus protocol, and self-healing sync to prevent drift and silent failures. It solves the problem of running agents on multiple computers without human copy-paste or missed handoffs. It is for developers and solo founders running AI agents on more than one machine.
✨ Key features
- Dual-rail bus: file mailbox plus group chat, one entry point
- Consensus protocol: propose, counter, accept, commit with guards
- ACK discipline: delivered is not done, with chase and escalation
- Single-writer files to avoid sync conflicts
- Independent verification with rubber-stamp guard
- Self-healing sync with watchdog and auto-failover
🎯 Use cases
- Coordinate AI agents across laptop and desktop
- Automate routine decisions between machines with consensus
- Ensure changes are verified by a second machine
- Monitor and self-heal sync links between machines
- Run a multi-machine agent fleet with human oversight only for risky actions
📦 Installation
🧰 Requirements: Python 3 with standard library only; no packages, server, or API keys needed.
# Clone the repository
git clone https://github.com/tonydzi/claw-consensus.git
cd claw-consensus
# Copy reference/ to each machine
# Set MACHINE_BUS_DIR to a synced folder subdirectory
# Create machines.json from docs/BUS.md example
🚀 Usage
python bus_send.py OTHER-MACHINE "hello from HUB-1"python machine_bus.py readpython consensus.py propose "test: adopt rule X" --tier 0python demo/demo.py⚠️ Good to know
The reference implementation is from a single founder's fleet of six machines; independent results are not yet available, and reproduction requires more than one box for interesting failures.
❓ FAQ
What are the runtime dependencies?
The reference implementation is stdlib-only Python; no packages, server, or database are required.
How does the consensus engine avoid LLM costs?
The consensus engine makes 0 LLM calls and spends 0 tokens; it is deterministic file I/O. LLM work is in the agent layer above.
How does the system handle sync failures?
It has three self-heal layers: a watchdog that alerts on state change, a bounded auto-nudge to restart the peer's daemon, and auto-failover to the chat rail.
Can I run the demo offline?
Yes, python demo/demo.py runs offline with no network, packages, or API keys, and self-checks all outcomes.
📊 Repository
🤖 Overview, features, install steps and FAQ were generated from the project's README on Sep 4, 2026. Always check the original source before running commands.