Skip to content

MCP Server

The Colony MCP server (@colony/mcp) exposes Colony pipeline tools inside any MCP-compatible editor — file issues, check pipeline status, estimate costs, trigger retries, and inspect diagnostics without leaving your editor.

It connects directly to Colony’s Postgres pipeline store and the GitHub API. It runs in two modes:

  • Local stdio — launched by your editor as a child process on your machine.
  • Central HTTP — one shared container on the Colony VM, accessible to all pilot users over Streamable HTTP.

After installing Colony’s CLI, run:

Terminal window
colony mcp

The command reads DATABASE_URL and GITHUB_TOKEN from your environment (or Colony config) and starts the MCP stdio server. Configure your editor to run this command as the MCP server process — the editor manages the process lifetime.

Alternatively, use npx without installing the CLI:

Terminal window
npx @colony/mcp

This fetches and runs the MCP server directly; set the required env vars in the editor config.

For shared pilot deployments, start one MCP container on the Colony VM:

Terminal window
docker compose --profile mcp up -d mcp

Before starting, set MCP_AUTH_TOKEN in .env:

Terminal window
MCP_AUTH_TOKEN=$(openssl rand -hex 32)

Pilot users point their MCP clients at:

http://<vm-host>:9300/mcp

with an Authorization: Bearer <MCP_AUTH_TOKEN> header. Expose this endpoint only on a trusted network, VPN, or behind a TLS reverse proxy — the MCP tools can create issues and mutate pipeline state.


Add to .mcp.json at the project root (project scope), or run claude mcp add colony -- colony mcp (add --scope user for all projects; this writes ~/.claude.json). Claude Code does not read mcpServers from settings.json:

Using colony mcp (installed CLI):

{
"mcpServers": {
"colony": {
"command": "colony",
"args": ["mcp"],
"env": {
"DATABASE_URL": "postgresql://user:pass@host/db",
"GITHUB_TOKEN": "ghp_..."
}
}
}
}

Using npx @colony/mcp (no install required):

{
"mcpServers": {
"colony": {
"command": "npx",
"args": ["@colony/mcp"],
"env": {
"DATABASE_URL": "postgresql://user:pass@host/db",
"GITHUB_TOKEN": "ghp_..."
}
}
}
}

Add to .cursor/mcp.json (per-project) or ~/.cursor/mcp.json (global):

Using colony mcp (installed CLI):

{
"mcpServers": {
"colony": {
"command": "colony",
"args": ["mcp"],
"env": {
"DATABASE_URL": "postgresql://user:pass@host/db",
"GITHUB_TOKEN": "ghp_..."
}
}
}
}

Using npx @colony/mcp (no install required):

{
"mcpServers": {
"colony": {
"command": "npx",
"args": ["@colony/mcp"],
"env": {
"DATABASE_URL": "postgresql://user:pass@host/db",
"GITHUB_TOKEN": "ghp_..."
}
}
}
}

VariableRequiredDescription
DATABASE_URLYesPostgres connection string for Colony’s pipeline store
GITHUB_TOKENPAT auth onlyGitHub personal access token. Not needed when config uses GitHub App auth
MCP_TRANSPORTNostdio or http. Defaults to stdio
MCP_AUTH_TOKENHTTP mode onlyBearer token required by the HTTP MCP endpoint
MCP_HOSTNoHTTP bind host. Defaults to 0.0.0.0
MCP_PORTNoHTTP port. Defaults to 9300
MCP_PATHNoHTTP MCP path. Defaults to /mcp
MCP_CONFIG_PATHNoExplicit path to colony.config.yaml when not using the default search path
COLONY_CONFIG_PATHNoFallback for MCP_CONFIG_PATH when that is unset
MCP_LOG_LEVELNoLog level (debug, info, warn, error). Defaults to info

