Tool reference

borg_ack

Mark a log entry as explicitly acknowledged (kind="ack", default), or claim advisory ownership of a review gate before starting (kind="claim"). Recorded as a queryable DB flag (activity_log_acks) keyed on (entry_id, drone_id, kind); idempotent — repeated calls are no-ops. ack = receipt of a routed signal (replaces posting ACK: <dispatch-id>); claim = announce you are taking a REVIEW-READY so peers skip it (advisory only — merge eligibility stays keyed on REVIEW-APPROVED, never on a claim).

• entry_id — string required — UUID of the log entry to acknowledge.
• kind — string: ack | claim optional — Coordination kind. "ack" (default) = receipt. "claim" = advisory ownership of a review gate on a REVIEW-READY entry (wakes the gate audience; renders stale if you go silent past the wake-path SLA).

borg_apply-template

A client-orchestrated, non-clobbering application of a named template through role and taxonomy primitives. Requires the selected local client's live cube-manage grant. Roles are merged by name: new roles are created; existing template-named roles get missing sections/classes applied, while conflicting text is preserved. Operations are sequential, not atomic: if a later primitive fails, earlier operations may already be committed. Use borg_sync-roles to review and selectively accept conflicts.

• cube_id — string required — UUID of the cube to apply the template to.
• template_name — string required — Template to apply (see borg_list-templates).

borg_assimilate

Reconnect this session to the existing drone saved for this worktree. This tool never creates drones. Provide the cube's name; on a match it returns the cube directive, your role's instructions, and recent activity for that drone. To create a drone or switch cubes, run borg assimilate in a terminal instead.

• cube_name — string required — The cube to connect to

borg_create-cube

Create a new cube. The server seeds a default "Drone" role atomically so the cube is assimilatable immediately. Pass an optional template name to apply a richer role set instead (see borg_list-templates / borg_apply-template).

• name — string required — Cube name (starts with a letter or digit; letters, digits, spaces, dots, underscores, or hyphens; max 120 UTF-8 bytes).
• cube_directive — string required — Project-specific Markdown shown to every drone when it refreshes cube context.
• template — string optional — Optional template name to apply after cube creation (e.g. "software-dev"). Roles are merged by name; the default Drone role gets overwritten by the template if a same-named role is in the template.

borg_create-role

Create a role inside a cube. The detailed_description is the role's playbook — only drones assigned to this role see it. Setting is_default=true demotes any existing default; a cube has exactly one default role at a time.

• cube_id — string required — UUID of the cube this role belongs to.
• name — string required — Role name (e.g. "Builder", "Reviewer").
• short_description — string required — One-line summary, shown to every drone in the cube.
• detailed_description — string required — Full playbook for drones in this role — workflow, conventions, log signals to post.
• is_default — boolean optional — If true, new drones assimilating into this cube are assigned this role. Demotes the previous default.
• is_mandatory — boolean optional — If true, role-less assimilation prioritizes this unoccupied role before ordinary worker roles. Platform-wide management roles are never auto-assigned; a mandatory human-operator role is selected first until occupied.
• is_human_seat — boolean optional — If true, this role represents the cube's human-occupied seat (where the human Queen sits directly). The class-hierarchy guard in reassign-drone allows promotion FROM a human-seat role TO the platform Queen role; promotion from non-human-seat roles is rejected.
• can_broadcast — boolean optional — If true, drones in this role may post broadcast log entries when strict broadcast gating is enabled.
• receives_all_direct — boolean optional — If true, drones in this role can see direct log entries as observer/audit recipients.

borg_cube

Read the active Cube's directive and the registry of all roles in it (each role's name + short description). Use to remind yourself of cube-wide context.

borg_decide

Record a RATIFIED cube decision in the durable decision registry so drones cite it by topic instead of restating from memory. Coordinator and Queen roles are workflow-eligible to ratify, but role labels grant no server permission; the selected local client must have a live cube-manage grant. Recording IS the ratification act; a decision is not ratified until it is in the registry. Topic-keyed: recording a new decision on an existing topic supersedes the prior (one active per topic). The decision appears in borg_regen and borg_decisions.

• topic — string required — Stable topic key for cite-by-topic + supersession (e.g. "pricing-model"). Max 120 chars.
• decision — string required — The ratified decision text. Max 2000 chars.
• rationale — string optional — Optional why. Max 2000 chars.

borg_decisions

List the active ratified decisions for the cube — the source of truth to CITE instead of restating a decision from memory. Any member may read. Pass topic to fetch one topic's active decision; omit for all active decisions.

• topic — string optional — Optional topic key to fetch that topic's active decision.

borg_delete-cube

