# Bothread

> Local room where AI coding agents collaborate on one codebase via MCP — collisions prevented, human in command.

- **Type:** MCP server
- **Install:** `agentstack add mcp-adamace9-bothread`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [AdamACE9](https://agentstack.voostack.com/s/adamace9)
- **Installs:** 0
- **Category:** [Integrations](https://agentstack.voostack.com/c/integrations)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [AdamACE9](https://github.com/AdamACE9)
- **Source:** https://github.com/AdamACE9/bothread
- **Website:** https://bothread.vercel.app

## Install

```sh
agentstack add mcp-adamace9-bothread
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# 🧵 Bothread

### Run the AI coding agents you already use — together, on one codebase. Local, MCP-native, you in command.

A free, open-source local app. **No API keys, no cloud.**  ·  Not affiliated with the embroidery brand "Brothread".

[](LICENSE)
[](https://www.typescriptlang.org/)
[](https://modelcontextprotocol.io)
[](#contributing)

**[Website](https://bothread.vercel.app) · [Get started](https://bothread.vercel.app/start) · [The skill](skill/) · [npm](https://www.npmjs.com/package/bothread)**

Three agents (Claude Code · Antigravity · OpenCode) splitting up the work and building a playable game in one shared room — live.

---

## What is Bothread?

**Bothread in one sentence:** Bothread is a free, open-source, local coordination hub that lets
multiple AI coding agents — Claude Code, Cursor, Antigravity, Gemini CLI, Codex, OpenCode, or any
other [MCP](https://modelcontextprotocol.io)-compatible agent — work together on the same codebase
in one shared room, claiming files so they never overwrite each other, while a human watches every
move and stays in command. No API keys, no cloud, no cost.

Run more than one AI coding agent on the same project without it and it gets painful fast: they
can't talk to each other, they open the same file and silently overwrite each other's work, and
whatever coordination exists happens invisibly across separate terminals. Bothread runs an MCP
server so any MCP-compatible agent can **join one room**, **collaborate on the same codebase**, and
**stay out of each other's way** — while a human watches every move and can step in at any time.

It does **not** call any AI model itself and takes **no API keys** — it coordinates the agents you
already run, each on its own subscription. Bothread is the room, the collision prevention, and the
human controls layered on top.

## The problem Bothread solves

- **They can't talk to each other.** Each agent runs in its own process, its own context, its own
  loop. They have complementary strengths — one plans, one refactors, one tests — but no way to
  actually work as a team.
- **They collide.** Two agents open the same file and quietly overwrite each other's work. By the
  time you notice, the damage is already committed.
- **You're shut out.** What little coordination exists happens invisibly, in terminals and config
  files. There's nothing to watch, and no moment to step in before something risky runs.

## Why it's different

Bothread isn't just message-passing and file-locking — a few open tools already do that in a
terminal. The part it adds is the **visible, human-governed room** on top:

| You can... | ...because Bothread gives you |
|---|---|
| **Watch** | A live thread of every message, decision, and file claim — with replies, edits, retractions, and agent-settable urgency, not a flat scroll. |
| **Review** | Point a room at a git repo and each agent's changes become a diff — merge it, discard it, or keep just the changes you want. Your own uncommitted work is never touched. |
| **Assign** | A shared task board — task, owner, status — so nobody has to reconstruct "who's doing what" by re-reading chat. |
| **Record** | Durable decisions, flagged issues, and verification reports that outlive the scroll — settled once, not re-litigated. |
| **Hand off** | Need a file another agent holds? Bothread routes a tracked request to the holder and tells the waiter the moment it's free — no idle stalemates. |
| **Approve** | Pick which risky actions (deploy, delete, git push…) need your yes — agents see it and ask first. |
| **Declare** | Each agent states its capabilities on join — can it view images, run a headless browser — so work routes to the right one from the start. |
| **Tag** | Channel tags keep two unrelated pieces of work from interleaving into one confusing thread. |
| **Catch up** | An agent that steps away and rejoins gets a real digest of what it missed — not just "welcome back." |
| **Audit** | Every join, claim, collision, merge, approval and nudge lands in a live activity trail you can scroll back through. |
| **Pause / Mute / Revoke** | Freeze the entire room, quiet one agent without removing it, or pull an agent's access instantly. |

Built for solo builders and vibe-coders — people who want to see and steer their agents, not read
raw JSON in a terminal — as much as for veteran engineers.

## At a glance

| | |
|---|---|
| **Cost** | Free, open source, MIT licensed |
| **Where it runs** | Locally, on `127.0.0.1` — no cloud, no account |
| **What it stores** | A local SQLite file (WAL mode); nothing leaves your machine |
| **What it needs** | [Node.js](https://nodejs.org) 20+, and at least one MCP-compatible agent |
| **What it doesn't need** | Any API key, any paid Bothread subscription, an internet connection to run |
| **Agent tool surface** | 19 MCP tools — messaging, file leases, tasks, notes, hand-offs, approvals |
| **Tested clients** | Claude Code, Claude Desktop, Cursor, Antigravity, Gemini CLI, Codex, OpenCode |

## Features

- 🧵 **One live thread** — agents talk to each other and to you, in real time, with replies,
  @-mentions (delivery-confirmed, not decorative), and editable/retractable messages.
- 🔒 **Collisions prevented** — agents claim files before editing; an overlapping exclusive claim is
  *denied and shown*, so two agents never silently clobber each other.
- 🌿 **Per-agent git diffs** — point a room at a git repo and each agent's changes between claiming and
  releasing files are captured as a reviewable diff. **Merge** it, **discard** it, or **keep only the
  hunks you want** — your own uncommitted edits are never touched. Automatic and opt-in (off unless
  the room has a git project folder).
- 🤝 **Routed hand-offs** — when an agent is blocked on a file another holds, Bothread opens a tracked
  request, @-mentions the holder, and notifies the waiter the moment it's released.
- 📋 **Shared task board & notes ledger** — a persistent task board (create/claim/update) and a
  durable notes ledger (decisions, issues, verification reports) every participant can see.
- ✋ **You're in command** — pause the room, approve / reject / redirect risky actions, mute or revoke
  an agent, message as the overseer, **nudge** a quiet one, and set per-room **approval gates**.
- 📜 **Live activity trail** — every join, claim, collision, merge, approval, and nudge is recorded and
  scrollable in the room's **Activity** tab. Full append-only audit, in plain sight.
- 🏠 **Local-first** — binds `127.0.0.1`, stores state in SQLite, no cloud, no account.

## How it works, in short

1. **Create a room** — open Bothread on your machine, start a room for your project, and get a
   private session ID.
2. **Connect your agents** — tell each agent "this is a Bothread session" and paste the ID. It joins
   in seconds.
3. **Watch them collaborate** — see the live conversation, who's claimed which files, and every
   collision prevented, as it happens.
4. **Step in anytime** — pause the room, approve a risky action, redirect with a message, mute or
   revoke an agent.

---

## Quick start

Any OS, same commands — pick one:

```bash
npx bothread start          # zero-install, try it right now
```

```bash
npm install -g bothread     # install once, `bothread` is on your PATH from any folder
```

Then, from **any** directory:

```bash
bothread start
```

It builds the room UI on first run and **opens the room in your browser**. Stop with `Ctrl-C`.

> ⚠️ **Common mix-up:** it's `npm install -g bothread`, **not** `npx install -g bothread` — `npx`
> *runs* a package, it has no install flag, and that command will just error. Use `npx bothread start`
> (no install) or `npm install -g bothread` (real global install) — never both together.

Building from source instead?

```bash
git clone https://github.com/AdamACE9/bothread.git
cd bothread
npm install   # install dependencies (one time)
npm link      # make 'bothread' runnable from anywhere
```

No git? On GitHub click **Code → Download ZIP**, unzip it, and open a terminal in the folder.
If `bothread` isn't found after `npm link`, just run `npm start` in the folder instead — same result.

### OS-specific notes

The commands above are identical on every OS — only the occasional troubleshooting differs:

🪟 Windows

Works as-is in PowerShell or cmd. If PowerShell refuses to run the `bothread` shim with a
*"running scripts is disabled on this system"* error, run once (as your normal user, not admin):

```powershell
Set-ExecutionPolicy -Scope CurrentUser RemoteSigned
```

The hub listens on both `127.0.0.1` and `localhost` (IPv4 + IPv6 loopback), so Claude Code's
`claude mcp add` works without header quirks. If a server shows as *failed*, make sure
`bothread start` is already running, then add it and check with `claude mcp list`.

🍎 macOS

If `npm install -g bothread` fails with an **`EACCES`** permission error, don't use `sudo` — point
npm's global folder at your home directory instead:

```bash
mkdir -p ~/.npm-global
npm config set prefix '~/.npm-global'
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.zshrc
source ~/.zshrc
```

If it instead fails because it can't find a prebuilt native module (`better-sqlite3`), install
Xcode's command-line tools so it can compile one:

```bash
xcode-select --install
```

🐧 Linux

Same commands as above. If the install fails trying to build `better-sqlite3` from source, install
build tools first (Debian/Ubuntu shown — use your distro's package manager otherwise):

```bash
sudo apt-get install -y build-essential python3
```

### Updating

Stop any running hub first (`Ctrl-C` in its terminal — two instances can't share a port). Then,
depending on how you installed it:

- **`npx`** — pin the version explicitly, since `npx` can reuse a cached one: `npx bothread@latest start`
- **`npm install -g`** — `npm install -g bothread@latest`, then `bothread start`
- **Cloned repo** — `git pull`, then `bothread start`

Either way, `bothread start` rebuilds the room UI automatically whenever its source changed, and
always runs fresh, so there's never a stale build silently left behind.

> **`bothread` not found after `npm link`?** Just run **`npm start`** in the folder — same result, no
> global command needed.

| Env var | Default | Meaning |
|---|---|---|
| `BOTHREAD_PORT` | `4889` | Hub port (bound to `127.0.0.1`). |
| `BOTHREAD_AUTH` | `off` | Token-free on `127.0.0.1` by default. Set `on` to require a bearer token. |
| `BOTHREAD_TOKEN` | _persisted_ | When auth is on, the bearer token (auto-generated + saved, stable across restarts). |
| `BOTHREAD_DB` | _per-user data dir_ | SQLite path; `:memory:` for ephemeral. |
| `BOTHREAD_NO_OPEN` | — | Set to skip auto-opening the browser. |

---

## Connect your agents

In the room, click **"Connect an agent."** The panel gives you copy-paste setup for each agent with
the MCP URL **already filled in**. You add Bothread to each agent once; then tell it
*"This is a Bothread session: ``"* and it joins. (The hub is token-free on `127.0.0.1`
by default; with `BOTHREAD_AUTH=on` the panel also fills in the `Authorization` header.)

| Agent | Add-server config | Native remote HTTP |
|---|---|---|
| **Claude Code** (CLI) | `claude mcp add --transport http bothread ` | ✅ |
| **Claude desktop app** | `claude_desktop_config.json` → `npx mcp-remote ` bridge (Settings → Developer → Edit Config) | bridge |
| **Antigravity** | `~/.gemini/config/mcp_config.json` → `serverUrl` | ✅ |
| **Cursor** | `.cursor/mcp.json` → `url` | ✅ |
| **Gemini CLI** | `~/.gemini/settings.json` → `httpUrl` | ✅ |
| **Codex** | `~/.codex/config.toml` → `url` | ✅ |
| **OpenCode** | `opencode mcp add bothread --url ` | ✅ |
| Others / stdio-only | bridge via `npx mcp-remote ` | ⚠️ via bridge |

> **Claude desktop app note:** the **"Add custom connector"** URL box is *cloud-brokered* — it can't
> reach a `localhost` hub. So a local Bothread goes in `claude_desktop_config.json` via the `mcp-remote`
> bridge; after a restart it shows up in the **+ → Connectors** menu as a toggle. *(Claude Code's CLI is
> the simpler local path — one `claude mcp add` line, no bridge.)*

Raw snippets: [`skill/mcp-config-examples`](skill/mcp-config-examples/README.md).

### Setting up an agent, step by step

1. **Add the Bothread MCP server** using the command for that client from the table above. The MCP
   URL (usually `http://127.0.0.1:4889/mcp`) is per-machine — copy it from your own running hub's
   "Connect an agent" panel.
2. **Install the etiquette skill** so the agent knows the room's conventions — claim before editing,
   hand off instead of stalling, keep messages terse:
   ```bash
   npx skills add AdamACE9/bothread -y
   ```
   This fetches the skill from this repo and installs it into the agent's own config automatically.
3. **Reload the agent** so the new `bothread` tools appear — adding an MCP server usually requires a
   restart of its process.
4. **Give it the room's live session ID** (shown in "Connect an agent", generated per room — it can't
   be predicted). It calls `join_session` with `{ sessionId, agentName, brand }`, then
   `get_room_state` to see who's already there and what's claimed.
5. **From then on it behaves like a teammate:** always `claim_files` before editing, never touch a
   file another participant holds, talk through `send_message` instead of assuming, and call
   `wait_for_update` instead of going idle when its step is done but the room's task isn't.

Full etiquette details: [`skill/bothread/SKILL.md`](skill/bothread/SKILL.md) and
[`skill/AGENTS.md`](skill/AGENTS.md).

### Other ways to install the skill

- **Claude Code plugin:** this repo is also a valid plugin + single-plugin marketplace
  (`.claude-plugin/plugin.json` + `.claude-plugin/marketplace.json`). Inside Claude Code:
  `/plugin marketplace add AdamACE9/bothread` then `/plugin install bothread@bothread`.
- **Claude (web / desktop app):** download **[`bothread-skill.zip`](https://bothread.vercel.app/bothread-skill.zip)**
  → **Settings → Capabilities → Skills → Create skill → upload it**.
- **Manual:** copy [`skill/bothread`](skill/bothread) into `.claude/skills/`, or put
  [`skill/AGENTS.md`](skill/AGENTS.md) in your project root (Cursor / Antigravity / Codex).

Full details: [`skill/README.md`](skill/README.md).

## The agent tool surface

`join_session` · `get_room_state` · `send_message` · `edit_message` · `retract_message` · `read_messages` ·
`wait_for_update` · `claim_files` · `check_files` · `release_files` · `renew_files` · `request_handoff` ·
`cancel_handoff` · `request_approval` · `create_task` · `update_task` · `record_note` · `resolve_note` ·
`leave_session`

Every call returns a clean structured result plus a readable summary, so an agent instantly
understands the room.

## Architecture

```
  agents ──MCP / Streamable HTTP──┐
                                  ▼
                           ┌──────────────┐    WebSocket     ┌────────────┐
                           │  Bothread    │ ──── push ─────▶ │  Room UI   │ ◀── you
                           │     hub      │                  └────────────┘
                           │  engine + SQLite (WAL, audit)   │
                           └──────────────┘
```

- **`packages/shared`** — zod schemas + types shared by the hub and the UIs (one source of truth).
- **`packages/server`** — the hub: a per-connection MCP server, the coordination **engine** (durable
  message thread, advisory file leases with atomic grant + TTL, blocking approvals, append-only audit),
  a REST control plane, and WebSocket push. State in `better-sqlite3` (WAL).
- **`apps/room-ui`** — the human room: live thread, participants rail, lock map, task board, notes
  ledger, and the pause / mute / revoke / approve / delete-room controls.
- **`skill/`** — the `bothread` Agent Skill, `AGENTS.md`, and per-agent connect snippets.
- **`website/`** — the marketing site + Get Started guide ([bothread.vercel.app](https://bothread.vercel.app)).

#

…

## Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [AdamACE9](https://github.com/AdamACE9)
- **Source:** [AdamACE9/bothread](https://github.com/AdamACE9/bothread)
- **License:** MIT
- **Homepage:** https://bothread.vercel.app

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** yes
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/mcp-adamace9-bothread
- Seller: https://agentstack.voostack.com/s/adamace9
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.