The MCP server and the webhook-receiver honor database.* (url_env, ssl, max_connections, idle_timeout, connection_timeout, query_timeout, statement_timeout, keep_alive) and build their pool the same way as the other components. When both DATABASE_URL and GITHUB_TOKEN are set, the MCP server skips the config file, so only { url } and the defaults below apply; use a config file to change them.

  • Timeouts: 10 s connection timeout, plus a 60 s client query_timeout and a 60 s statement_timeout (sent as a startup option on direct endpoints only). The MCP server uses 60 s rather than the 30 s default of other components because tool calls run reporting and listing queries. Raise database.query_timeout and database.statement_timeout for longer queries.
  • TLS:
    • URL carries SSL parameters (sslmode, ssl, sslrootcert, …): the URL decides.
    • database.ssl unset and no SSL parameters in the URL: TLS stays as PGSSLMODE says (none if unset).
    • database.ssl: true, {} or { verify: true }: TLS with certificate verification against the system CAs plus NODE_EXTRA_CA_CERTS. A server without TLS, with a self-signed certificate or with a private CA not in the trust store now fails to connect.
    • database.ssl: { verify: false }: TLS without verification, with a once-per-process warning.
  • Opt-outs: trust the private CA (mount it under /colony/keys/ca-certs/*.crt or set NODE_EXTRA_CA_CERTS); set database.ssl: { verify: false }; put the SSL mode in the URL (for example sslmode=no-verify or sslmode=disable, which also applies to every component reading that URL); or leave database.ssl unset so only the URL and PGSSLMODE decide.

All tools are listed below. Arguments marked required must be provided; all others are optional. The repo argument always takes owner/name format (e.g. RunColony/colony).

Every tool honors the host-bound tenant scope when an embedding host sets one. Repos and items outside the scope are reported as not found, with the same error as a repo or item that does not exist, and listings and statistics cover only in-scope tenants. The standalone stdio and HTTP servers set no scope and are unscoped.

Query work items and pipeline state. The view parameter selects the operation.

ArgumentRequiredTypeDescription
viewYesstringstatus: pipeline health, queue depth, halt signals and today’s spend; list: browse issues with filters; diagnose: investigate a specific issue (block reason, transitions, runs, linked change and checks, question, constraints, recent operator commands, decision menu); findings: agent-recorded findings; transcript: tail an item’s agent turns and transitions
repoRequired for diagnose, findingsstringRepository in owner/name format. Optional for status and list (omit for a cross-repo aggregate).
issue_numberRequired for diagnosenumberIssue number — required for diagnose; optional filter for findings
tenant_idNostringTenant external ID for ambiguous repo names — status, list and findings views. Narrows within the host-bound tenant scope; cannot select a tenant outside it
stateNostringFilter by issue state — list view only
workflowNostringWorkflow id; returns only items pinned to it, and state is validated against its states — list view only
traitNostringactive, blocked, awaiting-human or terminal; items whose current state carries the trait in their own pinned workflow (unresolvable workflows are excluded) — list view only
sinceNostringStart date filter (ISO 8601) — list view only
untilNostringEnd date filter (ISO 8601) — list view only
limitNonumberMaximum items to return — list (default 50, max 200) or findings (default 100, max 200)
offsetNonumberItems to skip for pagination (default 0) — list view only
cursorNostringOpaque next_cursor from a previous call; omitted starts at the beginning of retained history; latest returns no entries and a cursor after the newest rows — transcript view only
detailNostringsummary (default) or full (adds tool results and system rows) — transcript view only
wait_secondsNonumberLong-poll up to this many seconds (0–25, default 0) when no entries are available — transcript view only
change_numberNonumberThe code host’s number for the item’s change — findings view only
statusNostringopen, accepted, resolved, dismissed or superseded — findings view only
record_kindNostringjudgement or check_result; when omitted, only judgement rows are returned — findings view only
check_nameNostringFilter by check name (e.g. lint, typecheck) — findings view only
check_outcomeNostringFilter by check outcome (e.g. fail, pass) — findings view only
categoryNostringFilter by finding category — findings view only
severityNostringFilter by finding severity — findings view only

View descriptions:

  • status — pipeline health: worker availability, queue depth by task type, active issue count by state, and total cost for the current period, plus per-repo halted and todaySpend (below). repo optional. With repo, the result is { repos: [<one entry>] }. Without it, the result is a cross-repo aggregate built from a fixed number of queries regardless of repo count: { summary, repos, omittedRepos }. summary holds repoCount, workers, queueDepth, activeIssueCount, totalCostCurrentMonth (all totals over every repo), haltedRepos ([{ repo, halted }]) and todaySpend keyed by tenant external id. repos lists only repos with activity (busy workers, pending tasks or active issues) or a halt signal, halted repos first and then by active issue count descending, capped at 50. omittedRepos counts the repos left out of repos. tenant_id disambiguates a repo name that exists under more than one tenant; it narrows within the host-bound tenant scope and cannot select a tenant outside it.
    • halted — { reason, since, resumesAt? } or null. reason is repo_disabled, daily_cost_ceiling or safestop; when several apply the precedence is repo_disabled > daily_cost_ceiling > safestop.
      • repo_disabled: the repo has active = FALSE. since is null (no deactivation time is recorded) and there is no resumesAt. The no-repo listing includes only active repos, so this appears only when repo is named.
      • daily_cost_ceiling: today’s persisted tenant spend has reached the effective cap (max_daily_usd less budget_headroom_pct). resumesAt is the next UTC midnight; since is the time of the cost event at which cumulative spend first reached the effective cap. Spend not yet persisted by a worker is not counted, so this can read null slightly before a worker halts.
      • safestop: inferred from the database because the safestop sentinel file is container-local. The repo has at least one active worker and every active worker is draining (a health-endpoint drain looks the same). since is approximate (the earliest updated_at of those workers, which heartbeats refresh); no resumesAt. A fully stopped pipeline shows as zero workers with halted: null.
    • todaySpend — { spentUsd, capUsd, effectiveCapUsd } for the current UTC day, whether or not halted, or null when max_daily_usd is unset or no config is loaded (stdio without config). The live config is preferred when available.
  • list — list issues filtered by state, with cost, cycle time, and assignees. repo optional for cross-repo queries. tenant_id disambiguates a repo name that exists under more than one tenant (without repo it limits the list to that tenant); it narrows within the host-bound tenant scope and cannot select a tenant outside it. Without workflow, state is accepted when it is a built-in state or a state declared by one of the repo’s active workflows: its activated workflows (repo_workflows), its default workflow, or any workflow pinned by one of its items. Without repo this covers every repo in the tenant scope (narrowed by tenant_id). An undeclared state is rejected with an error listing the sorted union. With workflow, state is validated against that workflow’s states only.
  • diagnose — diagnose why an issue is in its current state: state history, block reason, execution telemetry, and actionable recommendations. Requires repo and issue_number. After the why report, diagnose appends five MCP-only sections, in this order. A read that fails renders unavailable (<message>) for its section only; an empty section renders none.
    • Linked change — change number and URL plus each check’s name — conclusion (pending when not yet concluded). Resolved from the dependabot-pr link on Dependabot workflows, the open PR on the item’s own epic/<n> branch for epics, otherwise the open PR for colony/issue-<n>. Renders unavailable (no code-host connection) without a code host.
    • Outstanding question — the open clarification question (and summary) when raised in the current state and the item is not terminal.
    • Standing constraints — <id>: <body> per constraint, with the kind in parentheses when not prose.
    • Recent operator commands — the last 5 commands from operator_commands (verb, actor or —, status, time), newest first. Slash-comment commands are not recorded there; they appear in the lifecycle trace.
    • Decision menu — the open selection menu (self-improvement or Dependabot): kind, round id and each choice id — label, followed by Answer with colony_act action=pick.
  • findings — list agent findings for a repo or issue: observations, risks, and review findings. Requires repo. Deterministic check results are included only when record_kind: check_result is passed.
  • transcript — a read-only live tail of an item’s agent turns interleaved with its state transitions. Requires repo and issue_number; limit is 1–200 (default 50). Returns {entries, next_cursor, state, is_terminal}; pass next_cursor back as cursor to continue. summary returns assistant text (cut to 2,000 characters) and tool calls (input cut to 200); full adds tool results (cut to 4,000) and system rows. Thinking rows are never returned, secrets are redacted as [redacted:<pattern>], repo secret values (8+ characters, from workspace.secret_env_vars in the config the MCP server was started with) are redacted as [redacted:NAME], and cut or stored-truncated rows carry truncated: true. With wait_seconds > 0 and no new entries, the call re-reads once per second until entries appear or the wait expires; a terminal item returns immediately. Limits of repo-secret redaction on read: secrets that a host supplies only to workers through repoSecretsResolver (for example nomad workers) are unknown to the MCP server, so rows stored before write-time redaction existed are returned unredacted (newly stored rows are redacted at write time); with no config file (stdio, or the env-only container path) no repo-secret redaction happens on read.

File and enqueue an issue with Colony-aware formatting. Reads .colony/conventions.md from the target repo, applies appropriate labels, and validates scope.

ArgumentRequiredTypeDescription
repoYesstringRepository in owner/name format
titleYesstringIssue title
bodyYesstringIssue body in markdown
as_epicNobooleantrue files the issue as an epic. false files it as a single item, even if the body has a ## Subtask heading. Omitted: an epic only when the body has a ## Subtask heading
complexity_hintNosmall | medium | largeComplexity hint for the analyzer
constraintsNostring[]Standing constraints to record on the filed item before work starts (at most 20, each 1-2000 characters)
assigneesNostring[]Code-host logins to assign to the issue at creation

If the code host drops a login (GitHub silently drops users without access to the repository), the result’s warnings names it. The issue is still created.

When constraints is given, the issue is created without the enqueue label, the constraints are recorded as prose rows on its pipeline row, and only then is the enqueue label added — no station can claim work before the constraints exist. The repo must be registered with Colony; otherwise the call is refused before the issue is created.


Cost and time estimate before filing. Takes an issue description and repo, returns estimated cost (USD), confidence level, and likely outcome.

ArgumentRequiredTypeDescription
repoYesstringRepository in owner/name format
descriptionYesstringIssue description to estimate
complexityNosmall | medium | largeOptional complexity tier filter for percentile computation
tenant_idNostringTenant external ID for ambiguous repo names; narrows within the host-bound tenant scope and cannot select a tenant outside it

The local and global percentiles only use done issues that entered done within the last 180 days (state_entered_at; ESTIMATE_WINDOW_DAYS), so older history no longer shifts the estimate. historicalExamples lists the 20 most recently updated done issues, regardless of the window.


Get Colony’s review verdict on a PR. Returns the reviewer’s structured analysis: verdict, findings, and confidence.

ArgumentRequiredTypeDescription
repoYesstringRepository in owner/name format
change_numberYesnumberThe code host’s number for the change
tenant_idNostringTenant external ID for ambiguous repo names; narrows within the host-bound tenant scope and cannot select a tenant outside it

Perform an operator action on a work item. The action parameter selects the operation.

ArgumentRequiredTypeDescription
repoYesstringRepository in owner/name format
issue_numberYesnumberIssue number to act on
actionYesstringAction to perform — see table below
child_numberNonumberSubtask issue number — required for release
confirmNobooleanSet true to proceed with an action that requires confirmation — see below
actorNostringrelease: recorded as released_by (default mcp). invoke with intent=approve: recorded as the actor of the Accept verdict (an accepted issue event with via: api and the judged headSha); on an epic Accept it is also recorded on the accepted findings. Operator commands (answer, pick, constrain, unconstrain, feedback, retry, reimplement, adopt, followup, review, priority, skip-planning, decompose, state, unblock): actor of the operator status event (default none). Ignored otherwise
expected_head_shaNostringinvoke with intent=approve on a change, or on an epic (the head of the epic PR on epic/<n>): the head commit SHA you reviewed. If the change head differs, the call is refused with the machine-readable error head_moved (a JSON body { error, message, expected, actual }, isError set) and nothing is claimed or transitioned, so the item stays decidable; retry with the new SHA. Omitted means the head at call time
intentNostringDeclared action intent — required for invoke; a slug of lowercase letters, digits and hyphens
choiceNostringMenu choice id — required for pick. Self-improvement menus: option:<n> (1-based, as the menu shows it) or roll-again. Dependency-update menus: approve, decline-release, decline-major, adopt:<k>, recheck
round_idNostringMenu round id; pick is refused unless it is the open round
tenant_idNostringTenant external ID — chooses the item when the same owner/name#N exists in several tenants; applies to every action, including contributed ones. Narrows within the host-bound tenant scope and cannot select a tenant outside it
textNostringOperator text — required for answer, constrain and feedback; optional for reimplement (Dependabot adoption instructions) and followup (required on a Dependabot tracking issue, not needed on an epic); required for adopt
constraint_idNointeger or allConstraint id, or all to remove every standing constraint — required for unconstrain
request_idNostringIdempotency key, 1-200 characters — required for answer, pick, constrain, unconstrain, feedback, reimplement, adopt, followup, review, priority, skip-planning, decompose, state and unblock; optional for retry (generated when omitted, returned in the result) and enqueue (dedupes the label write on retry)
sizeNostringComplexity override for retry: small, medium or large (case-insensitive). Any other value is an isError result and nothing is written
levelNostringhigh, normal or low — required for priority; optional for enqueue
target_stateNostringState to move the item to — required for state
reasonNostringNon-blank reason, persisted verbatim on the transition record — required for state

Available actions:

ActionDescriptionAvailability
pausePause processing, stopping any run in progress; the issue can be resumed later, and resuming restarts that step. Requires confirm: true.Always
resumeResume a paused issue.Always
cancelCancel the work item and close it. Requires confirm: true.Always
retryThe same operation as /colony:retry, including on failure-blocked and dependency-blocked items, which resume at their resolved retry target. Optional size sets the complexity. See below.Always
reimplementDiscard the change and return to analysis, as /colony:reimplement does: closes the PR, deletes the colony/issue-N branch (not an active epic branch) and the workspace, closes and deletes the item’s own epic/<n> branch, and clears subtask edges. On a Dependabot tracking issue it adopts the update instead (optional text = adoption instructions). Requires request_id and confirm: true. Result: {status, request_id, action, message, state} (status: 'pending' while still running). Refusals (returned as errors): not_declared, illegal_transition, not_found, and the adopt reasons already_active, migration_active, from_mismatch, not_dependabot, empty_instructions, pr_not_open, no_pr.Workflow-declared
adoptAdopt a Dependabot update, as /colony:adopt does: opens a Colony issue that builds on the Dependabot PR with your text instructions. Requires text, request_id and confirm: true. Result: operator-command shape. Refusals: already_active, migration_active, from_mismatch, not_dependabot, empty_instructions, pr_not_open, no_pr, not_found.Always
followupFile a follow-up, as /colony:followup does: on a Dependabot tracking issue a linked issue that waits for the bump (requires text); on an epic the polish follow-up (no text). Requires request_id. Refusals: in_progress, not_dependabot, terminal, empty_instructions, not_found.Always
reanalyzeRe-run analysis with new context.Workflow-declared
reopenReopen a completed issue; sends it back to intake.Workflow-declared
releaseRelease a cancelled subtask of this parent so the parent can finalize without it. Requires child_number; optional actor is recorded as released_by (default mcp). issue_number is the parent. Refusals (not a subtask, not cancelled) return an error with no write. Requires confirm: true.Always
invokeRun any operator action the item’s workflow declares, selected by intent. Requires intent and confirm: true.Workflow-declared
answerAnswer the outstanding clarification question. Requires text and request_id. See below.Always
pickPick a choice on the item’s open selection menu (self-improvement candidates or dependency-update decision), as ticking it does. A pick takes the same first-wins round claim as a tick, reply or auto-selection; a pick that loses is refused already_picked. Requires choice and request_id; optional round_id (refused as stale_round unless it is the open round) and actor (dependency-update menus: recorded as selected.actor; self-improvement menus: named in the selection comment and recorded as the operator status event actor). Refusals: no_menu, stale_round, paused, unknown_choice (lists the valid ids), already_picked. answer cannot answer self-improvement rounds (refused self_improvement_selection); use pick. See strategy.Always
constrainRecord a standing constraint, as /colony:constrain does. Tracked items only. Requires text and request_id.Always
constraintsList the standing constraints on a tracked item with their stable ids (read-only; no request_id). Returns constraints (id, kind, body, created_at, oldest first). Tracked items only.Never
unconstrainRemove one standing constraint by its id, or every one with constraint_id=all. Tracked items only. Requires constraint_id and request_id. An id not on the item is refused as not_found.Always
feedbackRoute rework feedback, as /colony:feedback does. Requires text and request_id.Always
reviewSend the item to its workflow’s review state (in-review on colony-default), as /colony:review does. Requires request_id.Always
prioritySet the manual priority, as /colony:priority does. Requires level and request_id.Always
skip-planningSkip planning, as /colony:skip-planning does. Requires request_id.Always
decomposeSend the item to planning as an epic, as /colony:decompose does. Requires request_id and confirm: true.Always
stateMove the item to a target state, as the dashboard POST …/transition does. Requires target_state, reason, request_id and confirm: true.Always
unblockUnblock a blocked item, as the dashboard POST …/unblock does. Requires request_id.Always
enqueueSeed an existing issue into the pipeline, as /colony:enqueue does, by adding the enqueue label and waking intake immediately; a row pre-seeded by level (or by /colony:constrain) is adopted at intake. Refused with the reason (state) when the issue is already tracked; also refused when the issue is closed, is a pull request, or (with level) when there is no code-host connection. Optional level (high, normal, low) records the manual priority before intake. Result: { ok, status: 'enqueue_requested', label, priority }.Always

An action marked “Requires confirm: true” is not run on the first call. The result is a normal (non-error) JSON text with status: "confirmation_required", plus action, repo, issue_number and a message. Call colony_act again with the same arguments and confirm: true to proceed; confirm is not passed on to the action. Actions contributed by an embedding host are gated by their own declaration.

Workflow-declared actions (reimplement, reanalyze, reopen, and anything reached through invoke) are only available when the issue’s active workflow declares them. invoke reaches any declared action, not only reimplement, reanalyze and reopen. A workflow may rename these actions but not withhold the platform actions (pause, resume, cancel, retry). resume is an action in colony_act — there is no separate resume tool.

invoke

invoke resolves the item’s declared operator action for intent on its pinned workflow and runs it. Blocking side effects (merge-pr) run before the transition commits; best-effort ones (close-pr) run after. For example, { action: 'invoke', intent: 'approve' } accepts a change in human-review-ready on colony-default and colony-content, and approves a drafted reply on colony-support.

On colony-default and colony-content, approve no longer declares merge-pr. It records a verdict and moves the item to merge-pending without calling the code host’s merge. The builtin:merge station merges the accepted head, so Accept returns before the merge; watch the item’s state. Pass actor to record who accepted (it appears on the accepted issue event). Pass expected_head_sha to make Accept conditional on the commit you reviewed: if the change’s head differs, invoke is refused with code head_moved carrying both SHAs, nothing is claimed or transitioned, and the ask stays decidable. Without expected_head_sha, the judged head is the head at call time.

These two merge-station behaviours apply to any API Accept on these workflows, not only an epic’s. When a ruleset requires a review, Colony submits an approving review from its review identity before merging. When the code host definitively refuses the merge, the verdict is dropped and the item returns to human-review-ready. A transient failure (a 502, 503 or 504, a rate limit or timeout, or GitHub’s Base branch was modified) keeps the verdict and the merge station retries.

invoke is refused, with no write, when:

  • intent is missing or is not a slug;
  • intent is retry, pause, resume, cancel, release, review, priority, skip-planning, decompose, state or unblock, which have their own actions;
  • the resolved action is marked framework: true;
  • the workflow does not declare the intent (the error lists the actions available from the current state);
  • the intent is declared but not available from the item’s current state;
  • the action declares merge-pr and the item has a recorded epic branch;
  • the action is Accept and the item is a subtask whose epic branch is not its own (epic_subtask). An epic’s own item is accepted as described in Accepting an epic.

{ action: 'invoke', intent: 'approve', confirm: true } on an epic’s own item (epic/<n>) accepts and merges the epic with a single decision and no approval on the code host.

Preconditions. The item is in human-review-ready, is not paused, and has a current judgement ask that is not a tooling escalation. Optional inputs: expected_head_sha (the head of the epic PR on epic/<n>), choice (followup or no-followup, overriding epic.review.polish_followup), text (a note), actor, and request_id (minted when omitted).

What is recorded. The Accept verdict carries the actor, the epic PR head SHA and via: api. Every open blocking finding is dismissed as accepted, as /colony:approve does, with the actor and note; the follow-up choice is stored. The acceptance appears on the item’s timeline and in the issue events, and Colony posts the usual comment on the issue.

Result. { status: "completed", request_id, action, message, state, headSha, acceptedFindingIds }: the new state, the accepted epic head and the ids of the findings accepted. If the sprint-master has not finished within the wait, the call returns { status: "pending", request_id, message }; call again with the same request_id to get the outcome. The builtin:merge station merges the accepted head after the call returns.

Refusals. Each is returned as an error whose error field carries the code:

CodeMeaning
wrong_stateNot in human-review-ready
pausedThe item is paused
not_epicNot an epic
epic_subtaskA subtask with an epic branch that isn’t its own
nothing_to_acceptNo current judgement ask, or a tooling escalation
already_decidedReject, code-host approval or an earlier Accept won
head_movedThe epic PR head differs from expected_head_sha, or from the head the current escalation judged (run /colony:review); carries expected and actual
code_host_unavailableNo open epic PR, or its head can’t be read

Refusal shape. A colony_act refusal whose reason is one of wrong_state, paused, not_epic, epic_subtask, nothing_to_accept, already_decided, head_moved or code_host_unavailable comes back, for every verb, as an error whose text is JSON: { "error": "<code>", "message": "…", …details }. This includes pick’s paused and the already_decided of feedback and rework, which used to return Refused: … text. Any other refusal stays plain text starting Refused: ….

First wins. Accept, Reject, a code-host approval and /colony:approve all claim the same judgement ask; exactly one wins and the others are refused already_decided. A repeated Accept cannot merge twice. Once an Accept is recorded, a later CHANGES_REQUESTED review on the code host does not undo it: the merge station merges the accepted head. To stop it, pause the item or push a commit, which voids the verdict.

Branch rules. Colony submits an approving review from its review identity, recording the verdict, so a ruleset requiring one approval is satisfied. If the App is on the ruleset’s bypass list, no review is needed. If the rules can’t be satisfied (a single-App identity that cannot approve its own PR, code owners, more than one approval, Azure DevOps requestor policy), the merge is refused with a comment, the verdict is dropped and the item returns to human-review-ready to be decided again. A merge that is definitively refused for any other reason drops the verdict the same way; a transient failure keeps it and the merge station retries.

Head changes. The verdict is tied to the accepted head. It carries across Colony’s own base-branch merge into the epic branch; the periodic epic branch refresh leaves an epic alone while an Accept is open; a push by anyone else voids it, and the epic is merged only at the accepted head.

Azure DevOps. Behaviour is the same: the pull request is completed pinned to the accepted head, and a moved head is refused rather than merged.

An action that declares merge-pr is refused unless the MCP server has a code-host (GitHub) connection. Accept on colony-default and colony-content (which reads the change head) is refused code_host_unavailable when there is no code-host connection, the change head can’t be read, or the item has no open pull request.

Operator commands: answer, constrain, feedback

These three actions (and retry, below) deliver a human act that a host cannot send as a comment (slash commands and replies from bot identities are ignored). answer, constrain and feedback take text and request_id, both required.

  • answer answers the outstanding clarification question. It uses the same claim as a comment reply, so whichever arrives first wins, and the loser is told the ask was already answered. It resumes the item where a comment reply would. The answer is posted as a Colony comment naming the actor, and the comment stays visible to the planner, developer and reviewer. If answer fails after posting, the comment is removed and the claim released, so a retry with a new request_id leaves one answer comment. It is refused when:
    • there is no outstanding question ask;
    • the ask is not a question (for example a judgement ask);
    • the ask predates the item’s current state;
    • the ask was already answered;
    • the open round is a self-improvement candidate selection.
  • constrain records a standing constraint exactly as /colony:constrain does, on tracked items only. Seeding an untracked item stays a slash-command affordance.
  • unconstrain removes one standing constraint by constraint_id (or all of them with constraint_id=all; the string is case-sensitive), which is stable (unlike the ordinal that /colony:unconstrain <n> takes). The constrain and unconstrain results carry constraints (id, kind, body, oldest first), so a client can learn the id it needs.
  • feedback routes rework feedback exactly as /colony:feedback does: the clarification, transition or mailbox route, the same refusals (including Dependabot), and the same acknowledgement comment.
  • retry performs exactly what /colony:retry [small|medium|large] performs: the failure-counter reset and marker comment, the model-tier escalation, the status event operator retry (or operator retry: <size>) with actor as its actor, and the routing (re-enqueue the current executor, or move a blocked item to its resolved retry target). It takes no text. request_id is optional: when omitted MCP generates retry:<uuid>, so each call is a fresh retry, and the result carries the id used so a pending result can be polled. It is refused when the state has no executor and the item is not blocked. A retry written while the sprint-master is down runs on its next drain.

Answering decision menus

A self-improvement candidate menu is answered with pick: choice=option:<n> (1-based) selects that candidate, and choice=roll-again re-rolls the candidates. This is the same first-wins selection as ticking a checkbox, so whichever arrives first wins. Optional round_id pins the round. Refusals are no_menu, stale_round, paused, unknown_choice (lists the valid ids) and already_picked. answer refuses self-improvement rounds with self_improvement_selection.

Operator commands: review, priority, skip-planning, decompose, state, unblock

These six actions run through the same operator-command channel. Each takes a required request_id and an optional actor, and returns the same completed, refused, failed or pending result. Inputs are validated before anything is recorded: a missing request_id, a missing or unknown level (not high, normal or low), a missing target_state, or a missing or whitespace-only reason returns an error and writes nothing.

ActionTwinExtra inputsconfirm
review/colony:reviewnonefalse
priority/colony:prioritylevel (high|normal|low)false
skip-planning/colony:skip-planningnonefalse
decompose/colony:decomposenonetrue
stateDashboard POST …/transitiontarget_state, reasontrue
unblockDashboard POST …/unblocknonefalse

Refusals (an isError result, no change to the item):

  • review is refused from any state where /colony:review refuses (see slash-commands.md), including workflows with no review state, with the same per-state reason and comment as /colony:review.
  • decompose is refused with reason illegal_transition, and no label change, when the item’s workflow does not allow a transition to planning. The check runs before any label write; /colony:decompose behaves the same.
  • state is refused when target_state is not a legal transition from the item’s current state in its own workflow, and the error lists the valid targets. States declared by a custom workflow are accepted. On success the reason is stored verbatim and an operator state: <target> status event is written.
  • unblock is refused, with no write, when the item’s current state is not a blocked state. Use retry for an active item that still carries a stale blocked flag. The dashboard POST …/unblock returns 409 NOT_BLOCKED for the same input.
  • Any illegal transition raised while running an action is reported as a refusal with reason illegal_transition, not as a failure.

request_id. A string of 1-200 characters, unique per tenant. A repeat with the same id and arguments performs no second effect and returns the recorded outcome. The same id with different arguments is an error. Interrupted commands are never re-run: retry with a new request_id.

actor. For release it is released_by (default mcp). For the operator commands, including retry, it is the actor of the operator status event (default none); for answer it also appears in the answer comment. Other actions ignore it.

Results:

ResultMeaning
completedThe command ran. The result carries the route or the resume state (for retry, the resulting state).
refusedAn isError result naming the reason. The item is not changed: no transition, constraint or mailbox message. constrain and feedback post the same refusal comment as their slash-command twins; answer refusals post no comment and make no claim or transition.
failedAn isError result with the error, including interrupted.
pendingThe command has not finished within about 10 s. The result carries request_id; call again with the same id for the final outcome.

Execution model. The sprint-master executes these commands. They are durable and run once even if it is briefly down. Authorising the human behind actor is the embedding host’s job.

Slash commandcolony_act
/colony:enqueueenqueue
/colony:adoptadopt
/colony:followupfollowup
/colony:unconstrainconstraints (bare form lists the standing constraints)
/colony:unconstrain allunconstrain with constraint_id=all
/colony:reimplementreimplement
SI candidate checkboxpick (choice=option:<n> or roll-again)

List self-improvement tracks for a repo (read-only): active tracks, completion counts, and cooldown status. Each track reports its enabled flag, label, cooldown, active prompt version, completion count, cooldown status and active issue. To edit tracks, use the dashboard Tracks tab or the monitor tracks API (see API Reference).

ArgumentRequiredTypeDescription
repoYesstringRepository in owner/name format
tenant_idNostringTenant external ID for ambiguous repo names; narrows within the host-bound tenant scope and cannot select a tenant outside it

Publish a pre-decomposed plan as dependency-linked Colony issues. Dependents are created blocked until their prerequisites complete. Idempotency is best-effort by title — do not run two overlapping imports concurrently. Use dry_run to preview classification without creating anything.

A plan with more than one non-manual task automatically gets a parent epic issue: all tasks become subtasks targeting an epic/<n> branch that is reviewed and merged as a unit. Single-issue plans skip the epic. Pass as_epic: false to suppress the epic, or as_epic: true to force one. Tasks whose title is already live in the pipeline or open as a GitHub issue are skipped.

ArgumentRequiredTypeDescription
repoYesstringRepository in owner/name format
tasksYesarrayStructured task array — see schema below
dry_runNobooleanPreview classification without creating issues
as_epicNobooleanDefaults to true when the plan has more than one non-manual task; false suppresses the epic, true forces one
epic_titleNostringTitle for the epic parent issue (used when an epic parent is created)
epic_bodyNostringBody for the epic parent issue (used when an epic parent is created)
initial_stateNostringEntry state for root tasks. Must be a state of the repo’s active workflow, otherwise the call returns an error listing the valid states. Defaults to the workflow’s intake initial state
constraintsNostring[]Standing constraints to record on every created item (at most 20, each 1-2000 characters)
assigneesNostring[]Code-host logins assigned to the epic parent and every task, unless a task sets its own assignees. Falls back to the repository’s default_stewards when omitted

When constraints is given, each is recorded as a prose row on every item the import creates, in the same transaction as the item’s pipeline row and before any station can claim work. Items the import skips because they already exist are not changed.

tasks array item schema:

FieldRequiredTypeDescription
keyYesstringShort unique identifier, no spaces (e.g. auth-api, migrate-db)
titleYesstringConcise action phrase ≤ 72 chars, starts with a verb
bodyNostringMarkdown issue body — background, acceptance criteria, constraints
dependsOnNostring[]Array of key values this task depends on (omit or [] for root tasks)
needsHumanNobooleantrue if the task requires human intervention before Colony can proceed
crossRepoNostring"owner/other-repo" if the task belongs to a different repository
assigneesNostring[]Code-host logins for this task; overrides the plan-level assignees

List v2 repo intelligence items (mode: list, default), or run retrieval debug for a specific agent role (mode: retrieve). List mode returns architecture facts, invariants, failure patterns, design decisions, and other evidence-backed intelligence. Retrieve mode runs the same ranked-snippet retrieval an agent would receive and returns snippets, candidate files, and token estimates.

ArgumentRequiredTypeDescription
repoYesstringRepository in owner/name format
modeNostringlist (default): filtered intelligence items; retrieve: retrieval debug for the given agent role
tenant_idNostringTenant external ID for ambiguous repo names; narrows within the host-bound tenant scope and cannot select a tenant outside it
kindNostringFilter by kind (e.g. architecture, invariant, failure_pattern, design_decision) — list mode
statusNostringFilter by status: candidate, observed, proposed, approved, dismissed, superseded — list mode
scope_kindNostringFilter by scope kind (e.g. repo, package, path, file, symbol) — list mode
scope_refNostringFilter by scope reference value — list mode
tagNostringFilter by tag — list mode
sourceNostringFilter by source agent or system — list mode
min_confidenceNonumberMinimum confidence threshold (0–1) — list mode
limitNonumberMaximum results (default 100, max 500) — list mode
agentRequired for retrieve modestringAgent role: analyzer, planner, developer, reviewer, retrospector — retrieve mode
issueNonumberIssue number to scope retrieval — retrieve mode
prNonumberPull request number to scope retrieval — retrieve mode
budgetNonumberToken budget for rendered markdown — retrieve mode

List workflow definitions registered for the tenant associated with the given repo, or return the full parsed definition for a specific workflow when workflow_id is given. Defaults to the latest version when version is omitted.

ArgumentRequiredTypeDescription
repoYesstringRepository in owner/name format
workflow_idNostringWorkflow identifier to fetch (e.g. colony-default); when omitted, lists all definitions
versionNonumberWorkflow version number (defaults to latest; only used when workflow_id is given)
tenant_idNostringTenant external ID for ambiguous repo names; narrows within the host-bound tenant scope and cannot select a tenant outside it

List the top flaky deterministic review checks (checks that failed, then passed on a rerun of the PR tree). Returns a markdown table (repo, check, flakes/evaluations, flake rate, last flake, quarantined) followed by the same data as JSON. For CI rows (source=ci), evaluations are first-attempt CI failures (a rerun was requested). The top-N limit covers review and CI rows together. With no repo, spans every repo in the pipeline store.

ArgumentRequiredTypeDescription
ownerNostringRepository owner; must be given together with repo
repoNostringRepository name (or owner/name)
daysNonumberLook-back window in days, 1-90 (default 14)
limitNonumberMaximum checks returned, 1-50 (default 10)
tenant_idNostringTenant external ID for ambiguous repo names; without a repo it limits results to that tenant. Narrows within the host-bound tenant scope and cannot select a tenant outside it

A check is quarantined when its flake count in the window is at or above review.flaky_quarantine_threshold (per-repo override, then global). When no config is loaded (stdio mode without a config file) or no threshold is set, quarantined is always false.

Operate the strategy loop. generate, approve, reject and revert are writes; list and get are read-only (SELECT-only, no actor needed). All honour the host-bound tenant scope. approve runs what the monitor route POST /api/strategy/:owner/:repo/snapshots/:version/approve runs: approveAndApplyStrategy, one transaction that validates, applies and activates the snapshot.

ArgumentRequiredTypeDescription
repoYesstringRepository in owner/name format
actionYesenumgenerate, approve, reject, revert, list or get
versionNonumberSnapshot version; required for approve, reject and get (INVALID_INPUT when missing)
statusNoenumlist only: filter by proposed, active, superseded, invalid or rejected
limitNonumberlist only: maximum snapshots, default 10, clamped to 1-50
editsNoobjectapprove only: { intent?, rationale?, portfolio?, creates?, retires? }, recorded as an operator-authored snapshot
reasonNostringreject only: reason recorded with the rejection (required, non-empty)
actorNostringWho is acting. Used only when the host binds no identity (McpContext.actor wins); with neither, ACTOR_REQUIRED

Success returns JSON: { "ok": true, "requested_at": "…" } for generate (a durable request; the sprint-master runs it), { "ok": true, "version": N, "status": "active" } for approve, and { "ok": true, "version": N } for reject and revert. list returns an array, newest first ([] for a repo with no snapshots), of { version, status, parent_version, charter_version, created_at, decided_at, decided_by, status_reason, intent, directive_counts: { portfolio, creates, retires } }; intent is cut to 300 characters and decided_* come from the rejection for rejected snapshots, otherwise the approval. get returns the full snapshot: version, status, parent_version, charter_version, author, created_at, intent, rationale, portfolio, creates, retires, approved_*, rejected_*, reject_reason, superseded_by, status_reason, violations, apply_error, apply_error_at, plus goal_assessments and applied_pool when present; an unknown version returns NOT_FOUND. The literal actor mcp is never recorded. The removed governed argument is refused by name: strategy tracks are never governed.

Failures return isError with a stable code at the start of the text:

CodeMeaning
NOT_FOUNDRepository (or out-of-scope repository) or snapshot not found
NOT_PROPOSEDThe snapshot is not proposed
ACTOR_REQUIREDNo host-bound actor and no actor argument
REASON_REQUIREDreject without a non-empty reason
NO_ACTIVE_CHARTERgenerate on a repo with no active charter
NO_REVERT_TARGETThe parent snapshot has no recorded applied_pool
INVALIDThe edits are invalid; nothing is written
STALE, CHARTER_CHANGEDThe parent or charter is no longer active; the snapshot is superseded
SCHEMA, GRANT_EXCEEDED, OPERATOR_TRACK, UNKNOWN_TRACK, TRACK_EXISTS, DUPLICATE_TRACK, INVALID_CRON, UNKNOWN_PIN, PROMPT_REQUIRED, PROMPT_INVALID, OUT_OF_BOUNDS, INVALID_DIRECTIVEValidation violations; the snapshot is marked invalid

A validation failure also returns structuredContent: { code, violations: [{ code, path, message }] } alongside the unchanged text, where code is the leading code of the text. A failure without violations has no structuredContent.

On a transient apply failure (anything that is not a validation violation), the transaction rolls back: no track writes land, and the snapshot stays proposed with apply_error recorded so it can be retried.


Claude Code slash commands that wrap the MCP tools in structured conversational prompts. The files live in .claude/commands/colony/ and are picked up automatically by Claude Code when the project is open. Copy them to ~/.claude/commands/colony/ for global availability.

CommandInvocationWhat it doesMCP tools used
brainstorm/colony:brainstorm [repo]Interview → estimate → file a Colony issuecolony_estimate, colony_file_issue
plan/colony:plan [repo]Decompose work into dependency-linked tasks and import as a plancolony_import_plan (dry-run preview + live import)
report/colony:report [repo] [time-window]Summary report: workers, queue, active issues, cost, findingscolony_work (views: status, list, findings)
issue-status/colony:issue-status <repo> <issue>Diagnose a specific issue: state history, block reason, recommendationscolony_work (views: diagnose, status)

Usage examples:

/colony:brainstorm RunColony/colony
/colony:plan acme/webapp
/colony:report acme/webapp 30d
/colony:issue-status acme/webapp 42
/colony:issue-status acme/webapp#42

Editor-side vs. GitHub-comment commands: These slash commands operate via the MCP server from your editor. They are distinct from GitHub-comment slash commands (/colony:retry, /colony:decompose, /colony:cancel, etc.) that control the pipeline from issue comments on GitHub.

REGISTRY_VERSION is 22.