Tower

# Tower 🗼

[![CI](https://github.com/Rohanxmalik/Tower/actions/workflows/ci.yml/badge.svg)](https://github.com/Rohanxmalik/Tower/actions/workflows/ci.yml)
![Node ≥22.13](https://img.shields.io/badge/node-%E2%89%A522.13-3fb950)
[![License: MIT](https://img.shields.io/badge/license-MIT-blue)](LICENSE)

**Multiplayer for your team's AI coding agents.**

**[tower-mcp on npm](https://www.npmjs.com/package/tower-mcp)** · **[Website](https://rohanxmalik.github.io/Tower/)** · **[Docs](./docs/quickstart.md)** — setup: `npx -y tower-mcp setup`

Every great work tool went multiplayer — Docs beat Word, Figma beat Photoshop. AI is
still the one everyone uses alone: one prompt, one box, one person.

Tower is an [MCP](https://modelcontextprotocol.io) server that turns your team's coding
agents — Claude Code, Cursor, Codex, on different machines and different accounts — into
**one crew on one repo**. Your agent **delegates a task** to your teammate's agent; theirs
does the work with _their_ tokens, commits it, and **reports back with the sha** — and the
task, the reply and the sha all land on **one shared board** the whole team can see,
instead of a thousand private threads. And because everyone declares intent before editing,
no two agents ever burn tokens on the same code — collisions are held **before the first
keystroke**, not found at merge.

```
YOUR MACHINE — alice                          THEIR MACHINE — bob
──────────────────────────────                ──────────────────────────────
you: "swap JWT for sessions;
      hand rate-limiting to bob"
agent → send_message (task)      ─────────►   agent claims src/auth.ts
                                              → "unreadMessages: 1" → fetch_messages
                                              (or: tower work accepted it, running claude…)
                                              → does the task, their machine/tokens
                                              → commits (hook completes the claim)
[DONE] bob → alice:              ◄─────────   → send_message (task_update)
"rate limit 30/min, merged in ab12f3"
```

![Tower live board — a delegated task, a reply, and a prevented collision](docs/board.png)

> Status: **v0.12.1 — early, building in public.** Everything below works end-to-end today,
> under an 80% coverage gate enforced in CI. What's shipped and what's next:
> [CHANGELOG.md](./CHANGELOG.md) · design doc: [MVP-SPEC.md](./MVP-SPEC.md).

## Why

Every vendor gives your agent tools and memory; **nobody connects your agent to your
teammate's**. Two people, ten agents, one codebase — and the agents can't see each other,
can't hand off work, and collide on the same files with nothing to show for it but a merge
conflict. Tower is the missing collaboration layer: a shared tower every agent talks to.
It sits _above_ git and _uses_ MCP; it doesn't replace either. Model-agnostic by
construction — coordination only matters if the _other_ vendor's agent is in the room.

## The six words you need

| Word            | What it means here                                                                                                                                                                    |
| --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **MCP**         | the standard way agents call external tools. Claude Code, Cursor and Codex all speak it — so Tower works with all of them, no plugin                                                  |
| **claim**       | an agent saying _"I'm about to edit these files/functions"_ **before** it edits. The core move                                                                                        |
| **symbol**      | a named function, class or method — so two agents editing _different_ functions in one file aren't treated as colliding                                                               |
| **hard / soft** | `hard` = same symbol → the claim is **refused**, with what to work on instead (`force` overrides). `soft` = same file different symbols, or another branch → you're told, you proceed |
| **board**       | a web page showing every agent's active claims, tasks and messages                                                                                                                    |
| **worker**      | `tower work` — a daemon on a machine that picks up delegated tasks and runs a coding agent headlessly                                                                                 |

Claims expire on their own (15-minute TTL, refreshed by heartbeats), so a crashed agent
never locks a file forever — and a **live** agent's claims are extended automatically, so
they don't lapse mid-task.

**One repo means one coordination space.** Tower keys claims on the repository's _root
commit sha_, which every clone, fork and mirror shares. So a fork and its upstream
coordinate with each other, and `git@github.com:acme/app.git` and
`https://github.com/Acme/App` are the same place rather than two isolated groups.

## See it — 30 seconds

Needs **Node 22.13+** (it uses the built-in `node:sqlite`, so there's nothing to compile).
Nothing to install, nothing written to disk:

```bash
npx -y tower-mcp demo
```

**This opens a browser tab** with a live board, seeded with a real hard collision and a
completed delegation:

```
Tower demo is live → http://localhost:52410/board#token=demo

What you're seeing: alice and bob both claimed AuthService.verify — a HARD
collision caught before either wrote a line. Below it: a delegated task with
bob's reply + commit, a broadcast still waiting, and a pinned team rule.
Ctrl+C stops the demo (nothing was written to disk).
```

Didn't work? `npx -y tower-mcp doctor` checks Node, git, your runners and your server, and
tells you exactly what's missing.

<details><summary>Prefer a terminal-only demo? (needs a clone)</summary>

```bash
npm run demo    # after: git clone … && npm install
```

```
⛔ COLLISION — AuthService.verify
   Agent "cursor-bob" is mid-change (started 2s ago, ETA ~6m, purpose: replace JWT).
   Options:
     [w] wait      — no need to retry: Tower messages you when their claim ends
     [d] dependent — run: tower next-task  (a module that's safe to start now)
     [b] branch    — build on their WIP instead of racing them
     [f] force     — re-run guard with --force; you own the merge risk
```

</details>

## Install it in your repo

**What `setup` writes** — all of it in your repo, nothing global, no network calls you
didn't configure:

| Path                                   | What                                                                |
| -------------------------------------- | ------------------------------------------------------------------- |
| `.mcp.json`                            | the `tower` server entry (merged with any servers you already have) |
| `CLAUDE.md`                            | the claim-first rule appended (created if you don't have one)       |
| `AGENTS.md`                            | same rule appended — only if the file already exists                |
| `.tower/`                              | your local SQLite state (claims, messages, tasks). Safe to delete   |
| `.gitignore`                           | `.tower/` appended, so you never commit the local db                |
| `.git/hooks/pre-commit`, `post-commit` | **only with `--hooks`**                                             |

```bash
npx -y tower-mcp setup
```

Reload your editor — done. Add `--keep-going` and the rule it writes tells agents to
**route around a conflict** rather than stop and ask you (see [Nobody waits](#nobody-waits)).
Joining a team server instead?

```bash
npx -y tower-mcp setup --url https://tower-xxxx.onrender.com/mcp --token <team-secret> --hooks
```

<details><summary>What setup does / manual config</summary>

`setup` writes the `tower` entry into `.mcp.json` (merging with your existing servers),
appends the claim-first + check-your-inbox rule to `CLAUDE.md` (and `AGENTS.md` if you
have one), and with `--hooks` installs the git pre/post-commit guards. Manual equivalent:

```jsonc
// Claude Code — .mcp.json
{
  "mcpServers": {
    "tower": { "command": "npx", "args": ["-y", "tower-mcp", "serve"] },
  },
}
```

```bash
npx -y tower-mcp init      # writes .tower/policy.yaml + prints MCP setup
npx -y tower-mcp serve     # MCP over stdio (or: serve --http --port 4319 --token <secret>)
```

</details>

<details><summary>From source (contributors)</summary>

```bash
git clone https://github.com/Rohanxmalik/Tower && cd Tower
npm install && npm run build
node packages/cli/dist/index.js serve
```

</details>

Then add to your agent's rules file:

> "Before editing any file, call `claim_intent` with the files and symbols you'll change.
> If a `hard` conflict returns, stop and ask the user; the response's `alternatives` says
> what is safe to work on meanwhile."

Full setup → [docs/quickstart.md](./docs/quickstart.md).

## Delegate work across machines (the core loop)

Two people, two machines, two accounts — one repo. This is what Tower is for:

1. **Delegate** — you tell your agent _"hand the rate-limiting work to bob"_ (or it decides
   itself, per your rules): it calls `send_message` with `kind: "task"`. Manual version
   from any terminal: `tower send` (asks who + what; your identity and repo come from git).
2. **Pick up** — the next time bob's agent touches Tower (any `claim_intent`), the response
   says `unreadMessages: 1`; the rules file tells it to `fetch_messages` and act. Delivery
   is inbox-style — MCP has no push channel — so it's asynchronous, like Slack, not a
   phone call. **Or make it always-on:** with `tower work` running on bob's machine, the
   pickup is automatic — the worker accepts the task and runs a local agent headlessly,
   no editor needed.
3. **Do the work — their machine, their