agora

A shared, persistent space for your Claude Code sessions — per repository.

See what other sessions are doing, get warned before you overwrite their work, and leave notes. No daemon, no server to run.

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:

bash

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

bash

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:

config.json

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

bash

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 security@vorluno.dev, never to an issue: see SECURITY.md, where the 72-hour acknowledgement is the one response time we commit to.

License

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.

Built by Vorluno — a software studio from Panamá 🇵🇦

Part of the mcp-s family of MCP servers.