borgmcp weekly downloads statistics

Borg MCP

Multi-agent coordination for Claude Code, Codex, and OpenCode. Borg runs the agent CLI you already installed and connects its sessions through a self-hosted coordination server on your computer or private LAN. A shared coordination space is a cube. Each connected agent session is a drone, and its role defines how it works.

Install

npm install -g borgmcp

Continue with the Get Started guide to check the requirements, configure Borg, start the local server, and add your first drone. Borg has no hosted account or subscription.

Choose A Command

• borg clone <repository-url> checks out a new repository and delegates its complete cube, roster, and launch setup to borg quickstart. Use --checkout-only to stop after checkout; --no-launch remains an explicit compatibility alias. In a non-interactive terminal, full setup requires both --yes and --template <name>.
• borg quickstart creates, staffs, and launches the full roster for the Git repository you are already in. Repeat --role <slug>[:<count>] to replace the template roster with an explicit selection. Rerunning it keeps existing drones and continues after cancellation or partial failure.
• borg assimilate [role] adds or resumes one drone under one role. Use it when you need one more drone or want to reattach a saved worktree, not when you want the repository's complete initial roster.
• borg representative prepare --host <host:port> --coordinator <drone-label> connects a human representative: a separate automated drone, under its own role, through which a standard MCP host such as Hermes relays your requests, questions and decisions to one named Coordinator — the drone whose role speaks with the human's authority and dispatches the others — and reads its replies. borg representative mcp serves its five restricted tools over stdio. The representative is not you and not the Coordinator, cannot address other drones, and sees reply content only when it reads. Reading is replayable until the host calls deliver after durably persisting the replies. A separate borg representative listen --worktree <path> emits body-free wake hints; borg representative status --worktree <path> reports tool and listener ownership. See Human representative.

Activity-Log Routing

Every borg_log call requires an explicit to audience: use "broadcast" for the whole cube or a non-empty selector array for direct delivery. Omission, message prose, and taxonomy classes never choose recipients. Direct recipients determine delivery and wakes, not read confidentiality; the cube remains the trust boundary. Use borg_read-log to drain unread entries and borg_read-entry to retrieve one known complete entry by entry_id without moving the unread cursor.

Pass refs with local Git refs when a log entry needs commit provenance. The client resolves each ref in the seat repository and appends <ref> = <40-hex> to the message; REVIEW-READY entries require this mechanism. Invalid refs and typed full SHAs whose seven-character prefix resolves to a different commit are refused. Full SHAs that cannot be checked locally remain allowed and are listed as unverified in the tool result for cross-repository citations.

Documentation

• Core concepts defines cubes, drones, roles, and the activity log.
• CLI commands covers launching, resuming, updating, and worktree maintenance. The installed client's borg --help and borg <command> --help are the exact reference for its version.
• MCP tool reference lists the borg_... tools available inside agent sessions.
• Cube documents explains immutable durable content, revisions, removal, and structured activity-log citations.
• Human representative explains connecting an MCP host such as Hermes to one Coordinator, message attribution, retries, replayable reads with a delivered checkpoint, and supervised wake hints.
• Server operations covers loopback and private-LAN operation.
• Security explains invitations, client access, and network exposure.
• Self-hosting covers data locations, backups, client administration, and upgrades.
• FAQ answers common setup and workflow questions.

For client-specific recovery details, see docs/LOCAL_SERVER.md and docs/SEAT_LIFECYCLE.md.

Agent Permissions

Borg can remove repeated approval prompts for its own coordination tools. It does not approve shell commands, file operations, or web access.

Claude Code receives Borg's MCP tool allowlist at launch. For Codex and OpenCode, Borg checks the effective configuration and automatically applies a launch-only override when restrictive Borg approvals are found. It prints the affected tool count and discloses that approving borg_tool also approves any Borg operation invoked through it. Pass --no-borg-approval-override to skip the override and receive the warning plus repair snippet instead. The launch-only override does not modify the agent's configuration. borg setup can show the corresponding persistent configuration snippets.

Wake Recovery

If borg_regen or borg_stream-status reports a wake-up problem, follow the recovery command it prints. For Codex or OpenCode, relaunch through borg if the agent's local control connection is no longer available.

License…