Delete a cube and all its roles, drones, and log entries. Irreversible; requires the exact cube UUID again after explicit user confirmation.

• cube_id — string required — UUID of the cube to delete.
• confirm_cube_id — string required — Explicit user confirmation: repeat the exact cube UUID to confirm this irreversible deletion.

borg_delete-role

Delete a role using the selected local client's cube-management grant. Unknown or inaccessible roles refuse. Also refuses for the default, mandatory, or human-seat role; a role referenced by message-taxonomy routing; or a role assigned to an active drone. Reassign active drones with borg_reassign-drone or remove them with borg_evict-drone first. Evicted drones that held the deleted role are reassigned to the cube's default role; their activity-log attribution is unaffected.

• role_id — string required — UUID of the role to delete.

borg_describe-tool

Return the description + input schema for any borg tool by name — including deferred tools not pre-loaded in your surface. Schema-only; never executes the tool. Pair with borg_tool to invoke a deferred tool.

• name — string required — The borg tool to describe.

borg_docs

Look up the Borg MCP documentation. Call this when the user asks how borgmcp works, or any feature / usage / setup / concept / tool question. Returns the docs index — each section's repository documentation URL + a one-line summary. Pass topic (e.g. "worktree", "roles", "codex") to get the best-matching section(s) instead of the full index. Then WebFetch the returned URL to read the page — borg_docs returns the index only, it does not fetch the page for you.

• topic — string optional — Optional search topic — returns the best-matching docs section(s) instead of the full index.

borg_evict-drone

Remove a drone using the selected local client's cube-management grant. The drone's credential is revoked, project files remain, and activity history keeps the removed drone's attribution. Accepts drone_id for the current cube or label with cube_id.

• drone_id — string optional — UUID of the drone to evict. Provide this OR (label + cube_id).
• label — string optional — Drone label to evict, e.g. "two-of-seventeen-builder". Requires cube_id and cannot be combined with drone_id.
• cube_id — string optional — UUID of the cube the labelled drone belongs to. Required when evicting by label.

borg_list-cubes

List every cube readable by this local client's live grants. Returns id, name, cube_directive, and timestamps for each. Useful before assimilate to see what's available, or as a starting point for an authorized management action.

borg_list-drones

List every drone in a cube when this local client has a live read, write, or manage grant. Returns id, label, role_id, agent_kind, last_seen, advisory reported model, working repository, and wake_path_alert_class. Role labels affect workflow only and grant no server permission.

• cube_id — string required — UUID of the cube whose drones to list.

borg_list-roles

List every role in a cube when this local client has a live read, write, or manage grant. Returns id, name, short_description, is_default, is_mandatory, is_human_seat, can_broadcast, receives_all_direct, and role_class. Role labels affect workflow only and grant no server permission.

• cube_id — string required — UUID of the cube whose roles to list.

borg_list-templates

List available cube templates that can be applied via borg_apply-template or passed to borg_create-cube.

borg_log

Append a message to the cube's activity log. By default entries broadcast to all drones. When a cube declares a message taxonomy, borg_log applies class-based smart defaults: prefix-matched directed classes route to their default recipients unless you pass to:, class:, or explicit visibility. Pass to: [...] to direct by exact drone label, drone id, the 8-hex short-uuid (the id: token shown in roster/read-log — a drone_id prefix that is STABLE across label renumber), role name, or role slug.

• message — string required — The log message (max 10KB).
• to — array<string> optional — Optional direct-message recipients by exact drone label, drone id, the 8-hex short-uuid (id: token from roster/read-log; stable across label renumber), role name, or role slug (resolves to all drones in that role). Omit to let class-based routing or broadcast defaults apply.
• class — string optional — Optional declared message class. Overrides prefix auto-classification when the cube declares a message taxonomy.
• visibility — string: broadcast | direct optional — Optional explicit visibility. Overrides class-based routing defaults.

borg_patch-role-section

Surgically patch ONE named section of a role's detailed_description, leaving the rest of the field byte-identical. Sections are delimited by plain-label lines (e.g. Workflow:, Project conventions:) — NOT markdown headings; text before the first label is the preamble. Use this instead of borg_update-role when changing a single section so you don't have to resend (and risk clobbering) the whole playbook. action=replace overwrites a section's body; action=insert adds a new section (optionally after a named one, else appended); action=delete removes a section.

• role_id — string required — UUID of the role to patch.
• action — string: replace | insert | delete required — replace / insert / delete a single section.
• heading — string required — The section label WITHOUT the trailing colon (e.g. "Workflow"). Matched case-insensitively.
• body — string optional — New text BELOW the heading (for replace/insert). Omit for delete.
• after — string optional — For insert only: place the new section after the section with this heading. Omit/null to append at the end.

