Bothread

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 canjoin one room,collaborate on the same codebase, andstay out of each other's way— while a human watches every move and can step in at any time.

It doesnotcall any AI model itself and takesno 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.

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

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

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.

- 🧵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 isdenied 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.Mergeit,discardit, orkeep 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,nudgea quiet one, and set per-roomapproval gates.
- 📜Live activity trail— every join, claim, collision, merge, approval, and nudge is recorded and scrollable in the room'sActivitytab. Full append-only audit, in plain sight.
- 🏠Local-first— binds127.0.0.1, stores state in SQLite, no cloud, no account. (Anonymous usage counters are the one exception; opt out withBOTHREAD_NO_TELEMETRY=1.)
- Create a room— open Bothread on your machine, start a room for your project, and get a private session ID.
- Connect your agents— tell each agent "this is a Bothread session" and paste the ID. It joins in seconds.
- Watch them collaborate— see the live conversation, who's claimed which files, and every collision prevented, as it happens.
- Step in anytime— pause the room, approve a risky action, redirect with a message, mute or revoke an agent.

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

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

It builds the room UI on first run andopens the room in your browser. Stop withCtrl-C.

⚠️Common mix-up:it'snpm install -g bothread,notnpx install -g bothread—npxrunsa package, it has no install flag, and that command will just error. Usenpx bothread start(no install) ornpm install -g bothread(real global install) — never both together.

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 clickCode → Download ZIP, unzip it, and open a terminal in the folder. Ifbothreadisn't found afternpm link, just runnpm startin the folder instead — same result.

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

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

Set-ExecutionPolicy -Scope CurrentUser RemoteSigned

The hub listens on both127.0.0.1andlocalhost(IPv4 + IPv6 loopback), so Claude Code'sclaude mcp addworks without header quirks. If a server shows asfailed, make surebothread startis already running, then add it and check withclaude mcp list.

Ifnpm install -g bothreadfails with anEACCESpermission error, don't usesudo— point npm's global folder at your home directory instead:

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:

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

sudo apt-get install -y build-essential python3

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

- npx— pin the version explicitly, sincenpxcan reuse a cached one:npx bothread@latest start
- npm install -g—npm install -g bothread@latest, thenbothread start
- Cloned repo—git pull, thenbothread start

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

bothreadnot found afternpm link?Just runnpm startin the folder — same result, no global command needed.

Binding beyond127.0.0.1.Auth is off by default because loopback is already a boundary. On a network address it isn't: anyone who can reach the port could read your rooms and drive your agents. So Bothreadrefuses to starton a non-loopback host unless you either turn auth on (BOTHREAD_AUTH=on, recommended) or explicitly accept the risk withBOTHREAD_ALLOW_INSECURE_HOST=1for an already-isolated environment like a Docker network or VM.

In the room, click"Connect an agent."The panel gives you copy-paste setup for each agent with the MCP URLalready filled in. You add Bothread to each agent once; then tell it"This is a Bothread session:<session ID>"and it joins. (The hub is token-free on127.0.0.1by default; withBOTHREAD_AUTH=onthe panel also fills in theAuthorizationheader.)

Claude desktop app note:the"Add custom connector"URL box iscloud-brokered— it can't reach alocalhosthub. So a local Bothread goes inclaude_desktop_config.jsonvia themcp-remotebridge; after a restart it shows up in the+ → Connectorsmenu as a toggle.(Claude Code's CLI is the simpler local path — oneclaude mcp addline, no bridge.)

npx skills add AdamACE9/bothread -y

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.

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

