Airlock

Airlock

Run five agents on one repo without them stomping on each other.

Named resource locks, atomic shared state, presence, events, and a task queue for AI agents — exposed over a local HTTP MCP server that's always running, so any session, terminal, or CI job can coordinate with any other. Cross-platform Go daemon, SQLite-backed, with real blocking waits — no more poll loops.

*Two agents reach for the same npm-install lock — one wins, the other blocks on a server-side wait and acquires the instant the first releases.*

Agent A                          Agent B

────── ────── lock_resource("npm-install") lock_resource("npm-install", wait_seconds=50) → { locked: true, lock_token } (parked — the daemon holds the connection open) npm install ... unlock_resource(lock_token) → { locked: true, lock_token } ← wakes instantly npm install ...

The problem

Open two Claude Code sessions on the same repo — one adding auth, one adding notifications. Both reach for npm install at the same time. Both pick 003_ as the next migration filename. Neither knows the other exists.

There's no shared state. No handoff. No way for one agent to know what another is doing. Coordination lives in fragile prompt instructions ("please wait until migrations finish") that nothing enforces.

How it works

Airlock is a single Go daemon that runs as a background service — always on, surviving IDE and terminal restarts. It listens on 127.0.0.1:27183 and speaks MCP over HTTP. Any agent that has it configured can:

• acquire locks — and *block* on a contended one (wait_seconds, up to 50s), so the daemon parks the caller and wakes it the instant the lock frees. No agent-authored retry loops.
• share atomic state — increment_counter for collision-free unique numbers, set_note_if for compare-and-swap. Read-modify-write is race-free, not best-effort.
• announce presence — register_agent heartbeats; when an agent dies, its locks release and its waiters wake immediately.
• signal events — generation-counted signal_event / wait_for_event for handoffs without polling.
• queue work — a small task queue with presence-bound leases that auto-requeue on crash.

State lives in SQLite (WAL mode) at ~/.airlock/state.db — transactional, crash-safe, with concurrent readers and a single writer. The store is pure-Go (modernc.org/sqlite, no cgo), which is what makes the Linux build a trivial cross-compile. One binary, no language runtime, no external database.

Install

(a) go install

go install github.com/adamorad/airlock/v2@latest   # builds the `airlock` binary

airlock install-service # launchd (macOS) / systemd user unit (Linux)

(b) Homebrew

brew install adamorad/tap/airlock

airlock install-service

(c) Build from source

git clone https://github.com/adamorad/airlock.git

cd airlock go build -o airlock . sudo install airlock /usr/local/bin/airlock # or anywhere on your PATH airlock install-service

install-service registers an always-on background service (and unloads the old v1 LaunchAgent if present, so the v2 daemon takes port 27183 cleanly).

Verify

airlock status

Airlock — 127.0.0.1:27183

#

LOCKS (0)

(none)

...

Configure your agent

Claude Code — one command:

claude mcp add --transport http airlock http://localhost:27183

Cursor / Windsurf / any MCP client — add this to your MCP config:

{

"mcpServers": { "airlock": { "type": "http", "url": "http://127.0.0.1:27183" } } }

On Linux (and any multi-user host) a bearer token is required — loopback is shared across all users there, so it isn't an authorization boundary on its own. The daemon writes a 0600 token to ~/.airlock/token on first run; send it as an Authorization: Bearer header:

{

"mcpServers": { "airlock": { "type": "http", "url": "http://127.0.0.1:27183", "headers": { "Authorization": "Bearer " } } } }

On macOS the daemon is loopback-only by default and the token is optional. AIRLOCK_TOKEN overrides the file on any OS.

Tools

Airlock exposes 22 tools over MCP. Every tool result is a JSON object (the list_* tools return a JSON array). TTLs are in ttl_seconds; ttl_minutes is accepted as a deprecated alias.

Locks

wait_seconds is the coordination-by-default knob: pass it (up to 50) and lock_resource blocks server-side until the lock frees, instead of returning locked:false immediately. The cap stays under Claude Code's 60s default per-tool-call timeout. The returned `lock_token` is a capability — unlock_resource/renew_lock require it (the agent_id path is kept for v1 compatibility). lock_resources acquires in a documented lock-ordering (lexicographic by name) so two callers can't deadlock.

Notes & State

Presence

Events

Events are generation-counted, not latched: pass back the generation you last saw and a signal that fired between calls is never missed.

Tasks

A claim is a lease: if the claimant doesn't complete_task/fail_task within lease_seconds, the task auto-requeues for another consumer — no work is lost to a crashed worker. The lease_token from claim_next_task is the capability complete_task/fail_task require.

Naming conventions

Use consistent names so agents understand each other:

• Files: file:/abs/path/to/package.json
• Processes: npm-install, db-migrations, tests:unit
• Agent identity: agent:claude-session-abc

Recipes

(a) Serialize edits to one file with a blocking lock

Two subagents both need to edit package.json. They serialize on a single lock — the second one *blocks* (no retry loop) and wakes the instant the first releases.

# Subagent A — block up to 50s to acquire, edit, release.

A=$(curl -s -X POST localhost:27183 -H 'Content-Type: application/json' \ -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"lock_resource","arguments":{"name":"file:/repo/package.json","agent_id":"sub-A","wait_seconds":50}}}' \ | jq -r '.result.content[0].text | fromjson | .lock_token')

...edit the file...

curl -s -X POST localhost:27183 -H 'Content-Type: application/json' \ -d "{\"jsonrpc\":\"2.0\",\"id\":2,\"method\":\"tools/call\",\"params\":{\"name\":\"unlock_resource\",\"arguments\":{\"name\":\"file:/repo/package.json\",\"lock_token\":\"$A\"}}}" \ | jq -c '.result.content[0].text | fromjson' # → {"released":true}

Subagent B — the same call with wait_seconds=50 parks until A releases, then

returns {locked:true, lock_token} the moment the lock frees. No polling.

(b) Unique migration filenames — race-free

The classic v1 hazard: two agents get_note the counter at the same instant, both read 003, both write 004. In v2 there is no read-modify-write to lose — increment_counter is atomic, so 100 concurrent callers get 100 distinct numbers.

curl -s -X POST localhost:27183 -H 'Content-Type: application/json' \

-d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"increment_counter","arguments":{"name":"migration-seq"}}}' \ | jq -c '.result.content[0].text | fromjson' # → {"value":4}

Use the returned value: create 0004_*.sql. The next caller gets 5, never a collision.

(c) Producer/consumer handoff via the task queue

A planner agent pushes work; one or more worker agents claim it. A lease means a crashed worker's task auto-requeues instead of vanishing.

# Producer — enqueue a unit of work.

curl -s -X POST localhost:27183 -H 'Content-Type: application/json' \ -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"push_task","arguments":{"queue":"build","payload":"compile module X","author":"planner"}}}' \ | jq -c '.result.content[0].text | fromjson' # → {"id":1}

Consumer — claim the next task, do the work, complete it with the lease token.

CLAIM=$(curl -s -X POST localhost:27183 -H 'Content-Type: application/json' \ -d '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"claim_next_task","arguments":{"queue":"build","agent_id":"worker-1"}}}' \ | jq -c '.result.content[0].text | fromjson') # → {"claimed":true,"id":1,"payload":"compile module X","lease_token":"..."} ID=$(echo "$CLAIM" | jq -r .id); TOK=$(echo "$CLAIM" | jq -r .lease_token)

...do the work...

curl -s -X POST localhost:27183 -H 'Content-Type: applicatio