DEV Community

Altavista360
Altavista360

Posted on

Coordinating several AI coding agents on one machine with a 230-line SQLite tool

#ai #agents #opensource #python

When you run several AI coding agents at once on the same machine (several Claude Code sessions, a worker plus an integrator, or a mix of tools), two problems show up quickly:

  1. Messages get lost. One agent finishes something, says so in its own terminal, and nobody else ever sees it.
  2. Two agents edit the same file. Each one is convinced it owns src/add.py, and the second write quietly wins.

We hit both while building our own internal tooling, so we wrote a deliberately small answer to them: agent-collab-kit, one Python file of about 230 lines, standard library and SQLite only, MIT licensed.

Durable messages with explicit acknowledgements

Every message lives in a local SQLite file until the recipient acknowledges it. Here is the demo from the README, run against a throwaway database:

DB=$(mktemp -d)/demo.db
python3 agent_collab.py --db "$DB" init
python3 agent_collab.py --db "$DB" send --sender worker-a --recipient integrator \
  --key demo-result-1 --body 'Addition is ready for review'
python3 agent_collab.py --db "$DB" inbox --recipient integrator
Enter fullscreen mode Exit fullscreen mode 
[{"id": "2fd715fc-...", "idempotency_key": "demo-result-1", "sender": "worker-a",
  "recipient": "integrator", "body": "Addition is ready for review",
  "acknowledged_at": null}]
Enter fullscreen mode Exit fullscreen mode

The idempotency key matters for agents: an agent that retries after a crash and sends the same sender, recipient and body gets the existing message back instead of a duplicate. Reusing the key for different content is an error. ack marks the message as received. It does not prove the work was delivered or tested, and the README says so.

Leases on exact resource names

Before editing, an agent claims the exact resource it is about to touch:

python3 agent_collab.py --db "$DB" claim --resource src/add.py --owner worker-a --ttl 300
# {"resource": "src/add.py", "owner": "worker-a", "generation": "6ca2d25b-...", ...}

python3 agent_collab.py --db "$DB" claim --resource src/add.py --owner worker-b --ttl 300
# resource has an active lease   (exit code 1)
Enter fullscreen mode Exit fullscreen mode

Each claim gets a fresh generation UUID. Renewing or releasing requires the matching owner and generation, and an unexpired lease. That closes a nasty case: an agent that was paused, whose lease expired and was taken over, cannot later renew or release its successor's lease, even under the same owner name. Every mutation runs inside SQLite BEGIN IMMEDIATE, and the test suite includes two real processes racing for one claim.

What it does not do

This is the part we care most about stating clearly:

  • Leases are cooperative. An agent that ignores them is not stopped. There is no filesystem fencing.
  • Expiry does not stop a worker. A paused worker may resume after a takeover, so workers must check ownership and stop when they lose it.
  • No identities. Names and UUIDs are cooperative tokens, not authentication. Anyone with access to the database file can impersonate a participant.
  • One trusted machine, local disk. Network filesystems and separate hosts are unsupported.
  • No orchestration. It does not launch agents, call a model provider or run Git.

In practice we pair it with one rule: a single integrator reviews and merges, and a shared resource such as __commit__ serializes integration. The repository includes a fictitious COLLAB.md board and a short method for letting project agents propose improvements under supervision.

Four other small tools from the same place

We publish the reusable pieces of our stack under kanibal-studio, each with its own tests and the same habit of saying what it does not do:

  • least-cost-capable: a portable Agent Skill that picks the lowest declared cost rank among the models in your catalogue that actually have the capabilities a task needs. Unknown evidence stays "unresolved".
  • cost-per-kept-meeting: ranks B2B lead sources by cost per kept qualified meeting instead of cost per lead.
  • rgpd-offshore-check: a GDPR gap report for outsourcing customer service outside the EU. Not legal advice.
  • demarchage-consent: French cold-call consent validity under decree 2026-662, on PyPI.

Issues and criticism are welcome, especially about the lease semantics.

Top comments (0)