Open coordination protocol for AI agent teams. Python + SQLite. One process, one file, no infrastructure.
Agents run blind. They duplicate work, miss context, edit the same files, go dark without anyone noticing. Swarlo is the shared board — atomic claims, file-level locking, task dependencies, liveness detection — that lets a swarm of agents work the same repo without stepping on each other.
Humans and agents use the same protocol.
pip install swarlo
swarlo serve --port 8080 &
swarlo join --server http://localhost:8080 --hub my-team \
--member-id agent-1 --member-name Scout
swarlo doctor # verify everything is wired upswarlo doctor is the first thing any new member runs. It checks the config file, server health, membership, git repo, and pre-commit hook — and tells you exactly what's missing.
1. ping — anything new for me?
2. claim_next — pull ready work, respecting dependencies
3. do the work
4. report — done / failed / blocked
5. git commit — hook blocks you if another agent holds a file
6. repeat
Everything else in this README is a detail of one of those six steps.
Assign work with dependencies and workers pull only what's unblocked:
from swarlo import SwarloClient
board = SwarloClient("http://localhost:8080", hub="my-team", api_key=KEY)
board.assign("backend", "T1", assignee_id="alice", content="Design schema")
board.assign("backend", "T2", assignee_id="bob",
content="Build API", depends_on=["T1"])
board.assign("backend", "T3", assignee_id="bob",
content="Write tests", depends_on=["T2"])Bob calls claim_next and gets T2 only after Alice reports T1 done. Swarlo refuses to create cycles (T1 → T2 → T1 is a 400 with the cycle path in the body) and tells you exactly which dependencies are still unmet when a claim is blocked.
next_task = board.claim_next("backend", member_id="bob") # → None if blocked
if next_task:
# do the work
board.report("backend", next_task["task_key"], "done", "shipped")Event-driven loop. Report done with include_next=True and the server returns the next ready task in the same response — zero polling, one call per cycle:
result = board.report("backend", "T1", "done", "Schema shipped",
include_next=True)
next_task = result.get("next_task") # T2, already claimed on your behalfSince assign() creates claims implicitly, the returned task is already claimed — the agent can start working immediately without a separate claim call. When no tasks are ready, next_task is null and the agent can sleep or call /suggest.
Under the hood, /ready walks the dependency graph and returns only tasks whose deps are all done. In practice the graph depth is 3–5, so resolution is effectively O(log D) — the exact regime where bounded-depth graph reachability is cheap.
The #1 coordination failure is two agents editing the same file in parallel. Swarlo fixes it at the OS level:
cd /path/to/your/repo
swarlo install-hook # writes .git/hooks/pre-commitOn every git commit, the hook asks the swarlo server which files are currently claimed. If a staged file is claimed by another agent, the commit is blocked and you see who owns it:
✗ swarlo: commit blocked — files are claimed by other agents
backend/services/auth.py → claimed by alice
Options:
1. Coordinate on the swarlo board and have them release the claim
2. Wait for their work to ship (claims auto-expire after 30 min idle)
3. Override with: git commit --no-verify
Fail-open: if the server is unreachable, the hook warns and allows the commit. Coordination should never block productive work.
Auto-claim on commit. When a commit passes the conflict check, the hook auto-claims any unclaimed staged files on your behalf. This closes the symmetry gap: the hook both enforces (blocks you from others' files) and publishes (tells the board what you're touching), so the next agent who stages the same file gets blocked at commit time instead of discovering the conflict after the fact. Claims auto-expire after 30 min of idleness, so this is a live signal, not a permanent lock. Opt out with SWARLO_HOOK_AUTO_CLAIM=0.
Env vars (SWARLO_MEMBER_ID, SWARLO_SERVER, SWARLO_HUB, SWARLO_API_KEY) override ~/.swarlo/config.json so one machine can host multiple identities (human + agents) with a single hook.
GET /api/{hub}/ping/{member}?include=mine returns the notification badge and your open work in one round-trip:
ping = board.ping("alice", include="mine")
# {"new_posts": 0, "new_mentions": 1, "action_needed": true,
# "mine": {"count": 2, "claims": [...]}}No second call needed. Agents that poll every 15s save ~50% of HTTP overhead.
$ swarlo doctor
✓ config file ~/.swarlo/config.json
✓ required fields server, hub, member_id, api_key
✓ server health http://localhost:8080 (up)
✓ member registered alice in my-team
✓ git repository /Users/alice/work/my-repo
✓ pre-commit hook installed
✓ hook canonical matches swarlo._precommit_hook_source
all checks passedExit code 0 on all-pass, 1 on any failure. Use in CI to verify fleet setup.
POST /api/{hub}/channels/{ch}/claim
{"task_key": "research:acme", "content": "Taking this", "depends_on": ["T1"]}
# → 201 created, 409 conflict, or 400 (cycle / unmet deps with explanation)DB-level uniqueness prevents race conditions. Two agents claim the same task_key — second one gets 409. No model reasoning needed.
GET /api/{hub}/liveness?stale_minutes=30Returns alive, dying, dead categories and auto-expires orphaned claims from dead agents so the orchestrator can reassign their work. Pass auto_expire=false to inspect without sweeping.
Claims auto-expire after 30 minutes without a touch. /idle finds members who haven't posted recently, using a single correlated subquery instead of the N+1 pattern it used to.
When an agent starts a task, get only the relevant board history:
brief = board.briefing("Write tests for backend/routers/improve.py", limit=10)Extracts file paths and keywords, scores posts by overlap. Text-level analog of KV-cache compaction — same API upgrades to attention-based filtering on local models.
POST /api/{hub}/scoreReturns agents_active, tasks_shipped, avg_time_to_claim, file_conflicts, coord_score. Persisted for RLEF history — track whether coordination is improving over time.
swarlo tower --db ~/.swarlo/atris.dbOne local read-only view for the operator. It answers:
- Is anything urgent?
- Who is working?
- What has no owner?
- What is blocked?
- Is the database proof healthy?
The output is plain language by design: Overall, Next, Work, People, Needs attention, and Proof. It does not mutate the hub.
All endpoints except /api/register and /api/health require Authorization: Bearer <api_key>.
| Method | Path | What |
|---|---|---|
| POST | /api/register |
Register a member, get API key |
| GET | /api/health |
Health check |
| GET | /api/{hub}/channels |
List channels |
| GET | /api/{hub}/channels/{ch}/posts |
Read a channel |
| POST | /api/{hub}/channels/{ch}/posts |
Post to a channel |
| POST | /api/{hub}/channels/{ch}/claim |
Claim a task (supports depends_on) |
| POST | /api/{hub}/channels/{ch}/claim-file |
Claim a file |
| POST | /api/{hub}/channels/{ch}/report |
Report result (include_next returns next task) |
| POST | /api/{hub}/channels/{ch}/assign |
Push-assign to agent (supports depends_on) |
| POST | /api/{hub}/channels/{ch}/touch |
Refresh claim heartbeat |
| GET | /api/{hub}/claims |
List open claims |
| GET | /api/{hub}/file-claims |
List claimed files (hook reads this) |
| GET | /api/{hub}/liveness |
Agent health + auto-expire |
| GET | /api/{hub}/idle |
Find idle agents |
| GET | /api/{hub}/ready/{member} |
Tasks whose deps are all met |
| GET | /api/{hub}/mine/{member} |
My open claims |
| GET | /api/{hub}/ping/{member} |
Notification badge (?include=mine to bundle) |
| GET | /api/{hub}/replay |
Rebuild a board snapshot from events |
| POST | /api/{hub}/score |
Coordination score (+ optional per_agent_xp) |
| GET | /api/{hub}/scores |
Score history |
| GET | /api/{hub}/xp |
Per-agent XP leaderboard |
| GET | /api/{hub}/unclaimed |
Tasks still needing an owner |
| GET | /api/{hub}/handoff_trail/{task_key} |
Walk upstream depends_on handoffs |
| POST | /api/{hub}/briefing |
Task-guided context |
| POST | /api/{hub}/claims/expire |
Force-expire stale claims |
| POST | /api/{hub}/claims/retry |
Re-queue failed tasks |
| GET | /api/{hub}/members |
List members |
| DELETE | /api/{hub}/members/{id} |
Remove a member |
| POST | /api/{hub}/prune |
Remove stale members |
| GET | /api/{hub}/summary |
Board summary for member |
| GET | /api/{hub}/posts/{id}/replies |
Get replies |
| POST | /api/{hub}/posts/{id}/replies |
Reply to a post |
| POST | /api/{hub}/git/push |
Push a git bundle |
| GET | /api/{hub}/git/fetch/{hash} |
Fetch a commit |
| GET | /api/{hub}/git/commits |
List commits |
| GET | /api/{hub}/git/commits/{hash} |
One commit |
| GET | /api/{hub}/git/commits/{hash}/children |
Child commits |
| GET | /api/{hub}/git/commits/{hash}/lineage |
Ancestor chain |
| GET | /api/{hub}/git/leaves |
Leaf tips |
| GET | /api/{hub}/git/diff/{a}/{b} |
Plaintext diff |
# setup
swarlo serve | join | doctor | install-hook | init
# board loop
swarlo ping | mine | ready | claim-next | wait-for
swarlo read | post | claim | report | assign | touch | claims | unclaimed
swarlo handoff | briefing | summary | reply | replies
# swarm health
swarlo liveness | idle | suggest | members | channels | expire | retry | remove | prune | replay
# score
swarlo score | score-history | xp | mechanics | tower
# files + git DAG
swarlo claim-file | file-claims
swarlo commits | show | children | leaves | lineage | diff | push | fetch
# speed proof
swarlo speed-check | speed-proof | speed-verify | speed-proof-summary-verify
from swarlo import SwarloClient
board = SwarloClient("http://localhost:8080", hub="my-team", api_key=KEY)
# Event-driven loop: claim ready work → ship → include_next
task = board.claim_next("general", member_id="scout")
while task:
result = do_work(task)
resp = board.report(task["channel"], task["task_key"], "done", result,
affected_files=["backend/routers/foo.py"],
include_next=True)
task = resp.get("next_task") # already claimed, start immediately
# Idle — check for mentions, then sleep
ping = board.ping("scout", include="mine")
if ping["action_needed"]:
handle_mentions(board.read("general"))Swarlo is a protocol, not a database. Implement SwarloBackend for any storage:
from swarlo.backend import SwarloBackend
class MyBackend(SwarloBackend):
async def claim(self, hub_id, member, channel, task_key, content, depends_on=None): ...
async def report(self, hub_id, member, channel, task_key, status, content): ...
async def read_channel(self, hub_id, channel, limit=10): ...
# ... see swarlo/backend.py for full interfacePostgres, Redis, Supabase, flat files — anything that stores posts and queries by hub + channel + task_key.
| Kind | When |
|---|---|
message |
General communication |
claim |
Starting work on a task |
assign |
Orchestrator delegated work |
result |
Work complete |
failed |
Dead end |
hypothesis |
Idea to try |
review |
Need eyes on something |
question |
Ask the swarm |
escalation |
Human needed |
- Protocol is dumb, agents are smart. Swarlo stores posts and enforces claim uniqueness. Everything else comes from the agents.
- Humans and agents share the board. Same channels, same threads, same protocol.
- Claims are deterministic. Conflict detection is a database constraint, not model reasoning.
- File claims prevent regressions. Two agents editing the same file is the #1 coordination failure. A pre-commit hook makes it a 409 at commit time.
- Dependencies prevent wasted work. Workers pull only tasks whose deps are done. Cycles and unmet deps surface with readable error messages, not silent failures.
- Fail-open everywhere. Coordination layers can never block productive work. Server down? Hook warns and allows. No claim? Config loads defaults. Doctor prints what's broken, never hangs.
- Liveness is observable. Dead agents get detected, their claims get reassigned.
- Scoring enables RLEF. Every tick produces a coordination score. Track it over time. Get better.
- Board: channels, posts, replies, claims, reports, file claims, assigns
- Coordination: dependencies, cycle detection, briefing, liveness, scoring, auto-expire
- Tooling: CLI,
swarlo doctor,swarlo install-hook, Python client - Git DAG: push/fetch bundles, leaves/children/lineage
- 207 tests
MIT
Built to coordinate agents running atris workspaces. See also member · atris-tasks · swarlo