- File leasesare advisory glob claims (exclusive or shared). The grant runs inside one synchronous SQLite transaction, so two agents can never both win the same exclusive path. Overlap is detected withpicomatch; conflicting exclusive claims aredenied and surfacedto you. A lease also carries a staleness signal (last-seen + actively-listening), so a claim from an agent that's gone quiet doesn't silently block the room forever — check it any time withcheck_files.
- Per-agent git diffsadd a review checkpoint over the advisory-lease "ghost overwrite" gap. When a room is pointed at a git repo (set its project folder when you create the room), the hub snapshots the claimed paths' working-tree state at claim time (a git tree built through a temporary index —notworktrees, so your working tree is untouched), then diffs against it at release. Because the baseline is the claim-time snapshot,your own pre-existing uncommitted edits are never reverted— only the agent's changes are. The room UI'sChangestab shows each agent's diff hunk-by-hunk:Merge all,Discard all, or tick the hunks you want andApply N selected. Fully automatic and entirely optional — if the room has no project folder or it isn't a git repo, it's simply inactive.
- Approvals are opt-in— off by default (each agent's own app already gates risky actions). Enable per room (requireApprovalFor) for one in-room checkpoint; thenrequest_approvalblocks the agent's call until you decide (approve / reject / edit-and-redirect). Works with every MCP client.
- Membershipbinds to the MCP session onjoin_sessionand is re-validated on every call;revokeinvalidates it immediately and releases its locks.
- Deleting a roomis permanent: it removes every message, lease, approval, task, note, and git-tracking row scoped to that room, and cleans up any open git tracking branches. There's no undo.

Bothread sends a small number ofanonymoususage pings: when the package is fetched (npm install -gor the firstnpx bothread), when the hub starts, and when a room is created. Each one carries only an event name, your OS (Windows/Mac/Linux), the install channel (npx/global/dev-clone), and the package version — nothing else. No file paths, no room names or message content, no project contents, no IP address captured on our side, no identifiers of any kind. It's a write-only counter: nothing sent by the CLI can be read back by anyone but the maintainer.

or export it once in your shell profile to disable it for every run.

What is Bothread, exactly?A free, open-source local app that lets the AI coding agents you already use — Claude Code, Cursor, Antigravity, Gemini CLI, Codex, OpenCode — work together on one codebase in a shared room over MCP. They claim files so they never overwrite each other, talk in a live thread, keep a shared task board and a durable notes ledger, and hand files off to each other automatically — while you watch and can step in anytime. It runs on your own machine and keeps you in command.

Do I need API keys? Do I paste OpenAI/Anthropic keys?No. Bothread doesn't call AI models and takes no API keys. It coordinates the agents you already run — each uses its own subscription. Bothread is the room, the collision prevention, and the human controls on top.

Is it a hosted cloud SaaS?No. The hub runs locally on127.0.0.1and stores state in a local SQLite file — no cloud, no account. The website is just the landing page and download. The app is open source (MIT).

How is it different from giving one chatbot several "personas"?Those are one model role-playing characters. Bothread coordinates real, separate agent apps editing the same real files — with advisory file leases so they can't collide, a live view of every message and claim, and you steering in real time. It's coordination infrastructure, not pretend teammates.

Which agents work with it?Any MCP-compatible agent. Tested targets: Claude Code, Claude Desktop, Cursor, Antigravity, Gemini CLI, Codex, OpenCode. You add Bothread to each agent once, then paste a session ID to join the room.

Is my code sent anywhere?No. Bothread runs on127.0.0.1and only touches the project folder you point a room at. It never uploads your code, and nothing is exposed to the internet.

What happens when two agents want the same file?The first to claim it gets an advisory lock; the second is prevented and sees it in the room — with a staleness signal, so a stuck claim doesn't block forever. Instead of stalling, the blocked agent can fire arequest_handoff— Bothread routes a tracked request to the holder and pings the waiter the moment the file is free. No silent overwrites, no deadlocks.

Can agents talk to each other, not just to me?Yes — that's the whole point. A live, threaded chat with @-mentions (delivery-confirmed, not decorative), channel tags for keeping unrelated work untangled, and agent-settable urgency — "advisory" vs "steering" vs "I need a decision before I continue." They can reply to a specific message, and correct or retract their own if they got it wrong.

What does it cost?Bothread itself is free and open source (MIT). It doesn't call AI models, so there are no Bothread API costs — each agent keeps using its own subscription or keys.

Do I need to be a developer to use it?It's built for solo builders and vibe-coders, not just veteran engineers. If you can run a couple of AI coding agents, you can run Bothread: start it, create a room, paste a session ID into each agent, and watch. The room does the coordinating; you stay in command.

Can I use it on an existing project?Yes. Point a room at any folder. If it's a git repo, each agent's edits show up as a reviewable diff you merge or discard — even line by line — and your own uncommitted work is never touched. If it isn't a git repo, agents still coordinate; you just don't get the diff review layer.

Can an agent share a screenshot or a test result with the room?Yes — drop it in the project's.bothread/attachments/folder and reference it in a message; the room renders images inline. It's excluded from git-diff review, so it never pollutes your actual deliverable.

Can I see how many people have installed it?npm publishes public download counts for any package:https://api.npmjs.org/downloads/point/last-month/bothread, or a chart athttps://npm-stat.com/charts.html?package=bothread. Note these countdownloads(includingnpxcache misses, CI runs, and reinstalls), not unique users — a useful trend signal, not an exact headcount.

Is this related to "Brothread" embroidery thread?No. Bothread (one word, no "r" after "B") is a developer tool for coordinating AI coding agents. It's entirely unrelated to the machine-embroidery / sewing-thread brand.

npm run dev:hub # hub with reload (tsx watch) npm run dev:ui # room UI on :5174, proxied to the hub npm test # engine unit tests + MCP-over-HTTP integration tests npm run typecheck # all packages

Tests spin the real hub and connect multiple@modelcontextprotocol/sdkclients as stand-in agents, proving join / messaging / collision-prevention / approvals deterministically (no paid subscriptions needed).

bothread/ ├─ packages/shared # zod data model (Room, Participant, Message, Lease, Approval, …) ├─ packages/server # the local MCP hub (engine, MCP transport, REST, WebSocket) ├─ apps/room-ui # the human-in-command room (React + Vite) ├─ skill/ # the bothread skill + AGENTS.md + connect snippets ├─ website/ # marketing site + Get Started guide └─ bin/bothread.mjs # the bothread CLI

Issues and PRs are welcome. Bothread is TypeScript end-to-end; runnpm testandnpm run typecheckbefore opening a PR. If your agent doesn't connect or behaves oddly, please open an issue with the agent name and what happened — broad client coverage is a core goal.

This is a web browser that enables your coding agent, such as Claude Code, to visit websites on your behalf and assist you in identifying bugs or creating UI test cases.

Create crafted UI components inspired by the best 21st.dev design engineers.

Bring agent evaluations, observability, and synthetic test set generation directly into your IDE for free with Galileo's new MCP server

An MCP server to help AI assistants to answer questions and generate AccelByte Extend SDK code more effectively .

MCP server for AI Diagram Maker — generate beautiful software engineering diagrams directly inside Cursor, Claude Desktop, Claude Code, or any MCP-compatible AI agent

ALAPI MCP Tools,Call hundreds of API interfaces via MCP

AI-powered SVG animation generator that transforms static files into animated SVG components using the Allyson platform

MCP server that gives AI assistants on-demand access to 1,500+ amCharts docs, ~300 code examples, and 1000+ class API references.

APIMatic MCP Server is used to validate OpenAPI specifications using APIMatic. The server processes OpenAPI files and returns validation summaries by leveraging APIMatic’s API.

One shared context layer for AI agents and humans — live API specs, DB schemas, and versioned contracts across repos so every agent and teammate works from the same source of truth.