MCP Server
MCP Server
Section titled “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.
Run Modes
Section titled “Run Modes”Local stdio (colony mcp)
Section titled “Local stdio (colony mcp)”After installing Colony’s CLI, run:
colony mcpThe 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:
npx @colony/mcpThis fetches and runs the MCP server directly; set the required env vars in the editor config.
Central HTTP (Docker Compose mcp profile)
Section titled “Central HTTP (Docker Compose mcp profile)”For shared pilot deployments, start one MCP container on the Colony VM:
docker compose --profile mcp up -d mcpBefore starting, set MCP_AUTH_TOKEN in .env:
MCP_AUTH_TOKEN=$(openssl rand -hex 32)Pilot users point their MCP clients at:
http://<vm-host>:9300/mcpwith 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.
Editor Configuration
Section titled “Editor Configuration”Claude Code
Section titled “Claude Code”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_..." } } }}Cursor
Section titled “Cursor”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_..." } } }}Environment Variables
Section titled “Environment Variables”| Variable | Required | Description |
|---|---|---|
DATABASE_URL | Yes | Postgres connection string for Colony’s pipeline store |
GITHUB_TOKEN | PAT auth only | GitHub personal access token. Not needed when config uses GitHub App auth |
MCP_TRANSPORT | No | stdio or http. Defaults to stdio |
MCP_AUTH_TOKEN | HTTP mode only | Bearer token required by the HTTP MCP endpoint |
MCP_HOST | No | HTTP bind host. Defaults to 0.0.0.0 |
MCP_PORT | No | HTTP port. Defaults to 9300 |
MCP_PATH | No | HTTP MCP path. Defaults to /mcp |
MCP_CONFIG_PATH | No | Explicit path to colony.config.yaml when not using the default search path |
COLONY_CONFIG_PATH | No | Fallback for MCP_CONFIG_PATH when that is unset |
MCP_LOG_LEVEL | No | Log level (debug, info, warn, error). Defaults to info |
Database settings
Section titled “Database settings”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_timeoutand a 60 sstatement_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. Raisedatabase.query_timeoutanddatabase.statement_timeoutfor longer queries. - TLS:
- URL carries SSL parameters (
sslmode,ssl,sslrootcert, …): the URL decides. database.sslunset and no SSL parameters in the URL: TLS stays asPGSSLMODEsays (none if unset).database.ssl: true,{}or{ verify: true }: TLS with certificate verification against the system CAs plusNODE_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.
- URL carries SSL parameters (
- Opt-outs: trust the private CA (mount it under
/colony/keys/ca-certs/*.crtor setNODE_EXTRA_CA_CERTS); setdatabase.ssl: { verify: false }; put the SSL mode in the URL (for examplesslmode=no-verifyorsslmode=disable, which also applies to every component reading that URL); or leavedatabase.sslunset so only the URL andPGSSLMODEdecide.
Tool Reference
Section titled “Tool Reference”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.
colony_work
Section titled “colony_work”Query work items and pipeline state. The view parameter selects the operation.
| Argument | Required | Type | Description |
|---|---|---|---|
view | Yes | string | status: 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 |
repo | Required for diagnose, findings | string | Repository in owner/name format. Optional for status and list (omit for a cross-repo aggregate). |
issue_number | Required for diagnose | number | Issue number — required for diagnose; optional filter for findings |
tenant_id | No | string | Tenant external ID for ambiguous repo names — status, list and findings views. Narrows within the host-bound tenant scope; cannot select a tenant outside it |
state | No | string | Filter by issue state — list view only |
workflow | No | string | Workflow id; returns only items pinned to it, and state is validated against its states — list view only |
trait | No | string | active, blocked, awaiting-human or terminal; items whose current state carries the trait in their own pinned workflow (unresolvable workflows are excluded) — list view only |
since | No | string | Start date filter (ISO 8601) — list view only |
until | No | string | End date filter (ISO 8601) — list view only |
limit | No | number | Maximum items to return — list (default 50, max 200) or findings (default 100, max 200) |
offset | No | number | Items to skip for pagination (default 0) — list view only |
cursor | No | string | Opaque 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 |
detail | No | string | summary (default) or full (adds tool results and system rows) — transcript view only |
wait_seconds | No | number | Long-poll up to this many seconds (0–25, default 0) when no entries are available — transcript view only |
change_number | No | number | The code host’s number for the item’s change — findings view only |
status | No | string | open, accepted, resolved, dismissed or superseded — findings view only |
record_kind | No | string | judgement or check_result; when omitted, only judgement rows are returned — findings view only |
check_name | No | string | Filter by check name (e.g. lint, typecheck) — findings view only |
check_outcome | No | string | Filter by check outcome (e.g. fail, pass) — findings view only |
category | No | string | Filter by finding category — findings view only |
severity | No | string | Filter 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-repohaltedandtodaySpend(below).repooptional. Withrepo, 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 }.summaryholdsrepoCount,workers,queueDepth,activeIssueCount,totalCostCurrentMonth(all totals over every repo),haltedRepos([{ repo, halted }]) andtodaySpendkeyed by tenant external id.reposlists 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.omittedReposcounts the repos left out ofrepos.tenant_iddisambiguates 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? }ornull.reasonisrepo_disabled,daily_cost_ceilingorsafestop; when several apply the precedence isrepo_disabled>daily_cost_ceiling>safestop.repo_disabled: the repo hasactive = FALSE.sinceisnull(no deactivation time is recorded) and there is noresumesAt. The no-repolisting includes only active repos, so this appears only whenrepois named.daily_cost_ceiling: today’s persisted tenant spend has reached the effective cap (max_daily_usdlessbudget_headroom_pct).resumesAtis the next UTC midnight;sinceis 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 readnullslightly 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 isdraining(a health-endpoint drain looks the same).sinceis approximate (the earliestupdated_atof those workers, which heartbeats refresh); noresumesAt. A fully stopped pipeline shows as zero workers withhalted: null.
todaySpend—{ spentUsd, capUsd, effectiveCapUsd }for the current UTC day, whether or not halted, ornullwhenmax_daily_usdis 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.repooptional for cross-repo queries.tenant_iddisambiguates a repo name that exists under more than one tenant (withoutrepoit limits the list to that tenant); it narrows within the host-bound tenant scope and cannot select a tenant outside it. Withoutworkflow,stateis 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. Withoutrepothis covers every repo in the tenant scope (narrowed bytenant_id). An undeclared state is rejected with an error listing the sorted union. Withworkflow,stateis 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. Requiresrepoandissue_number. After the why report,diagnoseappends five MCP-only sections, in this order. A read that fails rendersunavailable (<message>)for its section only; an empty section rendersnone.- Linked change — change number and URL plus each check’s
name — conclusion(pendingwhen not yet concluded). Resolved from thedependabot-prlink on Dependabot workflows, the open PR on the item’s ownepic/<n>branch for epics, otherwise the open PR forcolony/issue-<n>. Rendersunavailable (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 notprose. - 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 byAnswer with colony_act action=pick.
- Linked change — change number and URL plus each check’s
findings— list agent findings for a repo or issue: observations, risks, and review findings. Requiresrepo. Deterministic check results are included only whenrecord_kind: check_resultis passed.transcript— a read-only live tail of an item’s agent turns interleaved with its state transitions. Requiresrepoandissue_number;limitis 1–200 (default 50). Returns{entries, next_cursor, state, is_terminal}; passnext_cursorback ascursorto continue.summaryreturns assistant text (cut to 2,000 characters) and tool calls (input cut to 200);fulladds 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, fromworkspace.secret_env_varsin the config the MCP server was started with) are redacted as[redacted:NAME], and cut or stored-truncated rows carrytruncated: true. Withwait_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 throughrepoSecretsResolver(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.
colony_file_issue
Section titled “colony_file_issue”File and enqueue an issue with Colony-aware formatting. Reads .colony/conventions.md from the target repo, applies appropriate labels, and validates scope.
| Argument | Required | Type | Description |
|---|---|---|---|
repo | Yes | string | Repository in owner/name format |
title | Yes | string | Issue title |
body | Yes | string | Issue body in markdown |
as_epic | No | boolean | true 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_hint | No | small | medium | large | Complexity hint for the analyzer |
constraints | No | string[] | Standing constraints to record on the filed item before work starts (at most 20, each 1-2000 characters) |
assignees | No | string[] | 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.
colony_estimate
Section titled “colony_estimate”Cost and time estimate before filing. Takes an issue description and repo, returns estimated cost (USD), confidence level, and likely outcome.
| Argument | Required | Type | Description |
|---|---|---|---|
repo | Yes | string | Repository in owner/name format |
description | Yes | string | Issue description to estimate |
complexity | No | small | medium | large | Optional complexity tier filter for percentile computation |
tenant_id | No | string | Tenant 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.
colony_review
Section titled “colony_review”Get Colony’s review verdict on a PR. Returns the reviewer’s structured analysis: verdict, findings, and confidence.
| Argument | Required | Type | Description |
|---|---|---|---|
repo | Yes | string | Repository in owner/name format |
change_number | Yes | number | The code host’s number for the change |
tenant_id | No | string | Tenant external ID for ambiguous repo names; narrows within the host-bound tenant scope and cannot select a tenant outside it |
colony_act
Section titled “colony_act”Perform an operator action on a work item. The action parameter selects the operation.
| Argument | Required | Type | Description |
|---|---|---|---|
repo | Yes | string | Repository in owner/name format |
issue_number | Yes | number | Issue number to act on |
action | Yes | string | Action to perform — see table below |
child_number | No | number | Subtask issue number — required for release |
confirm | No | boolean | Set true to proceed with an action that requires confirmation — see below |
actor | No | string | release: 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_sha | No | string | invoke 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 |
intent | No | string | Declared action intent — required for invoke; a slug of lowercase letters, digits and hyphens |
choice | No | string | Menu 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_id | No | string | Menu round id; pick is refused unless it is the open round |
tenant_id | No | string | Tenant 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 |
text | No | string | Operator 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_id | No | integer or all | Constraint id, or all to remove every standing constraint — required for unconstrain |
request_id | No | string | Idempotency 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) |
size | No | string | Complexity override for retry: small, medium or large (case-insensitive). Any other value is an isError result and nothing is written |
level | No | string | high, normal or low — required for priority; optional for enqueue |
target_state | No | string | State to move the item to — required for state |
reason | No | string | Non-blank reason, persisted verbatim on the transition record — required for state |
Available actions:
| Action | Description | Availability |
|---|---|---|
pause | Pause processing, stopping any run in progress; the issue can be resumed later, and resuming restarts that step. Requires confirm: true. | Always |
resume | Resume a paused issue. | Always |
cancel | Cancel the work item and close it. Requires confirm: true. | Always |
retry | The 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 |
reimplement | Discard 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 |
adopt | Adopt 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 |
followup | File 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 |
reanalyze | Re-run analysis with new context. | Workflow-declared |
reopen | Reopen a completed issue; sends it back to intake. | Workflow-declared |
release | Release 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 |
invoke | Run any operator action the item’s workflow declares, selected by intent. Requires intent and confirm: true. | Workflow-declared |
answer | Answer the outstanding clarification question. Requires text and request_id. See below. | Always |
pick | Pick 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 |
constrain | Record a standing constraint, as /colony:constrain does. Tracked items only. Requires text and request_id. | Always |
constraints | List 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 |
unconstrain | Remove 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 |
feedback | Route rework feedback, as /colony:feedback does. Requires text and request_id. | Always |
review | Send the item to its workflow’s review state (in-review on colony-default), as /colony:review does. Requires request_id. | Always |
priority | Set the manual priority, as /colony:priority does. Requires level and request_id. | Always |
skip-planning | Skip planning, as /colony:skip-planning does. Requires request_id. | Always |
decompose | Send the item to planning as an epic, as /colony:decompose does. Requires request_id and confirm: true. | Always |
state | Move the item to a target state, as the dashboard POST …/transition does. Requires target_state, reason, request_id and confirm: true. | Always |
unblock | Unblock a blocked item, as the dashboard POST …/unblock does. Requires request_id. | Always |
enqueue | Seed 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:
intentis missing or is not a slug;intentisretry,pause,resume,cancel,release,review,priority,skip-planning,decompose,stateorunblock, 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-prand 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.
Accepting an epic
Section titled “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:
| Code | Meaning |
|---|---|
wrong_state | Not in human-review-ready |
paused | The item is paused |
not_epic | Not an epic |
epic_subtask | A subtask with an epic branch that isn’t its own |
nothing_to_accept | No current judgement ask, or a tooling escalation |
already_decided | Reject, code-host approval or an earlier Accept won |
head_moved | The 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_unavailable | No 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.
answeranswers 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. Ifanswerfails after posting, the comment is removed and the claim released, so a retry with a newrequest_idleaves 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.
constrainrecords a standing constraint exactly as/colony:constraindoes, on tracked items only. Seeding an untracked item stays a slash-command affordance.unconstrainremoves one standing constraint byconstraint_id(or all of them withconstraint_id=all; the string is case-sensitive), which is stable (unlike the ordinal that/colony:unconstrain <n>takes). Theconstrainandunconstrainresults carryconstraints(id,kind,body, oldest first), so a client can learn the id it needs.feedbackroutes rework feedback exactly as/colony:feedbackdoes: the clarification, transition or mailbox route, the same refusals (including Dependabot), and the same acknowledgement comment.retryperforms exactly what/colony:retry [small|medium|large]performs: the failure-counter reset and marker comment, the model-tier escalation, the status eventoperator retry(oroperator retry: <size>) withactoras its actor, and the routing (re-enqueue the current executor, or move a blocked item to its resolved retry target). It takes notext.request_idis optional: when omitted MCP generatesretry:<uuid>, so each call is a fresh retry, and the result carries the id used so apendingresult 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.
| Action | Twin | Extra inputs | confirm |
|---|---|---|---|
review | /colony:review | none | false |
priority | /colony:priority | level (high|normal|low) | false |
skip-planning | /colony:skip-planning | none | false |
decompose | /colony:decompose | none | true |
state | Dashboard POST …/transition | target_state, reason | true |
unblock | Dashboard POST …/unblock | none | false |
Refusals (an isError result, no change to the item):
reviewis refused from any state where/colony:reviewrefuses (see slash-commands.md), including workflows with no review state, with the same per-state reason and comment as/colony:review.decomposeis refused with reasonillegal_transition, and no label change, when the item’s workflow does not allow a transition toplanning. The check runs before any label write;/colony:decomposebehaves the same.stateis refused whentarget_stateis 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 thereasonis stored verbatim and anoperator state: <target>status event is written.unblockis refused, with no write, when the item’s current state is not a blocked state. Useretryfor an active item that still carries a stale blocked flag. The dashboardPOST …/unblockreturns 409NOT_BLOCKEDfor 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:
| Result | Meaning |
|---|---|
completed | The command ran. The result carries the route or the resume state (for retry, the resulting state). |
refused | An 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. |
failed | An isError result with the error, including interrupted. |
pending | The 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-command equivalents
Section titled “Slash-command equivalents”| Slash command | colony_act |
|---|---|
/colony:enqueue | enqueue |
/colony:adopt | adopt |
/colony:followup | followup |
/colony:unconstrain | constraints (bare form lists the standing constraints) |
/colony:unconstrain all | unconstrain with constraint_id=all |
/colony:reimplement | reimplement |
| SI candidate checkbox | pick (choice=option:<n> or roll-again) |
colony_tracks
Section titled “colony_tracks”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).
| Argument | Required | Type | Description |
|---|---|---|---|
repo | Yes | string | Repository in owner/name format |
tenant_id | No | string | Tenant external ID for ambiguous repo names; narrows within the host-bound tenant scope and cannot select a tenant outside it |
colony_import_plan
Section titled “colony_import_plan”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.
| Argument | Required | Type | Description |
|---|---|---|---|
repo | Yes | string | Repository in owner/name format |
tasks | Yes | array | Structured task array — see schema below |
dry_run | No | boolean | Preview classification without creating issues |
as_epic | No | boolean | Defaults to true when the plan has more than one non-manual task; false suppresses the epic, true forces one |
epic_title | No | string | Title for the epic parent issue (used when an epic parent is created) |
epic_body | No | string | Body for the epic parent issue (used when an epic parent is created) |
initial_state | No | string | Entry 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 |
constraints | No | string[] | Standing constraints to record on every created item (at most 20, each 1-2000 characters) |
assignees | No | string[] | 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:
| Field | Required | Type | Description |
|---|---|---|---|
key | Yes | string | Short unique identifier, no spaces (e.g. auth-api, migrate-db) |
title | Yes | string | Concise action phrase ≤ 72 chars, starts with a verb |
body | No | string | Markdown issue body — background, acceptance criteria, constraints |
dependsOn | No | string[] | Array of key values this task depends on (omit or [] for root tasks) |
needsHuman | No | boolean | true if the task requires human intervention before Colony can proceed |
crossRepo | No | string | "owner/other-repo" if the task belongs to a different repository |
assignees | No | string[] | Code-host logins for this task; overrides the plan-level assignees |
colony_intelligence
Section titled “colony_intelligence”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.
| Argument | Required | Type | Description |
|---|---|---|---|
repo | Yes | string | Repository in owner/name format |
mode | No | string | list (default): filtered intelligence items; retrieve: retrieval debug for the given agent role |
tenant_id | No | string | Tenant external ID for ambiguous repo names; narrows within the host-bound tenant scope and cannot select a tenant outside it |
kind | No | string | Filter by kind (e.g. architecture, invariant, failure_pattern, design_decision) — list mode |
status | No | string | Filter by status: candidate, observed, proposed, approved, dismissed, superseded — list mode |
scope_kind | No | string | Filter by scope kind (e.g. repo, package, path, file, symbol) — list mode |
scope_ref | No | string | Filter by scope reference value — list mode |
tag | No | string | Filter by tag — list mode |
source | No | string | Filter by source agent or system — list mode |
min_confidence | No | number | Minimum confidence threshold (0–1) — list mode |
limit | No | number | Maximum results (default 100, max 500) — list mode |
agent | Required for retrieve mode | string | Agent role: analyzer, planner, developer, reviewer, retrospector — retrieve mode |
issue | No | number | Issue number to scope retrieval — retrieve mode |
pr | No | number | Pull request number to scope retrieval — retrieve mode |
budget | No | number | Token budget for rendered markdown — retrieve mode |
colony_workflows
Section titled “colony_workflows”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.
| Argument | Required | Type | Description |
|---|---|---|---|
repo | Yes | string | Repository in owner/name format |
workflow_id | No | string | Workflow identifier to fetch (e.g. colony-default); when omitted, lists all definitions |
version | No | number | Workflow version number (defaults to latest; only used when workflow_id is given) |
tenant_id | No | string | Tenant external ID for ambiguous repo names; narrows within the host-bound tenant scope and cannot select a tenant outside it |
colony_flaky_checks
Section titled “colony_flaky_checks”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.
| Argument | Required | Type | Description |
|---|---|---|---|
owner | No | string | Repository owner; must be given together with repo |
repo | No | string | Repository name (or owner/name) |
days | No | number | Look-back window in days, 1-90 (default 14) |
limit | No | number | Maximum checks returned, 1-50 (default 10) |
tenant_id | No | string | Tenant 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.
colony_strategy
Section titled “colony_strategy”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.
| Argument | Required | Type | Description |
|---|---|---|---|
repo | Yes | string | Repository in owner/name format |
action | Yes | enum | generate, approve, reject, revert, list or get |
version | No | number | Snapshot version; required for approve, reject and get (INVALID_INPUT when missing) |
status | No | enum | list only: filter by proposed, active, superseded, invalid or rejected |
limit | No | number | list only: maximum snapshots, default 10, clamped to 1-50 |
edits | No | object | approve only: { intent?, rationale?, portfolio?, creates?, retires? }, recorded as an operator-authored snapshot |
reason | No | string | reject only: reason recorded with the rejection (required, non-empty) |
actor | No | string | Who 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:
| Code | Meaning |
|---|---|
NOT_FOUND | Repository (or out-of-scope repository) or snapshot not found |
NOT_PROPOSED | The snapshot is not proposed |
ACTOR_REQUIRED | No host-bound actor and no actor argument |
REASON_REQUIRED | reject without a non-empty reason |
NO_ACTIVE_CHARTER | generate on a repo with no active charter |
NO_REVERT_TARGET | The parent snapshot has no recorded applied_pool |
INVALID | The edits are invalid; nothing is written |
STALE, CHARTER_CHANGED | The 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_DIRECTIVE | Validation 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.
Slash Command Pack
Section titled “Slash Command Pack”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.
| Command | Invocation | What it does | MCP tools used |
|---|---|---|---|
brainstorm | /colony:brainstorm [repo] | Interview → estimate → file a Colony issue | colony_estimate, colony_file_issue |
plan | /colony:plan [repo] | Decompose work into dependency-linked tasks and import as a plan | colony_import_plan (dry-run preview + live import) |
report | /colony:report [repo] [time-window] | Summary report: workers, queue, active issues, cost, findings | colony_work (views: status, list, findings) |
issue-status | /colony:issue-status <repo> <issue> | Diagnose a specific issue: state history, block reason, recommendations | colony_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#42Editor-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.