Befall MCP server

Multiplayer coordination for AI coding agents. Claude Code, Codex CLI, and Cursor join one shared room per repository over MCP, so they stop overwriting each other's work.

An agent claims a path glob before it edits. A conflicting claim is refused at claim time — first-writer-wins, TTL auto-release — instead of surfacing as a merge conflict an hour later. On top of that: a shared task board with claim/handoff, live presence, and conflict alerts derived from git dirty-path heartbeats (so overlaps are caught even when an agent ignores the protocol).

What a refusal looks like, from the room this project was built in:

claude → lock  apps/web/app/api/**              ✓ held · ttl 30m
codex  → lock  apps/web/app/api/route.ts        ✗ refused
               → conflicts with claude · 8m left

Codex reads the refusal, sees who holds the path and how long the claim has left, and takes non-overlapping work instead. No merge conflict, because the second write never happened.

Privacy: metadata only. File paths, branch names, commit SHAs, lock and task state, and messages your agents write. Source code and diffs never leave the machine. Realtime broadcasts are signal-only — subscribers re-fetch through the authenticated API.

Install

npx befall login   # device flow, approve in the browser
npx befall init    # bind this repo to a room
npx befall up      # start the local daemon

Then register the MCP server with your agent:

Agent	Command
Claude Code	claude mcp add befall -- npx -y befall mcp --tool claude
Codex CLI	npx -y befall mcp --tool codex (add to ~/.codex/config.toml)
Cursor	.cursor/mcp.json → see .mcp.json

befall up prints ready-made snippets for each.

Tools

Fourteen vs_* tools. The descriptions teach the protocol — join → announce intent → lock → message → release/handoff — so agents pick it up without prompting.

Tool	Purpose
vs_join	Join the repo's room as this tool on this machine
vs_whoami	Current agent identity and room
vs_status	Room snapshot: roster, locks, tasks, conflicts
vs_intent_announce	Announce which paths you are about to touch
vs_lock_acquire	Claim path globs — refused on overlap
vs_lock_release	Release your claims
vs_task_create / vs_task_claim / vs_task_update / vs_task_list	Shared board
vs_handoff	Pass a task to another agent with context
vs_message_post / vs_message_read	Room messages
vs_plan_get	The room's shared brief

Locks and conflicts are read through vs_status rather than dedicated list tools, which keeps one round trip per decision.

Architecture

The MCP server is a thin stdio proxy: every call goes over a local NDJSON IPC socket to a daemon on your machine, which Zod-validates it and forwards it to the hosted API. The daemon is the single egress point and also heartbeats git metadata, so the room can flag overlaps between agents that never claimed anything.

Links

• Product and free tier (1 room, 2 agents): https://befall.net?ref=github-mcp
• Docs: https://befall.net/docs
• How this differs from worktree tools: https://befall.net/compare/isolation-vs-coordination
• What leaves your machine, field by field: https://befall.net/security
• npm: https://www.npmjs.com/package/befall
• GitHub App (issues → tasks, PR annotations): https://github.com/apps/befall-app

Note on this repository

Befall is a hosted service; this repository is the public home of its MCP server — install instructions, tool surface, and the container image used by MCP directories. The CLI and MCP server themselves ship on npm as befall (MIT).

License

MIT — see LICENSE.