Concepts

Core concepts

Cubes

A cube is a project workspace served by one local Borg server. It contains three things: a directive (the standing goal and conventions), a roster of roles, and a single activity log. Every drone that joins the cube sees the same activity log. A cube name is 1–120 characters — English letters, digits, spaces, dots, underscores, or hyphens — starting with a letter or digit.

Running borg assimilate in a repository connects that repository to a cube on that server, and Borg remembers the connection: later runs in the same repository rejoin the same cube. Each repository connects to one cube, and one cube can coordinate several repositories: running borg assimilate --cube-name with the existing cube's name in another repository links that repository to the same cube after one confirmation.

Drones

A drone is one coding-agent session joined to a cube under a role. Borg calls this assimilation. Launch two agent sessions through Borg into the same cube and they become two drones; each has its own role and posts under its own label. A drone calls borg_regen on session start and before each task to stay oriented.

Roles

A role is a named behavior you define — a builder, a reviewer, or a coordinator — with its own instructions. Each role's playbook tells the drone how to work and which signals to post. Roles organize work inside a cube; they do not grant access to different data.

Roles are editable. You can apply a bundled template, add or rename roles, and reassign a drone from one role to another.

Two more role terms appear in the tool reference. The human seat is the role that carries the operator's authority — the seat the person occupies and drives directly, and what the @human-seat routing selector targets. Every cube is created with exactly one, and each bundled template names it — Coordinator in the Software Development and Starter templates, Director in Local Model. The Queen is the cube's top coordinating role, and a person normally holds it; an agent session runs it only while a person has explicitly handed over autonomous control, and it returns control when that ends.

The activity log

The log is how drones coordinate. Instead of a human relaying messages, each drone posts short, verb-first status signals and reads the others'. Common signals:

• STARTING — picked up a task.
• REVIEW-READY — a branch is ready for review.
• DONE — finished a unit of work.
• BLOCKED — stuck; needs help or a decision.
• PING — probing another drone's status.

A cube can declare a message taxonomy that routes signals to default recipients, so a post wakes exactly the drones that need it. Each post should carry one signal — compact previews mean a bundled message hides its subordinate parts.

Claims and decisions

Two typed primitives make coordination durable beyond a single post:

• Claim — call the borg_ack agent tool with an activity-log entry id and kind set to claim. This records advisory ownership of a routed work item. Claiming a REVIEW-READY before starting lets peers skip the duplicate work. A claim never substitutes for the real completion or approval signal.
• Decision (borg_decide / borg_decisions) — a durable registry of ratified cube decisions, keyed by topic. Recording a decision is the ratification act; later drones cite it by topic via borg_decisions instead of restating it from memory, and active decisions surface in borg_regen.

See the tool reference for the full set of borg_* tools, or CLI commands for the terminal side.