agora-mcp

---

Retired

Claude Code now does this itself. Sessions coordinate, see each other's work and share state without a separate MCP server in between, which is what this existed to provide.

The repository is archived and read-only. It still works — nothing was removed from npm, and the last published version keeps installing — but it will not be maintained, and it does not need to be. If you want the idea rather than the package, the whole design is in docs/ and the licence lets you take it.

Why

When several Claude Code sessions work on the same repository — in parallel, or just over the course of a day — they're blind to each other. None of them knows what the others touched, they overwrite the same files silently, and the context is lost when you close them.

agora gives every session a shared place to leave a trail and look at each other's work.

How it works

The whole system is one SQLite file per repo: <repo-root>/.agora/space.db (in WAL mode, so multiple processes read and write it at once without corruption).

• No one runs a server. There's no daemon, no web app. The "space" is the file.
• Every session of the repo writes what it does and reads what the others did.
• Because it's a file, it persists by itself — close everything, come back tomorrow, the state is still there.
• It's a shared board, not a live chat: sessions find out when they start, when they're about to edit (collision), or when they ask (the tools).

Multi-worktree friendly: the .db lives at the main repo root, so every session of the repo — including those in different worktrees — shares one agora.

Features

• 🟢 See who's here and what files each session is touching, live.
• ⚠️ Collision warnings — before you edit a file (or work a branch) another active session already holds.
• 📋 Project resume — open a session and get a summary of what the others did.
• 📓 Activity log — a per-repo timeline of everything that happened.
• ✉️ Notes between sessions (directed or broadcast).
• 🛡️ Best-effort hooks — they exit 0 no matter what; they never block your session.

Requirements

• Bun 1.3+
• git 2.x
• Claude Code (or any MCP client)

Installation

From npm — nothing to clone:

# Register the MCP server — nothing to install for this part
claude mcp add agora -- bunx --bun @vorluno/agora-mcp

# The hooks need the CLI on your PATH. Install once, then run it from any repo.
# Idempotent; add --project to scope it to the current repo only.
bun add -g @vorluno/agora-mcp
agora-init init

From source — if you want to change it:

git clone https://github.com/vorluno/agora-mcp.git
cd agora-mcp
bun install
bun run src/cli.ts init
claude mcp add agora -- bun run /absolute/path/to/agora-mcp/src/index.ts

Configuration

Any MCP client works. The mcpServers entry:

{
  "mcpServers": {
    "agora": {
      "command": "bun",
      "args": ["run", "/absolute/path/to/agora-mcp/src/index.ts"]
    }
  }
}

For Claude Code, claude mcp add (above) writes this for you. For Warp or Cursor, paste the snippet into their MCP settings.

Tools

Tool	Description
resume_project	Summary of the agora: active sessions, recent activity, collisions, unread notes.
who_is_here	Active sessions and which files each one is touching.
activity_log	The repo's event log, filterable by time/session.
check_collision	Is another active session touching these files or this branch?
leave_note	Leave a note for another session (or broadcast to all).
read_notes	Read notes addressed to a session (marks them read).

How collisions are detected

• File collision: 2+ distinct sessions with an active writing claim on the same file.
• Branch collision: 2+ active sessions on the same branch but in different worktrees.

Only live sessions are counted, so a session that died without a clean exit won't produce false positives.

Automatic capture (hooks)

init installs 5 best-effort hooks (they always exit 0):

Hook	What it does
SessionStart	Registers the session and injects the agora summary into your context (also fires on /resume and after a context compaction).
PostToolUse (Edit/Write)	Records the file claim + event; warns if a new collision appears.
PreToolUse (Edit/Write)	Warns you before editing if another session already holds the file.
Stop / SessionEnd	Marks the session idle / stopped and releases its claims.

Development

bun test          # full suite (incl. a real WAL concurrency test)
bunx tsc --noEmit # type-check

Built test-first across 14 TDD tasks with per-task and whole-branch review.

Contributing and security

Read CONTRIBUTING.md first — its first line tells you whether your pull request will be considered. Vulnerabilities go to [email protected], never to an issue: see SECURITY.md, where the 72-hour acknowledgement is the one response time we commit to.

License

Apache-2.0 © 2026 Vorluno. See NOTICE.

Up to and including 0.1.0 this was MIT. Those releases stay MIT — a licence already granted cannot be withdrawn. From 0.2.0 on it is Apache-2.0, which grants patent rights explicitly.

---