Reference

CLI commands

The borg executable ships in the borgmcp npm package. Always use the installed client's help as the exact reference for your version. Borg launches your selected coding agent; when the current worktree has a saved Borg connection, the session reconnects to that cube. See the launcher explanation and --cli choices.

borg --help
borg <command> --help

Client lifecycle commands

• borg quickstart creates the repository's cube, adds one drone for every role in the template, and launches all of their sessions — the fastest path from a repository to a staffed cube. For a new cube it prompts for the template; --template <name> chooses it without prompting and --role <slug>[:<count>] replaces the default roster with exactly the roles you name. It requires a running Borg server and never starts one, and a rerun after a partial failure keeps and skips the drones that already exist. See Get started for the full setup sequence.
• borg clone <repository-url> [directory] clones a repository and then runs quickstart inside the new checkout. --checkout-only stops once the checkout is ready. A repeated command reuses an existing checkout only when its origin matches, and credential-bearing URLs are refused — use a Git credential helper or SSH configuration instead.
• borg assimilate [role] adds one drone to your Git repository and launches its coding agent already connected to the repository's cube. Omit the role to let Borg choose from the cube's roles and current staffing. To add several drones one at a time, pass each role explicitly. Each drone gets its own worktree and branch under ~/.borg/worktrees/<repo>/<name>. Borg names the worktree after the drone's role; pass --worktree <name> to set the directory name yourself. The worktree name does not select the role. borg assimilate --here resumes the drone saved in the current worktree instead of creating a new one. Use it to add a drone after quickstart, or to fill a role quickstart left out.
• borg launches the selected agent CLI. In a drone's worktree, it resumes that worktree's saved cube connection directly, without a menu. In an interactive terminal at the repository root, it shows a menu of the repository's drones available to resume so you can pick one; a drone is offered only when its saved connection is active and its worktree is still on disk.
• borg update updates the Borg client and its local server together, as a compatible published pair; it does not restart running agent sessions, so restart those yourself.
• borg doctor inspects Borg agent integrations without changing them, and reports a repair command when a check fails.
• borg cleanup reports orphaned Borg-managed worktrees.
• borg drones lists the drones registered on this machine, with each drone's cube, worktree path, agent CLI, and state. The registry belongs to this machine only.
• borg launch <drone-label-or-id-prefix> reopens one active drone from any directory. Borg finds the drone's worktree in the local registry and starts it exactly as if you ran borg in that worktree. If the drone is not active, or its worktree is missing, Borg refuses and tells you how to recover. When the same label exists in more than one cube, add --cube <name> or use the drone id prefix.
• borg launch-all [cube] opens the cube's saved drone worktrees; assimilate at least one drone first. In an interactive terminal on macOS with iTerm2 or Terminal.app installed, each drone opens in its own terminal tab or window, titled with the drone's name; on Linux the drones share one tmux session; with neither available, Borg prints the launch commands for you to run. --mode <tmux|terminals|pastelist> selects the backend explicitly.

Human representative

borg representative connects a human representative: a separate automated drone, under its own role, through which a standard MCP host (for example Hermes) sends your requests, questions and decisions to one named Coordinator and reads its replies. The Coordinator is the drone in the cube's human seat (see Roles). The representative is not you and does not replace the Coordinator. It cannot address other drones or broadcast.

• borg representative prepare --coordinator <drone-label> --worktree <name> creates the representative's own drone in a new worktree and binds it to exactly that Coordinator; borg drones lists the labels. It launches no coding agent and changes no other drone. The representative needs a role that already exists in the cube and is neither the human seat nor a coordinating role: the default name is hermes-representative, and --role <name> selects a different one. Create that role first, for example by asking the Coordinator to add it. If the named Coordinator is missing, duplicated, or not in the human seat, the command fails; it never selects a different drone. In a script or other non-interactive run, add --host <host:port> to name the Borg server. On success it prints the borg representative mcp command and an example host configuration.
• borg representative status --worktree <path> shows the saved connection, checks it against the live cube, and reports the listener and, when the Hermes plugin is installed, its setup state. <path> is the absolute path of the representative's worktree, as prepare prints it.
• borg representative mcp --worktree <path> is the command an MCP host starts, with the same absolute worktree path. It gives the host five tools over stdio — borg_representative_status, borg_representative_send, borg_representative_read, borg_representative_deliver and borg_representative_ack — and the host configuration holds no token, key, or URL. Any number of processes can use these tools at the same time.
• borg representative listen --worktree <path> --protocol 2 tells the host when to read. The host starts it with a pipe on its input; it prints a JSON line when replies are waiting — how many, never their text or sender — and reads the host's acknowledgements back. A reply that is still not delivered gets another line after 10 minutes, 1 hour and 6 hours, then every 24 hours. It stops when the host closes the pipe. Only one listener runs per representative. The Hermes plugin below runs it for you.
• borg representative hermes-plugin install sets up Hermes in one command. It installs Borg's Hermes plugin, borg-representative-push, in your Hermes home ($HERMES_HOME, else ~/.hermes; --hermes-home <path> names another, as an absolute path), writes its settings and the Borg MCP entry through Hermes's own commands, and enables it. It backs up config.yaml first, and if a step fails it undoes only its own changes. When the Coordinator replies, the plugin wakes one Hermes messaging-gateway conversation — a direct chat on Telegram, Discord, Slack or another gateway platform. Before it asks you anything, the command checks every value it would write. At a terminal it then asks for the representative's worktree when several are prepared, then for the chat, then for a [y/N] confirmation, where the default is no; it never picks a chat for you. A worktree or chat you give with --worktree <path> or --session-key <key>, or one that is already configured, is used without a question. A worktree or chat that would fail is listed as not selectable, with the reason. Without a terminal, a choice that is still needed is refused, and the command prints the exact command to run for each candidate. It restarts a gateway that runs as a system service; for a gateway you started by hand, it prints the restart command. It does not stop or restart Hermes Desktop: Desktop chats cannot be woken, but they can use the Borg tools. When the command says the Borg MCP entry changed, run /reload-mcp in open Desktop chats, or restart Desktop. --dry-run shows the steps without changing anything, and running the command again changes nothing that is already in place. borg update refreshes an installed plugin, and borg representative hermes-plugin uninstall removes only what Borg added.

The MCP process pushes nothing to the host: the host gets replies only when it callsborg_representative_read, and listen only tells it when to call.read returns the replies after the delivered checkpoint, oldest first, and does not advance the delivered checkpoint or the server's read position, so the same replies come back until the host delivers them. After the host has stored the replies, it calls borg_representative_deliver with the entry_id of the last one it stored; that moves the checkpoint, and the next read starts after it.borg_representative_ack only tells the Coordinator that a reply arrived; it does not move the checkpoint. A decision marked as authorized by you is the representative's own label, and the Borg server does not verify it. Thehuman representative guidecovers the host configuration, message format, retries, the listener's output, the Hermes plugin's setup and behaviour, and recovery errors.

Worktree maintenance

borg cleanup reports orphaned Borg worktrees by default. The --prune option performs the removal only when explicitly requested.

borg cleanup
borg cleanup --prune

Server and tools

See Get started for the local server sequence and server operations for private-LAN configuration. For in-session tools, use the tool reference.