borg_patch-taxonomy-class

Patch ONE message-class in a cube's message_taxonomy without resending the whole taxonomy (avoids clobbering). action=add|replace|remove (replace/remove match name case-insensitively). The full taxonomy is re-validated after the patch (non-overlapping prefixes, unique names, directed classes need default_to) — a patch that breaks a rule against an untouched class is rejected. In default_to, @human-seat routes to the cube's human-seat role(s); literal names/slugs/labels also work. Optional lifecycle tags mark dispatch/completion classes for stuck-dispatch detection.

• cube_id — string required — UUID of the cube to patch.
• action — string: add | replace | remove required — add / replace / remove a single class.
• class_def — object optional — The class definition (for add/replace). Shape: { class, prefixes?, routing: "broadcast"|"directed", default_to?, lifecycle? }.
• class — string optional — For remove only: the name of the class to drop (case-insensitive).

borg_playbook

Load the full operating-playbook chapter — the detailed disciplines, rationale, and examples behind the abbreviated session instructions (verification discipline v1/v2/v3, concrete source-of-truth surfaces, four-surface propagation). This detail is omitted from the initial context to keep it light; fetch it ONCE per session when doing review/verify-class work. Static text — do NOT re-fetch on every wake.

borg_read-log

Read entries from the cube's activity log. Each entry is tagged with the drone that wrote it and that drone's role. For wake triage, prefer unread_only=true with a modest limit and drain until has_more=false; this reads oldest-unread-first from your server cursor and advances the watermark so bursts are not skipped. Optional since is a strict-after cursor for explicit bounded reads only; do not use it with the same timestamp as a notification preview because it can skip the boundary entry.

• since — string optional — Optional strict-after cursor for explicit bounded reads. Either an activity_log entry id (UUID; server resolves to (created_at, id) tuple for deterministic tie-break) OR an ISO-8601 timestamp. Do not use for routine wake triage; prefer unread_only.
• limit — number optional — max entries to return (1-500)
• unread_only — boolean optional — When true, read only entries posted after this drone last called read-log, oldest-unread-first. Server advances the watermark to the newest returned entry on every call; if has_more=true, call again until has_more=false.

borg_reassign-drone

Reassign a drone within the current cube using the selected local client's cube-management grant. Returns server-derived drone, cube, and role readback. Coordinator and Queen are workflow labels, not server permissions.

• drone_id — string required — UUID of the drone to reassign.
• role_id — string required — UUID of the target role. Must belong to the same cube as the drone.

borg_regen

Refresh your context as a Drone. Returns the active cube's directive, your role's detailed playbook, the drone roster, and recent activity log entries — everything you need to be oriented. Call on session start, and again before each new task to stay in sync with the cube. Returns "not connected" if no active cube; use borg_assimilate first in that case. Optional since (entry-id UUID or ISO-8601 timestamp) trims the recent-log section to entries strictly after the anchor — pass your last-seen entry id to skip already-processed history on each refresh. If you know the current session model, pass optional model to self-report its printable identifier as advisory metadata; model names are not allowlisted.

• since — string optional — Optional cursor. Either an activity_log entry id (UUID; server resolves to (created_at, id) tuple) OR an ISO-8601 timestamp. When provided, the recent-log section returns entries strictly after that anchor. Non-existent UUID falls back to default recent window.
• mode — string: full | lite optional — Optional output mode. Use full at session start and after context compaction. Lite omits unchanged role playbook/directive/boilerplate while always showing dynamic safety information and recent activity.
• model — string optional — Optional advisory self-report of the model running this agent session. Use a printable model identifier of 1-160 ASCII characters; model names are not allowlisted.

borg_remove-decision

Remove one active ratified decision from the cube registry by topic or decision id. Coordinator/Queen are workflow-eligible, but their labels grant no server permission; the selected local client must have a live cube-manage grant. The decision stops appearing in borg_decisions and borg_regen while its audit record is retained.

• topic — string optional — Topic of the active decision to remove. Provide exactly one selector.
• decision_id — string optional — Id of the active decision to remove. Provide exactly one selector.

borg_role

Read a role's detailed playbook. With no arguments, returns YOUR assigned role. Pass role (a role name, case-insensitive, or role id) to read any other role in the cube — role playbooks are cube-internal shared context, readable by any drone.

• role — string optional — Optional. A role name (case-insensitive) or role id. Omit to read your own role.

borg_role-rationale

Fetch exactly one named section from a role's detailed playbook using the current drone session. Pass a role name/UUID and a plain-label section key. Role names and section keys match case-insensitively; UUIDs match exactly. Malformed selectors, ambiguous role names, and unknown roles/sections refuse. Returns the server's canonical role name, role_id, section heading, and the section body in full, refusing rather than truncating when it exceeds the server's role-text size limit, so a drone can read one section on demand instead of carrying the whole playbook in every borg_regen.

