BORG

Get started

Install Borg and start a local server

A cube is a project workspace served by one local Borg server; a role is a named behavior you define, such as a builder or a reviewer; a drone is one coding-agent session joined to a cube under a role. Borg runs the coding agent you already installed: install one package, then use the client wrapper to prepare the local server and launch your agent into a cube as a drone. You type borg ... commands in a terminal; the agent calls borg_... tools inside its own session. Core concepts explains all three in full, along with the activity log the drones coordinate through.

  1. 1

    Check the requirements

    Install Node.js 22.18 or later, npm 10 or later, and at least one supported coding agent: Claude Code, Codex, or OpenCode. You also need a Git repository for Borg to coordinate — either one already on this machine, or the URL of one you can clone.

  2. 2

    Install and configure Borg

    Install the launcher, then run its interactive setup. On a first install, every detected coding-agent CLI is already checked. If no local server is installed, setup also offers to install the compatible one (borgmcp-server). Decline that install and setup exits without applying the agent changes you already approved, so accept it.

    By default, borg setup creates a loopback-only server identity: only programs on this computer can reach it. For private-LAN access, decide before running the command below — see Server operations for the sequence.

    $ npm install -g borgmcp
    $ borg --version
    $ borg setup

    If the shell cannot find borg, fix the npm global-bin PATH before continuing.

  3. 3

    Start the local server

    borg setup has already initialized the server's data directory and identity. Start it in the foreground and leave this terminal open.

    $ borg server start

    The server keeps this terminal and fills it with its dashboard, a read-only live status view. One line reports Endpoint: https://127.0.0.1:7091 and Bind mode: loopback.

  4. 4

    Create and launch the cube

    In a second terminal, cd into your repository and run borg quickstart. It creates the repository's cube, adds one drone for every role in the template, and launches all of their sessions.

    $ cd /path/to/your/repository
    $ borg quickstart

    Starting from a repository you have not cloned yet? borg clone <repository-url> clones it and then runs quickstart inside the new checkout, so an empty directory is a valid starting point. Pass --checkout-only to stop after the checkout is ready.

    $ borg clone https://github.com/you/your-repo

    Quickstart needs the server from step 3 and never starts one itself. If that terminal is not running, quickstart stops before creating anything and prints no Borg server is running at https://127.0.0.1:7091.

    For a new cube it asks which template to use — press Enter for Software Development — then shows the plan and asks once: Create and launch these 7 drones? [Y/n]. Each drone gets its own worktree and branch under ~/.borg/worktrees; your repository checkout stays untouched. Quickstart finishes with ✓ Cube `your-repo` is staffed. 7 drones launched.

    If a drone fails partway through, the ones already created are kept. Fix the cause and run borg quickstart again — it continues from where it stopped.

  5. 5

    Tell the coordinator what to build

    Quickstart staffs every role in the template, the coordinator included, so you direct the cube through a coordinator drone rather than taking that role yourself. Its closing line names the session to start in: Start in the coordinator session, followed by that drone's label.

    Switch to that session and describe what you want built. It dispatches the work to the other drones and they coordinate through the cube's activity log. Ask any launched agent to call borg_whoami to confirm its cube, drone, and role.

What's next

Add one more drone

Quickstart staffs the whole template at once. To add a single drone to a repository afterwards, cd into it and run borg assimilate: Borg assigns the role, creates the worktree, and launches that one agent. It is also the command you use to take a role quickstart left unfilled, such as after borg quickstart --role builder.

$ cd /path/to/your/repository
$ borg assimilate

Extra drones need nothing extra. Every drone's worktree and branch live inside the same repository, so one drone can read and merge another's branch directly — no remote, no pushing. Add a Git remote only to move the work off this machine. Pass --cli claude, --cli codex, or --cli opencode to choose the agent explicitly.

Add a second repository to the same cube

One cube can coordinate more than one repository — for example, an application and a library that change together. If your project spans a second Git repository, open a separate terminal, cd into that repository, and run borg assimilate --cube-name with the cube name Borg confirmed in step 4 (letter case is ignored; if more than one cube you can access matches, the command stops and links nothing).

$ cd /path/to/your/second-repository
$ borg assimilate --cube-name "your cube name"

Borg assigns this repository a role and connects it to the cube, then launches that drone's agent. Drones in both repositories now coordinate through the same cube. If the name does not match an existing cube, Borg starts creating a new cube with that name — answer n at the Create cube confirmation and rerun with the exact name. Borg links a repository once; later runs there rejoin the saved cube.

Server operationsSecurity guidance

Come back to a drone later

cd into the repository root and run bare borg with no arguments. Borg shows a launch menu that lists the repository's drones available to resume — pick one, and Borg relaunches the selected agent, reconnected to that drone's saved cube; no need to create it again. A drone is offered only when its saved connection is active and its worktree is still on disk.

In a drone's own worktree, bare borg skips the menu and resumes that worktree's drone directly. In a directory with no drones, Borg still launches an agent — just without a cube connection, so match the directory to the drone you want back. Check the line it prints when launching: [<drone> · <cube>] ◼ Launching <agent>… names the drone you resumed; [borg · <directory>] with no drone name means you are in the wrong directory.

$ cd /path/to/your/repository
$ borg

You do not need to remember worktree paths. borg drones lists the drones registered on this machine, with each drone's state. borg launch <drone>reopens an active drone from any directory, exactly as if you ran borg in its worktree.

To reopen every saved drone in a cube at once instead of one at a time, run borg launch-all from a repository already linked to that cube.

Learn the coordination model

Explore cubes, drones, roles, and the activity log — the shared vocabulary every Borg-connected agent uses.

Read core concepts →