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.

![CI](https://github.com/adamorad/airlock/actions/workflows/ci.yml/badge.svg)
![License](https://img.shields.io/badge/license-MIT-blue)
![Platform](https://img.shields.io/badge/platform-macOS%20%7C%20Linux-lightgrey)
![MCP](https://img.shields.io/badge/MCP-compatible-7C3AED)

![Airlock demo](docs/assets/demo.gif)

*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.*

<!-- Static fallback if the GIF doesn't render: -->

```
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`

```bash
go install github.com/adamorad/airlock/v2@latest   # builds the `airlock` binary
airlock install-service                          # launchd (macOS) / systemd user unit (Linux)
```

### (b) Homebrew

```bash
brew install adamorad/tap/airlock
airlock install-service
```

### (c) Build from source

```bash
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

```bash
airlock status
# Airlock — 127.0.0.1:27183
#
# LOCKS (0)
#   (none)
# ...
```

### Configure your agent

**Claude Code** — one command:

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

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

```json
{
  "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 <token>` header:

```json
{
  "mcpServers": {
    "airlock": {
      "type": "http",
      "url": "http://127.0.0.1:27183",
      "headers": { "Authorization": "Bearer <paste contents of ~/.airlock/token>" }
    }
  }
}
```

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

| Tool | Args | Returns |
|------|------|---------|
| `lock_resource` | `name`, `agent_id`, `ttl_seconds?`=900, `wait_seconds?`=0 (cap 50), `wake_token?` | `{locked:true, lock_token, expires_in_seconds}` — or, if contended, `{locked:false, held_by, expires_in_seconds}` plus `{wake_token, queue_position, retry_with}` when you were queued |
| `unlock_resource` | `name`, `lock_token` (preferred) or `agent_id` | `{released: bool}` |
| `renew_lock` | `name`, `lock_token` (preferred) or `agent_id`, `ttl_seconds?`=900 | `{renewed:true, expires_in_seconds}` or `{renewed:false, error}` |
| `list_locks` | — | `[{name, agent_id, expires_in_seconds}]` |
| `lock_resources` | `names:[string]`, `agent_id`, `ttl_seconds?`=900 | all-or-nothing: `{locked:true, tokens:{name:token}}` or `{locked:false, held_by}` |

`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

| Tool | Args | Returns |
|------|------|---------|
| `set_note` | `key`, `value`, `author?`, `ttl_seconds?` | `{saved:true}` |
| `get_note` | `key` | `{key, value, author?, expires_in_seconds?}` or `{found:false}` |
| `list_notes` | — | `[{key, value, author?, expires_in_seconds?}]` |
| `delete_note` *(v2)* | `key` | `{deleted: bool}` |
| `set_note_if` *(v2)* | `key`, `expected_value`, `new_value`, `author?`, `ttl_seconds?` | `{swapped: bool}` (true only if the stored value equaled `expected_value`; an absent/expired note counts as `""`) |
| `increment_counter` *(v2)* | `name`, `by?`=1 | `{value}` (post-increment; collision-free under concurrency) |

### Presence

| Tool | Args | Returns |
|------|------|---------|
| `register_agent` *(v2)* | `agent_id`, `ttl_seconds?`=60 | `{registered:true, expires_in_seconds}` — re-call to stay alive; when it lapses the agent's locks auto-release |
| `unregister_agent` *(v2)* | `agent_id` | `{unregistered:true}` — also releases held locks |
| `list_agents` *(v2)* | — | `[{agent_id, expires_in_seconds}]` |

### Events

| Tool | Args | Returns |
|------|------|---------|
| `signal_event` *(v2)* | `name` | `{generation}` (the new, bumped generation; wakes all waiters) |
| `wait_for_event` *(v2)* | `name`, `last_seen_generation?`=0, `wait_seconds?`=25 (cap 50) | `{generation, fired}` — blocks until the generation advances past `last_seen_generation`, or the window expires (`fired:false`) |
| `clear_event` *(v2)* | `name` | `{cleared:true}` |

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

### Tasks

| Tool | Args | Returns |
|------|------|---------|
| `push_task` *(v2)* | `queue`, `payload`, `author?`, `priority?`=0 | `{id}` (higher priority / older claimed first) |
| `claim_next_task` *(v2)* | `queue`, `agent_id`, `lease_seconds?`=120 | `{claimed:true, id, payload, lease_token}` or `{claimed:false}` |
| `complete_task` *(v2)* | `id`, `lease_token` | `{completed: bool}` |
| `fail_task` *(v2)* | `id`, `lease_token`, `requeue?`=true | `{failed: bool}` (requeue=true returns it to pending; false gives up) |
| `list_tasks` *(v2)* | `queue` | `[{id, queue, payload, priority, state, author?, lease_agent?, lease_expires_in_seconds?}]` |

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.

```bash
# 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.co