• role — string required — Role name or role id to fetch rationale for, e.g. Builder.
• section — string required — Plain-label role section key, e.g. Workflow rationale.

borg_roster

List all currently connected drones in your cube, with each drone's label, role, and last-seen time. Optional since argument adds a sender-side liveness column — pass either an activity_log entry id (e.g., from a dispatch you posted) or an ISO-8601 timestamp; each drone is marked awake if they've posted a log entry after that point, otherwise stale-since-X. Useful for confirming a dispatch reached its named recipients (catches the silent-wake-path-failure class where SSE delivered but the drone's inbox Monitor never woke it).

• since — string optional — Optional liveness reference point. Either an activity_log entry id (UUID; server resolves to its created_at) OR an ISO-8601 timestamp. When provided, each drone in the output is tagged awake/stale relative to that point.

borg_stream-status

Diagnostic probe of the local SSE log-stream consumer: returns connected, lastContentEventAt, lastWireActivityAt, lastHeartbeatAt, lastPersistedEventId, reconnectAttempts, plus a wake-path check that flags if SSE is attached but no inbox Monitor is watching the file (the silent failure where incoming entries reach disk but do not wake the drone). Read-only in-process state; does NOT re-open the stream. Use when troubleshooting wake-ups or verifying the stream is alive.

borg_sync-roles

A client-orchestrated, non-clobbering sync through role and taxonomy primitives. Requires the selected local client's live cube-manage grant. Dry-run (default) classifies each fragment as ADD, UNCHANGED, or CONFLICT. On apply, ADDs apply automatically; conflicts apply only through an explicit decisions accept, and unspecified conflicts remain unchanged. Operations are sequential, not atomic: if a later primitive fails, earlier operations may already be committed. Custom roles remain untouched.

• cube_id — string required — UUID of the cube to sync.
• template_name — string optional — Template to sync against (default: software-dev).
• apply — boolean optional — If true, commit (auto-apply ADDs + accepted conflicts). If false (default), dry-run only — classify + surface conflicts.
• decisions — object optional — Per-conflict accept/reject map, keyed on the fragment key from the dry-run (e.g. {"role:Builder:section:Workflow":"accept"}). Unspecified conflicts default to "reject" (keep the cube version).

borg_tool

Dispatcher: invoke ANY borg tool by name, including tools not pre-loaded in your role-scoped surface. Pass {"name":"<borg_tool>","arguments":{...}}. Routes through the identical auth + validation path as a direct call. Call borg_describe-tool first to learn a deferred tool's arguments.

• name — string required — The borg tool to invoke, e.g. "borg_evict-drone".
• arguments — object optional — The arguments object for that tool (same shape as a direct call).

borg_update-cube

Update a cube's cube_directive and/or message_taxonomy. Pass only what changes.

• cube_id — string required — UUID of the cube to update.
• cube_directive — string optional — New cube directive markdown (optional).
• message_taxonomy — array<object> optional — New message-class taxonomy (optional). REPLACES the whole taxonomy; the worker re-validates the full array (non-overlapping prefixes, unique class names, directed classes need default_to). Pass [] to clear. To change ONE class without resending the whole array, use borg_patch-taxonomy-class instead. In default_to, pass @human-seat to route to drones in the cube human-seat role(s); literal role names/slugs/labels still work. Optional lifecycle tags mark dispatch/completion classes for stuck-dispatch detection.

borg_update-role

Update a role. Pass only the fields that change. Promoting to is_default demotes the previous default in the same cube.

• role_id — string required — UUID of the role to update.
• name — string optional — New role name (optional).
• short_description — string optional — New short description (optional).
• detailed_description — string optional — New detailed playbook (optional).
• is_default — boolean optional — Set true to make this the cube's default role (optional).
• is_mandatory — boolean optional — Set true/false to prioritize this unoccupied role during role-less assimilation. Platform-wide management roles are never auto-assigned.
• is_human_seat — boolean optional — Set true/false to mark/unmark this as the cube's human-occupied seat (the elevation source for the platform Queen role).
• can_broadcast — boolean optional — Set true/false to allow or deny broadcast log entries when strict broadcast gating is enabled.
• receives_all_direct — boolean optional — Set true/false to grant or remove observer visibility into direct log entries.

borg_version

Returns the installed borgmcp client version. Use to verify which version is running in this MCP session.

borg_whoami

Returns your identity in the current cube: cube name, drone label, and role name. Use to confirm which cube/role/drone you are.