{ "markdown": "
\n\n\"agora\n\n# agora\n\n**A shared, persistent space for your Claude Code sessions — per repository.**\n\nSee what other sessions are doing, get warned before you overwrite their work, and leave notes. No daemon, no server to run.\n\n[![License: Apache 2.0](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](./LICENSE)\n[![Bun](https://img.shields.io/badge/Bun-1.3+-fbf0df?logo=bun&logoColor=black)](https://bun.sh)\n[![Model Context Protocol](https://img.shields.io/badge/MCP-compatible-6E56CF)](https://modelcontextprotocol.io)\n[![Built with Claude Code](https://img.shields.io/badge/Built_with-Claude_Code-D97757)](https://claude.com/claude-code)\n\n
\n\n---\n\n> ## Retired\n>\n> **Claude Code now does this itself.** Sessions coordinate, see each other's work and share state\n> without a separate MCP server in between, which is what this existed to provide.\n>\n> The repository is archived and read-only. **It still works** — nothing was removed from npm, and the\n> last published version keeps installing — but it will not be maintained, and it does not need to be.\n> If you want the idea rather than the package, the whole design is in `docs/` and the licence lets you\n> take it.\n\n\n## Why\n\nWhen 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.\n\n**agora** gives every session a shared place to leave a trail and look at each other's work.\n\n## How it works\n\nThe whole system is **one SQLite file per repo**: `/.agora/space.db` (in WAL mode, so multiple processes read and write it at once without corruption).\n\n- **No one runs a server.** There's no daemon, no web app. The \"space\" *is* the file.\n- Every session of the repo **writes** what it does and **reads** what the others did.\n- Because it's a file, it **persists by itself** — close everything, come back tomorrow, the state is still there.\n- 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).\n\n> 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.\n\n## Features\n\n- 🟢 **See who's here** and what files each session is touching, live.\n- ⚠️ **Collision warnings** — before you edit a file (or work a branch) another active session already holds.\n- 📋 **Project resume** — open a session and get a summary of what the others did.\n- 📓 **Activity log** — a per-repo timeline of everything that happened.\n- ✉️ **Notes** between sessions (directed or broadcast).\n- 🛡️ **Best-effort hooks** — they exit `0` no matter what; they never block your session.\n\n## Requirements\n\n- [Bun](https://bun.sh) 1.3+\n- `git` 2.x\n- [Claude Code](https://claude.com/claude-code) (or any MCP client)\n\n## Installation\n\n**From npm** — nothing to clone:\n\n```bash\n# Register the MCP server — nothing to install for this part\nclaude mcp add agora -- bunx --bun @vorluno/agora-mcp\n\n# The hooks need the CLI on your PATH. Install once, then run it from any repo.\n# Idempotent; add --project to scope it to the current repo only.\nbun add -g @vorluno/agora-mcp\nagora-init init\n```\n\n**From source** — if you want to change it:\n\n```bash\ngit clone https://github.com/vorluno/agora-mcp.git\ncd agora-mcp\nbun install\nbun run src/cli.ts init\nclaude mcp add agora -- bun run /absolute/path/to/agora-mcp/src/index.ts\n```\n\n## Configuration\n\nAny MCP client works. The `mcpServers` entry:\n\n```json\n{\n \"mcpServers\": {\n \"agora\": {\n \"command\": \"bun\",\n \"args\": [\"run\", \"/absolute/path/to/agora-mcp/src/index.ts\"]\n }\n }\n}\n```\n\nFor **Claude Code**, `claude mcp add` (above) writes this for you. For **Warp** or **Cursor**, paste the snippet into their MCP settings.\n\n## Tools\n\n| Tool | Description |\n|------|-------------|\n| `resume_project` | Summary of the agora: active sessions, recent activity, collisions, unread notes. |\n| `who_is_here` | Active sessions and which files each one is touching. |\n| `activity_log` | The repo's event log, filterable by time/session. |\n| `check_collision` | Is another active session touching these files or this branch? |\n| `leave_note` | Leave a note for another session (or broadcast to all). |\n| `read_notes` | Read notes addressed to a session (marks them read). |\n\n## How collisions are detected\n\n- **File collision:** 2+ distinct sessions with an active `writing` claim on the **same file**.\n- **Branch collision:** 2+ active sessions on the **same branch** but in **different worktrees**.\n\nOnly **live** sessions are counted, so a session that died without a clean exit won't produce false positives.\n\n## Automatic capture (hooks)\n\n`init` installs 5 best-effort hooks (they always `exit 0`):\n\n| Hook | What it does |\n|------|--------------|\n| `SessionStart` | Registers the session **and injects the agora summary** into your context (also fires on `/resume` and after a context compaction). |\n| `PostToolUse` (Edit/Write) | Records the file claim + event; warns if a new collision appears. |\n| `PreToolUse` (Edit/Write) | Warns you *before* editing if another session already holds the file. |\n| `Stop` / `SessionEnd` | Marks the session idle / stopped and releases its claims. |\n\n## Development\n\n```bash\nbun test # full suite (incl. a real WAL concurrency test)\nbunx tsc --noEmit # type-check\n```\n\nBuilt test-first across 14 TDD tasks with per-task and whole-branch review.\n\n## Contributing and security\n\nRead [CONTRIBUTING.md](./CONTRIBUTING.md) first — its first line tells you whether your pull request\nwill be considered. Vulnerabilities go to **security@vorluno.dev**, never to an issue: see\n[SECURITY.md](./SECURITY.md), where the 72-hour acknowledgement is the one response time we commit to.\n\n## License\n\n[Apache-2.0](./LICENSE) © 2026 Vorluno. See [NOTICE](./NOTICE).\n\nUp to and including **0.1.0** this was MIT. Those releases stay MIT — a licence already granted\ncannot be withdrawn. From **0.2.0** on it is Apache-2.0, which grants patent rights explicitly.\n\n---\n\n
\n\nBuilt by **[Vorluno](https://vorluno.dev)** — a software studio from Panamá 🇵🇦\n\nPart of the [`mcp-s`](https://github.com/vorluno/mcp-s) family of MCP servers.\n\n
\n", "bytes": 6515, "sha": "ebc50c7a22a88741d7f117c97dafe68379c538bbc3d3dfd5efda0ca5ff286fe3", "repo_slug": "vorluno/agora-mcp", "fonte": "repo", "truncated": false, "api": "https://agentalog.com/api/listings/mcp_io_github_vorluno_agora_mcp_687e48a3/readme" }