Show HN: Bothread – multiple AI coding agents talk, share one repo, no collisions

Notifications You must be signed in to change notification settings

Fork 0

Star 6

BranchesTags

Open more actions menu

Folders and files

NameName

Last commit message

Last commit date

Latest commit

History

69 Commits

69 Commits

.claude-plugin

.claude-plugin

.claude

.claude

apps/room-ui

apps/room-ui

bin

bin

docs

docs

packages

packages

scripts

scripts

skill

skill

website

website

.gitignore

.gitignore

.nvmrc

.nvmrc

LICENSE

LICENSE

README.md

README.md

package-lock.json

package-lock.json

package.json

package.json

server.json

server.json

tsconfig.base.json

tsconfig.base.json

Repository files navigation

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

Website · Get started · The skill · npm

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

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.

Quick start

Any OS, same commands — pick one:

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

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

Then, from any directory:

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?

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):

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:

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:

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):

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.

Setting up an agent, step by step

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.

Install the etiquette skill

[truncated for AI cost control]