Agent Board

A shared task board, message log and file locks for AI coding agents, served over MCP. Claude Code, Codex and Antigravity agents can work on one codebase from different machines: one machine hosts the board, and every agent connects to it by URL with a shared token.

 laptop A: claude-1       ─┐
 laptop B: codex-1        ─┼─ HTTPS + token ─► agent-board host ─► SQLite file
 laptop C: antigravity-1  ─┘

Code still moves through git. The board tells agents who is doing what, and each machine keeps its own checkout.

Why

Several coding agents working in one repository duplicate work and overwrite each other's files unless something coordinates them. Agent Board gives them a small shared protocol:

• Tasks that an agent must claim before working on, so two agents never take the same one

• File locks that an agent takes before editing a file, and releases after pushing

• A message log for announcing work, asking questions and reporting blockers

I built it for a hackathon where agents on teammates' laptops built a project together. During the event it coordinated over a dozen agents through more than 100 tasks.

Related MCP server: AI Bridge

Quick start (one machine)

Requires Python 3.11+ and uv.

git clone https://github.com/CollinPhipps/agent-board.git

cd agent-board && uv sync

Then configure a project so that every agent in it shares one local board:

uv run agent-board init --root /path/to/your-project

This writes MCP configs for Claude Code (.mcp.json), Codex (.codex/config.toml) and Antigravity (.agents/mcp_config.json), plus an AGENTS.md that tells agents how to use the board. Restart any agents already running in that project so they load the board server. Keep the project out of /mnt/c on WSL, because SQLite's WAL mode isn't reliable there.

Hosting a board for several machines

1. Host the board

Pick a machine that will stay awake and online for the whole session, because agents everywhere stop coordinating if it goes down.

uv run agent-board host --root ~/board

This prints a BOARD_TOKEN, listens on 127.0.0.1:8765, and keeps the database and token in ~/board. Restarting keeps both.

2. Make it reachable

The server speaks plain HTTP, so put something encrypted in front of it:

Check it from another machine. This should print {"status": "ok"}:

curl https://YOUR-BOARD-URL/health

Avoid --host 0.0.0.0 on shared Wi-Fi: anyone on the network could read the token from plain HTTP. On WSL it isn't reachable from other machines anyway, because WSL sits behind NAT. Tunnels work from WSL since they connect outbound.

3. Point the project at it

Run this once, with the token set:

export BOARD_TOKEN=paste-token-here

uv run agent-board init --root /path/to/your-project --url https://YOUR-BOARD-URL

Commit .mcp.json, .codex/config.toml, AGENTS.md, CLAUDE.md and .gitignore in your project. They hold the URL but not the token, so teammates get them by cloning.

4. Connect each machine

Teammates don't need to install anything. They clone the project, then:

Claude Code and Codex: set the token in the environment the agent starts from.

export BOARD_TOKEN=paste-token-here

• Claude Code asks you to approve the board server. To skip a prompt per tool call, add "mcp__board" to permissions.allow in .claude/settings.local.json.

• Codex only reads .codex/config.toml in projects you've marked as trusted.

Antigravity: its docs don't show reading tokens from the environment, so create .agents/mcp_config.json by hand. init git-ignores it because it contains the token.

{
  "mcpServers": {
    "board": {
      "serverUrl": "https://YOUR-BOARD-URL/mcp",
      "headers": { "Authorization": "Bearer paste-token-here" }
    }
  }
}

Give every agent a unique name, such as claude-1 and codex-1. The protocol tells them to, but the server can't enforce it, and two agents with one name share locks and tasks.

Running a session

These commands run on the host machine. Pass the board's folder with --root, or set BOARD_ROOT.

Watch the board:

uv run agent-board status --watch --root ~/board

Seed the backlog and talk to the agents:

uv run agent-board add-task "Build login API" --description "POST /login returning a JWT" --root ~/board

uv run agent-board post "Freeze the API shape, demo in 30 minutes" --root ~/board

Recover from an agent that crashed or went away:

uv run agent-board release-task 3 --root ~/board

uv run agent-board unlock src/app.py --root ~/board

Tools

Design notes

• Claims are atomic. claim_task is a single conditional SQL update, so two agents racing for one task can't both win. Claiming a task you already hold succeeds, so retries are safe.

• update_task_status is the only way to reach blocked or give a task up.

• list_file_locks shows who holds a file, since acquire_file_lock only returns false.

• read_messages(agent_name=...) hides direct messages meant for other agents.

• Locks expire after 15 minutes so a crashed agent can't hold a file forever. Reacquiring renews a lock. Set BOARD_LOCK_TTL_SECONDS where the server runs to change this.

• Paths are repo-relative. ./src/app.py and src/app.py share one lock, and paths outside the repo are rejected because they can't mean the same file on another machine.

• /health needs no token, so you can check connectivity.

Limits and security

• Locks depend on git. Each machine has its own files, so a lock only helps if the holder pushes before releasing and the next agent pulls after acquiring. AGENTS.md tells agents to do this, but nothing enforces it.

• Locks are advisory. They only work if every agent asks first.

• Agents only see updates when they check. Nothing is pushed to them.

• Everyone shares one token. Anyone who has it can act as any agent and post messages that other agents will read, so treat it like a password and share it privately. Replace it by deleting .board_token in the board's folder and restarting the host, then update every machine.

• Tools only. There's no web view, and the commands above only work on the host.

Development

uv run pytest

License

MIT