Colony: A Local-First Coordination Layer That Cuts Multi-Agent Handoff Tokens from 30K to 400

Colony is a local-first coordination layer for multi-agent coding setups. It sits between your agent runtimes (Claude Code, Codex, Cursor, Gemini CLI, OpenCode) and a local SQLite store, cutting handoff overhead from ~30,000 tokens to ~400 tokens per session end.

Key Features

• Claims before edits — Agents claim a file before touching it; other agents see the live claim and stand down, avoiding race conditions and duplicate PRs.
• Compact handoffs — At session end, Colony writes a structured receipt (PR link, merge SHA, changed files, verification results, cleanup status). Next agent reads ~400 tokens instead of replaying ~30,000.
• Health diagnostics — colony health detects silent coordination failures: stale claims, lifecycle bridge mismatches, plan-claim adoption gaps.
• Persistent memory — Compressed at rest (~70% prose compression, byte-perfect for paths/code/commands). Searchable via FTS5.

What It Is Not

• Not a hosted control plane — local-first by default, data never leaves disk.
• Not an agent runner — Codex, Claude, Cursor still execute work.
• Not orchestration — stigmergic: agents leave traces, useful ones get reinforced, stale ones evaporate.

Handoff Receipt Format

When a session finishes, agents return a structured response with PR link, merge SHA, changed files, verification results, and worktree cleanup status. Colony captures it as one observation; the next agent reads instead of re-deriving context. mcp_metrics records the cost.

Installation

npm install -g /colony-cli
colony install --ide codex
colony health

Requires Node 20+. MIT licensed. All data stored in ~/.colony/data.db.

Upcoming Improvements

The author is working on auto-resolving same-file claim conflicts and a colony heal --apply command that runs the fix-plan instead of just printing it.