Skip to content

Getting Started with Colony

Go from git clone to watching Colony process its first issue in under 30 minutes.

Audience: A senior engineer comfortable with TypeScript, GitHub, and containers evaluating Colony on a test repo.

This is the single starting point for new users. Everything you need is on this page. Reference docs are linked for deeper dives but are never required reading:

  • Installation Guide — Prerequisites deep-dive (platform-specific install commands, resource sizing)
  • Environment Variables — Canonical table of every variable with required-by, deployment mode, and generation examples
  • Configuration Reference — Progressive-disclosure guide: Essential fields (Tier 1), recommended tuning (Tier 2), and advanced options (Tier 3)
  • First Issue Tutorial — Extended guide for issue scoping, analyzer plans, slash commands, and gotchas
  • Failure Modes Guide — Common failure modes with symptoms, diagnosis, and fixes

CLI note: The bootstrap script (./scripts/setup.sh) links colony as a global command so every example below works as written. If you bootstrap manually instead, colony won’t be on your PATH — substitute node packages/cli/dist/index.js in each command, or run npm link inside packages/cli yourself.


The fastest path. The bootstrap script installs deps, builds, links the colony CLI globally, and installs the Claude Code CLI in one go. Then the interactive wizard takes over.

Prerequisite: Node 22+. On Linux, install via mise (curl https://mise.run | sh && exec $SHELL && mise use -g node@22) or nvm to avoid EACCES on global installs. macOS Homebrew Node works too. See Prerequisites for details.

Platform support: On Windows, run everything inside WSL2 — see Windows / WSL2.

Terminal window
git clone https://github.com/RunColony/colony.git
cd colony
./scripts/setup.sh
# Interactive wizard: prompts for API keys, config, database, and starts agents
colony quickstart

./scripts/setup.sh is idempotent and handles every install gotcha — including configuring a user-owned npm prefix on Linux when system Node has a root-owned global, and installing @anthropic-ai/claude-code (required by Colony workers). If the script updates your shell rc (~/.bashrc / ~/.zshrc), it will print a source command to refresh PATH before running colony quickstart.

Skipping the bootstrap script means handling these yourself: npm install && npm run build && (cd packages/cli && npm link) && npm install -g @anthropic-ai/claude-code. On Linux with system Node, expect EACCES errors unless you’ve configured ~/.npm-global first (or installed Node via mise/nvm).

The wizard guides you through six phases:

🚀 Colony Quickstart
This wizard will guide you through setting up Colony step by step.
── Step 1: Environment
Validate prerequisites and API keys; choose deployment mode (Docker Compose, Apple Container, or Native)
── Step 2: Repository
Configure your target repository
── Step 3: Database
Set up the Colony database
── Step 4: Cost Preview
Select Claude models with cost tradeoff explanations; set per-issue and daily cost limits
── Step 5: Launch
Write config, initialize repo, and start agents
── Step 6: First Issue
Create a test issue to see Colony in action

If the wizard is interrupted (Ctrl-C, terminal closed), re-running colony quickstart will detect the previous session and ask whether to resume. Partial progress within an interrupted phase is preserved — e.g., if you Ctrl-C while answering the Anthropic key prompt, the wizard remembers your earlier choices (deployment mode, GitHub auth method, GitHub App ID/Installation ID, Node/git/Claude CLI checks) and only re-asks the questions that hadn’t been answered yet.

Credentials are not saved in the wizard’s resume state file for security (this is separate from .env, which the wizard writes for native and docker-compose). On resume, you will be re-prompted for any token that isn’t already in your environment:

  • GITHUB_TOKEN — re-export before running, or re-paste at the prompt
  • ANTHROPIC_API_KEY or CLAUDE_CODE_OAUTH_TOKEN — same. If you paste an sk-ant-oat... token, the wizard routes it to CLAUDE_CODE_OAUTH_TOKEN and writes auth_mode: oauth-token in your config
  • GitHub App private key path is remembered, but the key itself is read fresh each run from the path you provided

If quickstart completes successfully, skip to Step 6: Process Your First Issue.

If you prefer fine-grained control over each step, follow the manual setup below.


Platform support: On Windows, run everything inside WSL2 — see Windows / WSL2.

Before you begin:

  • Node.js 22+ — node --version should print v22.x or higher. Recommended: install via mise (Linux/macOS) so global installs work without sudo.

  • Git — git --version

  • Anthropic credentials — one of:

    • API key (sk-ant-api...) from console.anthropic.com — pay-as-you-go billing
    • OAuth token (sk-ant-oat...) from claude setup-token — uses your Claude Pro/Max subscription

    The quickstart wizard auto-detects which form you paste and configures Colony accordingly.

  • GitHub account with a test repository (public or private)

Claude Code CLI: No manual step required. ./scripts/setup.sh installs @anthropic-ai/claude-code for you as part of the bootstrap.

Recommended: install Node via mise (Linux/macOS)

mise installs Node into your home directory, which makes npm install -g and npm link work without sudo and without the EACCES errors you’ll hit with apt/yum-installed Node on Linux.

Terminal window
# Install mise
curl https://mise.run | sh
# Restart your shell or source the rc mise updated (~/.bashrc, ~/.zshrc, etc.)
exec $SHELL
# Install Node 22 globally
mise use -g node@22
# Verify
node --version # should print v22.x or higher

nvm works equivalently if you prefer (nvm install 22 && nvm use 22). ./scripts/setup.sh detects mise / nvm / asdf / volta and skips the npm-prefix workaround when present.

Alternative: system Node (with caveats)

If you must use a system-installed Node (apt, brew, etc.), ./scripts/setup.sh will detect that the global npm prefix is not writable and automatically reconfigure npm to use ~/.npm-global so subsequent global installs don’t EACCES.

Terminal window
# macOS (Homebrew)
brew install node@22
# Ubuntu/Debian — but mise is strongly preferred
sudo apt install nodejs npm
# Other platforms — see https://nodejs.org

Warning: If you have previously run sudo npm install -g <anything>, you may have root-owned files inside ~/.npm-global or /usr/local/lib/node_modules that will EACCES on subsequent global installs. ./scripts/setup.sh detects this and prints fix instructions.

Other prerequisites

Git

Terminal window
git --version

If not installed: xcode-select --install (macOS) or your platform’s package manager.

Container runtime setup (optional)

Colony can run as containers (Docker or Apple Container) or as native Node.js processes. Containers are recommended for production; native is fine for evaluation.

Docker Desktop

Terminal window
# macOS
brew install --cask docker
# Linux — see https://docs.docker.com/engine/install/

Apple Container (macOS only)

Requires macOS 15+ and Apple Silicon.

Terminal window
brew install container
container system start
container system property set build.rosetta false

Resource recommendations

DeploymentWorkersMemoryCPUsDisk
Single repo (eval)18 GB450 GB
Single repo (prod)2-316 GB8100 GB
Multi-repo3+32 GB16200 GB

For the full prerequisites reference, see Installation Guide.

Next: Choose your deployment mode.


Colony’s deployment mode is the single configuration decision that all subsequent steps branch on. Pick one and record it in your config now — the database step, environment variables, and start command all follow from this choice automatically.

ModeBest forDatabaseHow agents run
Docker ComposeFirst-time users, productionBundled (included in compose)docker compose up -d
Apple ContainermacOS with Apple SiliconExternal (Neon or local Docker)./scripts/colony-container.sh up -d
NativeQuick local evaluationExternal (Neon or local Docker)colony start

Recommendation: Use Docker Compose for your first setup — it bundles Postgres and requires the least configuration. Use Native if you want the simplest possible evaluation without containers.

Set your mode in colony.config.yaml (you’ll create this file in Step 4, but note the value now):

deployment:
mode: native # change to docker-compose or apple-container if applicable

Both colony quickstart and colony init --generate ask for your deployment mode and write it to colony.config.yaml automatically — you don’t need this manual step if you use either wizard.

Next: Set up your database.


Colony stores pipeline state in Postgres.

docker-compose mode: Postgres is bundled in the Compose stack — nothing to set up here. Jump to Step 4.

native or apple-container mode: you need an external Postgres instance. Pick one:

Option A: Neon (free hosted Postgres)

  1. Sign up at neon.tech — free tier is sufficient.
  2. Create a project and database.
  3. Copy the connection string (includes ?sslmode=require).
Terminal window
export DATABASE_URL="postgresql://user:pass@ep-xxx.us-east-2.aws.neon.tech/colony?sslmode=require"

Option B: Local Docker Postgres

Terminal window
docker run -d --name colony-pg -e POSTGRES_USER=colony -e POSTGRES_PASSWORD=colony -e POSTGRES_DB=colony -p 5432:5432 pgvector/pgvector:pg17
export DATABASE_URL="postgresql://colony:colony@localhost:5432/colony"

Migrations run automatically when agents start — no manual migration step needed.

Next: Configure Colony.


Terminal window
git clone https://github.com/RunColony/colony.git
cd colony
./scripts/setup.sh

./scripts/setup.sh installs dependencies, builds all packages, configures a user-owned npm prefix if needed (Linux apt-installed Node ships with a root-owned global prefix that EACCESes on npm link), and links the colony CLI globally.

If your shell rc was updated, the script will print a source command to refresh PATH in the current shell.

If you want to run the steps yourself: npm install && npm run build && (cd packages/cli && npm link). On Linux you will likely hit EACCES on the final step — either re-run with the bootstrap script or first configure a user prefix: mkdir -p ~/.npm-global && npm config set prefix ~/.npm-global and add ~/.npm-global/bin to your PATH.

Colony needs access to your GitHub repository. Pick one auth method — PAT and GitHub App are mutually exclusive in the config.

Personal Access Token (PAT) — quickest for evaluation

  1. Go to github.com/settings/tokens.
  2. Choose Generate new token (classic) or Generate new token → Fine-grained. Either type works; the table below shows what to grant for each.
  3. Configure scopes / permissions:
Token typeRequired permissions
Classic PATEnable the repo scope (covers everything Colony needs)
Fine-grained PATRepository access: select the target repo.
Permissions: see the table below

Fine-grained PAT permissions:

Permission (fine-grained)AccessWhat breaks without it
ContentsRead & writeCannot clone, push branches, or open PRs
IssuesRead & writeCannot read issues, post comments, or manage labels
Pull requestsRead & writeCannot create, review, or merge PRs
MetadataReadGranted automatically by GitHub
AdministrationRead & writeOptional. Only needed for the branch-protection ruleset colony init creates; without it init skips branch protection
ChecksReadCI-gated auto-merge cannot read check runs
Commit statusesReadCI-gated auto-merge cannot read commit statuses
ActionsReadCI-gated auto-merge cannot read workflow runs
Dependabot alertsReadOptional. colony check warns, and security-PR prioritisation is unavailable

For a classic PAT, the repo scope covers all of the above; the Administration permission corresponds to the repo admin role.

Limitations of PAT auth:

  • GitHub only allows GitHub Apps to create check runs, so the reviewer’s colony check run always fails under a PAT. It is caught and logged as Could not post check run; this is expected.
  • A PR author cannot APPROVE or REQUEST_CHANGES on their own PR, so formal PR reviews fail when the same PAT both opens and reviews PRs.

For full functionality, use a GitHub App — see github-app-setup.md.

  1. Set an expiration that matches your evaluation window.
  2. Copy the token immediately — GitHub only shows it once.
  3. Export it as GITHUB_TOKEN (or let colony quickstart prompt for it):
Terminal window
export GITHUB_TOKEN=ghp_your_token_here

PATs are tied to your personal account, so all Colony activity appears as you, and rate limits are lower than a GitHub App. Fine for evaluation; switch to App auth before going to production.

GitHub App — recommended for production

Provides fine-grained permissions, higher rate limits, and bot-attributed activity. See the GitHub App Setup Guide for step-by-step instructions (creating the App, generating a private key, finding the Installation ID). For fully autonomous merging, see dual-app setup.

When colony quickstart asks “GitHub authentication method”, choose GitHub App and have these ready: App ID, Installation ID, and the path to the .pem private key.

Alternatively, copy the annotated example config and edit it directly:

Terminal window
cp colony.config.example.yaml colony.config.yaml

Every required field is marked with a # CHANGE THIS: comment. This is the fastest path if you prefer editing a file over an interactive wizard.

Or use the interactive wizard:

Terminal window
colony init --generate

This prompts for deployment mode, your repo, auth method, database URL, optional local clone path (for stack auto-detection — workers clone fresh inside containers at runtime), review checks, and Claude model preference. It writes colony.config.yaml with a deployment: block already set.

Non-main default branches: If your repo’s default branch is master, develop, or anything other than main, you must set workspace.branch in colony.config.yaml. colony init --generate detects this automatically when GITHUB_TOKEN is already exported and writes workspace.branch for you — otherwise add it manually before running colony init.

Docker Compose mode: the target repository lives entirely inside containers. Workers clone it fresh at startup, and singleton agents (sprint-master, monitor, webhook-receiver) operate via the GitHub API + Postgres without needing on-disk repo access. The wizard offers an optional “Local clone path” prompt only so it can auto-detect your project’s tech stack and review commands — leave it empty if you’d rather skip detection and edit colony.config.yaml manually.

Native mode (no containers) still requires a local clone — Colony processes run on the host and operate directly on that clone.

For the essential fields you must set, see Tier 1: Essential Configuration. For all fields, see the full Configuration Reference.

Terminal window
export GITHUB_TOKEN=ghp_your_token_here
# Pick ONE of these — quickstart auto-detects which form was pasted:
export ANTHROPIC_API_KEY=sk-ant-api_your_key_here # API key (console.anthropic.com)
# OR
export CLAUDE_CODE_OAUTH_TOKEN=sk-ant-oat_your_token_here # OAuth token (`claude setup-token`)
# Using an AI gateway (TrueFoundry, LiteLLM, etc.)? ANTHROPIC_API_KEY is not required — see configuration.md#claudegatewayconfig
# native / apple-container mode only — docker-compose mode provides Postgres automatically:
export DATABASE_URL=postgresql://colony:colony@localhost:5432/colony

Docker deployments: Before colony init, copy .env.example to .env (cp .env.example .env) and edit it — set GITHUB_TOKEN and ANTHROPIC_API_KEY (or your gateway auth token — see configuration.md#claudegatewayconfig) there instead of exporting shell variables. Host commands such as colony init and colony check read this file.

OAuth tokens (sk-ant-oat...) use your Claude Pro/Max subscription instead of pay-as-you-go API credits. Generate one with claude setup-token. When you use one, your colony.config.yaml will include claude.auth_mode: oauth-token and claude.oauth_token_env: CLAUDE_CODE_OAUTH_TOKEN.

Next: Initialize your repo.


This creates Colony’s pipeline labels and branch protection on GitHub. Requires a colony.config.yaml already created in step 4 — running this before generating config produces a descriptive error with remediation options.

Non-main default branches: colony init creates a branch protection ruleset targeting workspace.branch (which defaults to main). If your repo’s default branch is not main, set workspace.branch in colony.config.yaml before running colony init — otherwise branch protection will target a branch that may not exist.

Terminal window
colony init -r your-org/your-repo

Expected output:

Initializing Colony for your-org/your-repo...
✓ Repository access validated
✓ XX pipeline labels created/verified
✓ Flag labels created/verified
✓ Branch protection ruleset configured

Docker Compose mode: colony init only creates pipeline labels and branch protection on GitHub — it does not write any local files. Workers clone and operate on the target repo inside their containers. If you see a “Docker Compose mode detected” line in the output, this is expected and correct.

Docker Compose mode — credential split: Containers receive .env via Docker Compose, and host-run commands like colony init and colony check read the same file automatically — from the directory holding colony.config.yaml, then from the current directory. Variables already exported in your shell take precedence, and unedited placeholder values from .env.example (such as ghp_your_token_here) are ignored. If a command reports GITHUB_TOKEN in <path>/.env is still the placeholder value, replace it with a real token.

Terminal window
colony check

For docker-compose or apple-container mode, pass --docker to run container-aware checks (compose health, container DB connectivity, mounted config) instead of host-local equivalents:

Terminal window
colony check --docker

Before docker compose up: For docker-compose mode, colony check --docker run before the containers exist validates config, credentials and the repository, and skips the in-container checks (config mount, DB connectivity, COLONY_REPO) with a single warning. That warning is expected and does not fail the check; re-run colony check --docker after docker compose up -d to run them.

Fix any failures before starting — misconfigured review checks are the most common cause of wasted API credits on first run. In --docker mode, colony check fetches package.json from the target repo via the GitHub API and warns if configured review.checks reference npm scripts that don’t exist, catching the most common cause of dev/review loops before agents start. Common issues:

ErrorFix
Cannot access your-org/your-repoCheck token has repo scope and repo name is correct
Claude CLI not foundRe-run ./scripts/setup.sh (it installs claude-code)
DATABASE_URL not setExport the connection string or use Docker Compose
ANTHROPIC_API_KEY / GITHUB_TOKEN placeholder or missingRun colony check --docker — it detects unedited .env.example placeholder values and missing keys before containers start (it skips the in-container checks until the containers are running)

Run the command that matches the deployment.mode you set in Step 2:

docker-compose:

Terminal window
# .env was copied and edited before `colony init` (see Step 4 → Set environment variables)
docker compose build
docker compose up -d
# Verify:
docker compose ps
# All services should show "running (healthy)"
# Re-run the check now that the containers are up, to run the in-container checks:
colony check --docker

apple-container:

Terminal window
./scripts/colony-container.sh build
./scripts/colony-container.sh up -d
# Verify:
./scripts/colony-container.sh health

native:

Terminal window
colony start
# Verify:
colony status

For native and docker-compose deployments, the quickstart wizard writes your credentials to .env in the Colony directory. This file is loaded automatically by colony start, Docker Compose, and host commands such as colony check. Add .env to your .gitignore to avoid committing secrets.

Health check endpoints (all deployment modes):

Terminal window
curl -sf http://localhost:9100/health # sprint-master
curl -sf http://localhost:9200/health # worker
curl -sf http://localhost:9106/health # monitor + dashboard

Dashboard access control: The monitor dashboard (port 9106) exposes control actions — retry, cancel, pause, and transition issues. By default it has no authentication. On a shared host, bind the port to localhost only rather than publishing it to all interfaces. To enable dashboard login (session-based for the browser, HTTP Basic Auth as a fallback for programmatic/CLI clients), set agents.monitor.auth.password_env: COLONY_DASHBOARD_PASSWORD in your config and export COLONY_DASHBOARD_PASSWORD in your environment. See the dashboard documentation for details. colony check will warn you if the dashboard is reachable without auth.

Webhooks are optional. Colony works out of the box using polling (Sprint Master checks GitHub every 30 seconds). Webhooks provide near-instant response but aren’t needed for evaluation, except for slash commands (/colony:retry etc.), which are only delivered through the webhook receiver; without it, use the dashboard or the MCP colony_act tool.

Docker Compose: webhook-receiver is not started by default. To enable it, run docker compose --profile webhook up -d and set webhook.enabled: true in your config. See Webhook Setup for full setup instructions.

Next: Process your first issue.


Tips for writing a well-scoped first issue

Colony works best on issues that are small, self-contained, and clearly described. For your first issue, pick something that:

  • Has a single responsibility. One feature, one bug fix, or one refactor — not a combination.
  • Has clear acceptance criteria. Describe what “done” looks like so the analyzer can write a concrete plan.
  • Doesn’t require secrets or external services. Colony’s developer agent runs in an isolated worktree. It can read and write code, run build/test/lint commands, and interact with the local filesystem — but it cannot access external APIs, databases, or secret stores during implementation.
  • Touches a small number of files. Fewer than 5–10 files is ideal for a first run. Large cross-cutting changes are better handled after you’re comfortable with the pipeline.

Size guidance: A good first issue changes 1–3 files and under 200 lines total. Larger changes are more likely to hit the turn limit or require re-implementation cycles before reaching human-review-ready.

Example issue

Title: Add a greeting utility function

Body:

Add a `greet(name: string): string` function to `src/utils.ts` that returns
`Hello, {name}!`.
Acceptance criteria:
- Function is exported from `src/utils.ts`
- Returns the greeting string with the provided name
- Unit test in `src/__tests__/utils.test.ts` covers the happy path

What to avoid for a first issue

  • Vague descriptions (“improve the API” or “refactor the codebase”)
  • Issues requiring environment variables or API keys at runtime
  • Issues that depend on unreleased changes from other branches
  • Large epics — save those for after you understand the pipeline

On your test repo, create a GitHub issue:

  • Title: Add a greeting utility function

  • Body:

    Add a `greet(name: string): string` function to `src/utils.ts` that returns
    `Hello, {name}!`.
    Acceptance criteria:
    - Function is exported from `src/utils.ts`
    - Returns the greeting string with the provided name
    - Unit test in `src/__tests__/utils.test.ts` covers the happy path
  • Label: colony:enqueue

Adjust the file path and test location to your repo’s language and layout (e.g. lib/utils.rb + test/utils_test.rb for Ruby, utils.py + tests/test_utils.py for Python); see .colony/conventions.md for teaching Colony your repo’s layout.

The colony:enqueue label tells Sprint Master to pick up this issue. Colony’s default intake_mode: tagged setting means only issues explicitly labeled colony:enqueue enter the pipeline — this gives you full control over which issues Colony processes.

To add the label in the GitHub UI: open your issue, click Labels in the right sidebar, search for colony:enqueue, and select it. The label is applied immediately.

Note: The colony:enqueue label is created automatically when you run colony init on your repo. If you don’t see it, re-run colony init -r owner/repo. To automatically process all new issues without labeling, set intake_mode: all under agents.sprint_master in your config.

Timing expectation: Sprint Master polls every 30 seconds. Your issue may take up to 60 seconds to be picked up. Run colony status (or docker exec colony-sprint-master colony status) to verify agents are running. If nothing happens after 2 minutes, check logs with colony logs or docker compose logs -f.

Open the dashboard at http://localhost:9106 for real-time pipeline status. See the Monitor Dashboard guide for a full tab and control reference. The issue progresses through these states (visible as GitHub labels):

colony:enqueue → colony:new → colony:analyzing → colony:ready-for-dev → colony:in-review → colony:merge-pending → colony:human-review-ready → colony:done
StageLabelWhat it means
newcolony:newColony has detected this issue and will start analyzing it shortly.
analyzingcolony:analyzingColony is reading the codebase to understand scope and context.
ready-for-devcolony:ready-for-devPlanning is complete; Colony is queued to start writing code.
in-reviewcolony:in-reviewA pull request is open and under review.
merge-pendingcolony:merge-pendingReview passed — Colony will merge automatically once CI completes.
human-review-readycolony:human-review-readyA PR is open and waiting for your approval before Colony can merge.
donecolony:doneThis issue is complete and its PR has been merged or closed.

The detailed breakdown below shows what Colony does at each stage and where to see it. For every state, its label and the transitions between states, see the state table in the Labels reference.

Detailed pipeline stage breakdown

What happens: The Sprint Master picks up the issue on its next poll cycle (default: every 30 seconds). It creates a pipeline_issues row in Postgres and transitions the issue to new.

Where to lookWhat you’ll see
GitHubThe colony:enqueue label is replaced by colony:new
Dashboard (http://localhost:9106)The issue appears in the pipeline view with state new
LogsSprint Master logs Intake: new issue. Filter to one issue with colony logs --issue <N>

Filtering logs: Logs are Pino JSON, so the issue number is in the structured issue field, not the message text. Use colony logs --issue <N>, or with Docker Compose: docker compose logs -f worker | grep '"issue":<N>'.

What happens: The Sprint Master enqueues an analyze task in the work_tasks queue. A worker claims the task and runs the analyzer, which reads the issue body, explores the codebase, and writes an implementation plan.

Where to lookWhat you’ll see
GitHubLabel changes to colony:analyzing
DashboardIssue state updates to analyzing; worker activity shows the claimed task
LogsWorker logs Claimed task with taskType: analyze (filter: colony logs --issue <N>)

What happens: The analyzer finishes and posts a comment on the issue with its implementation plan. The issue transitions to ready-for-dev, which enqueues a develop task.

Where to lookWhat you’ll see
GitHubLabel changes to colony:ready-for-dev. A new comment from Colony appears with the analysis plan
DashboardIssue state updates to ready-for-dev
LogsNo dedicated log line. Watch for the label change and the analysis comment on GitHub, or run colony why <N>

What happens: A worker claims the develop task while the issue is still labeled colony:ready-for-dev — there is no separate “in development” state or label; development happens under ready-for-dev. The developer agent creates a git worktree branched from origin/main, implements the changes using Claude Code, and opens a pull request, which transitions the issue to in-review.

Where to lookWhat you’ll see
GitHubLabel stays colony:ready-for-dev while work is in flight. A new branch colony/issue-N appears, then a PR is opened and the label changes to colony:in-review
DashboardIssue state stays ready-for-dev; worker activity shows the claimed develop task
LogsWorker logs Claimed task with taskType: develop. No stable log line for worktree creation: watch for the colony/issue-<N> branch on GitHub, or run colony why <N>

Timing: Development is the longest phase. A simple issue typically takes 2–5 minutes; more complex issues can take 10–30 minutes depending on the Claude model and issue complexity.

A worker claims the review task once the PR is opened, and the reviewer runs deterministic checks (build, test, lint) followed by an LLM-powered code review.

Where to lookWhat you’ll see
GitHubLabel changes to colony:in-review. Review comments appear on the PR
DashboardIssue state updates to in-review
LogsWorker logs Claimed task with taskType: review, then reviewer logs Reviewing issue

colony:in-review → colony:merge-pending → colony:human-review-ready

Section titled “colony:in-review → colony:merge-pending → colony:human-review-ready”

What happens: Once the reviewer approves, the issue transitions to merge-pending — Colony attempts to merge automatically once CI completes. With the default review.auto_merge_on_approval: false, the merge step hands off to human-review-ready instead of merging, and the issue is now waiting for your approval.

Where to lookWhat you’ll see
GitHubLabel changes to colony:merge-pending, then colony:human-review-ready. The PR has Colony’s review comments and is ready for your review
DashboardIssue state updates to merge-pending, then human-review-ready
LogsNo stable verdict log line. See the review comments on the PR and the label change on GitHub, or run colony why <N>

Review cycle: If the reviewer finds issues, the PR goes through a colony:changes-requested → colony:in-review cycle before reaching human-review-ready. Each cycle incorporates the previous review feedback.

Development timing: A simple issue typically takes 2-5 minutes. Complex issues can take 10-30 minutes. If the reviewer finds issues, the PR goes through a changes-requested → in-review cycle automatically.

Terminal window
# Docker:
docker exec colony-sprint-master colony status
docker compose logs -f worker
# Native:
colony status
colony logs

Once the issue reaches human-review-ready, review the PR on GitHub. Colony took your issue from description to working code — a branch, tests (if applicable), and a pull request ready for your review.

Completing the loop: With the default review.auto_merge_on_approval: false, Colony stops at human-review-ready and waits for you to approve and merge the PR on GitHub. Once merged, Colony detects the merge, transitions the issue to colony:done, and closes it automatically. In polling mode this can take up to one Sprint Master poll interval (default 30s), so the human-review-ready label lingering briefly after merge is expected. To skip the manual step, see Auto-merge in the First Issue Tutorial.

For advanced topics (reading analyzer plans, slash commands, PR review workflow, and common gotchas), see First Issue Tutorial.

Cost Expectations

Each issue costs Anthropic API credits. Rough ranges based on issue complexity:

ComplexityTypical cost
Simple (add a field, fix a typo)$1–3
Medium (new endpoint, refactor)$5–15
Complex (new feature, large refactor)$15–50

Before starting: run colony estimate to preview your projected monthly spend based on expected throughput and your config.

For evaluation: add claude.max_cost_per_issue: 10 to your colony.config.yaml to cap each issue at $10. If an issue hits the cap, it moves to colony:blocked and Colony posts a comment explaining the spend. Raise the cap in config and comment /colony:retry on the issue to retry. See claude.max_cost_per_issue for details.

After each issue: run colony inspect <issue> to review the per-issue cost breakdown and timeline.


You’ve seen Colony process a single issue. Here’s where to go:

  • Greenfield repos — use colony bootstrap <stack> <name> to scaffold a new Colony-managed repo with conventions, .gitignore patches, and GitHub labels pre-configured. See Bootstrap Guide.
  • Process more issues — try different issue types and complexities. See First Issue Tutorial for scoping guidance.
  • Connect an editor via MCP — run colony mcp to expose Colony pipeline tools in Claude Code, Cursor, or any MCP-compatible editor. See MCP Server (Editor Integration) below.
  • Seed the pipeline from a plan — use colony plan import <path> or the colony_import_plan MCP tool to bulk-file issues from a superpowers plan. See Plan Import Guide.
  • Enable autonomous merging — set review.auto_merge_on_approval: true in config (requires dual-app setup)
  • Enable webhooks (Docker Compose) — run docker compose --profile webhook up -d and set webhook.enabled: true in your config for near-instant event response instead of polling. See Webhook Setup.
  • Production deployment — Deployment Guide for hardened setup with monitoring, webhooks, and multi-repo support
  • Non-TypeScript repos — Colony supports any language. Configure workspace.setup_command and review.checks, and add .colony/conventions.md. See the Rails example.
  • Custom executors — SDK Guide for building your own pipeline stages
  • Enable autonomous self-improvement — define a charter, manage tracks, and let the Strategist propose weekly workflow snapshots. See Strategy & Tracks.
  • Configuration — Configuration Reference — start at Tier 1 for first-time setup

For the full command reference with all options, see CLI Reference.

Terminal window
colony status # Pipeline status and agent health
colony metrics # Throughput, cycle times, success rates
colony inspect <issue> # Per-issue cost and timeline
colony why <issue> # Diagnose why an issue is not progressing
colony check # Re-run setup validation
colony pause <issue> # Temporarily pause an issue
colony resume <issue> # Resume a paused issue
colony logs [agent] # Tail agent logs
colony safestop # Gracefully drain and stop all agents

The Colony MCP server exposes pipeline tools directly inside MCP-compatible editors — query issue status, file new issues, trigger retries, and manage the pipeline without leaving your editor.

Start the server:

Terminal window
colony mcp

This reads DATABASE_URL and GITHUB_TOKEN from your environment (or Colony config) and launches the MCP stdio server. Configure your editor to run this command as the MCP server process.

Claude Code (.mcp.json at the project root; or run claude mcp add colony -- colony mcp, adding --scope user for all projects):

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

Cursor (~/.cursor/mcp.json):

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

Available tools: colony_work, colony_file_issue, colony_estimate, colony_review, colony_act, colony_tracks, colony_import_plan, colony_intelligence, colony_workflows, colony_strategy, colony_flaky_checks. See MCP Server for the full tool reference, run modes, and slash command pack.


Quick fix: Run colony check --fix to automatically remediate the most common setup issues — missing tool config exclusions, placeholder repo_dir, and missing environment variables. It prompts before any destructive change.

Symptom: Cannot access your-org/your-repo or Authorization failed

Fix: See GitHub Authentication in the installation guide for the exact required scopes and permissions.

Anthropic API key rejected with invalid x-api-key (HTTP 401)

Section titled “Anthropic API key rejected with invalid x-api-key (HTTP 401)”

Symptom: Anthropic API key rejected (HTTP 401): {"error":{"type":"authentication_error","message":"invalid x-api-key"}}

Cause: You pasted a Claude OAuth token (sk-ant-oat..., issued by claude setup-token) into a slot expecting a regular API key (sk-ant-api...). The two use different HTTP auth schemes — OAuth tokens require Authorization: Bearer, not x-api-key.

Fix: Re-run colony quickstart (or re-export your token). The wizard now auto-detects the sk-ant-oat prefix and routes the value to CLAUDE_CODE_OAUTH_TOKEN with auth_mode: oauth-token. If your colony.config.yaml was already written incorrectly, edit it to:

claude:
auth_mode: oauth-token
oauth_token_env: CLAUDE_CODE_OAUTH_TOKEN

and export CLAUDE_CODE_OAUTH_TOKEN (not ANTHROPIC_API_KEY).

If you started from colony.config.example.yaml, the commented auth block at the top of its claude: section already contains these exact fields — uncomment them instead of editing from scratch.

Symptom: ANTHROPIC_API_KEY environment variable is not set or DATABASE_URL environment variable is not set

Fix: Export the missing variable, or add it to .env for Docker deployments. Run colony check to check all variables.

If agents fail after a terminal restart with Environment variable "GITHUB_TOKEN" is not set. Please set it to a valid GitHub token. (checked shell environment and .env files: <paths>), the parenthetical lists the .env files that were checked: the one beside colony.config.yaml, then the one in the current directory if that is different. If a listed file exists but still holds the .env.example placeholder, the error instead reads GITHUB_TOKEN in <path> is still the placeholder value from .env.example — replace it with a real token. See environment-variables.md for the lookup order. Check if .env exists in your Colony directory. If it does, colony start loads it automatically — the error may indicate the file was deleted or moved. Re-run colony quickstart to regenerate it, or manually create .env with your credentials.

Symptom: Cannot connect to Postgres at host:port

Fix:

  • Docker Compose: check docker compose ps — the postgres service should be healthy
  • External Postgres: verify the connection string in DATABASE_URL
  • Neon: ensure ?sslmode=require in the connection string

Symptom: colony check reports Claude CLI not found or failed

Fix: Re-run ./scripts/setup.sh from the colony repo root — it installs @anthropic-ai/claude-code and verifies claude --version. If you’d rather install it yourself, npm install -g @anthropic-ai/claude-code works but may EACCES on Linux with system Node; see the Prerequisites section for the mise/nvm path.

Symptom: ./scripts/setup.sh or npm install -g ... fails with EACCES: permission denied, mkdir '/usr/local/lib/node_modules/...' or similar.

Cause: System-installed Node (apt, yum) sets the npm global prefix to a root-owned directory. Don’t fix this with sudo — that leaves root-owned files in your home dir that EACCES on later non-sudo installs.

Fix (recommended): Install Node via mise so the prefix lives under your home directory:

Terminal window
curl https://mise.run | sh
exec $SHELL
mise use -g node@22
rm -rf node_modules # drop anything installed against the old Node
./scripts/setup.sh

Fix (if you’ve already used sudo npm install -g): root-owned files may remain in ~/.npm-global or /usr/local/lib/node_modules. Reclaim ownership and re-run:

Terminal window
sudo chown -R "$(id -u):$(id -g)" ~/.npm-global
./scripts/setup.sh

npm error config prefix cannot be changed from project config

Section titled “npm error config prefix cannot be changed from project config”

Symptom: Every npm command in the colony repo prints npm error config prefix cannot be changed from project config: /path/to/colony/.npmrc. Commands may still complete, but the error is noisy and breaks scripts that parse npm output.

Cause: A stray prefix=... line landed in a project-level .npmrc at the colony repo root. npm refuses prefix overrides from project config (only user/global are allowed). Some npm versions silently route npm config set prefix to project location when invoked inside a workspace, even though --location=user is supposed to be the default.

Fix:

Terminal window
# Inspect the offending file
cat /path/to/colony/.npmrc
# If it only contains the prefix line, remove the file entirely
rm /path/to/colony/.npmrc
# If it contains other settings you want to keep, strip just the prefix line
sed -i '/^prefix\s*=/d' /path/to/colony/.npmrc

Then re-run ./scripts/setup.sh. The current script detects this case at the start of step 4 and cleans it up automatically; this manual fix is only needed if you set the prefix outside the bootstrap script.

Symptom: docker compose ps shows a service as unhealthy

Fix: Check service logs (docker compose logs <service>). Common causes: config not mounted, port conflicts, database not ready.

Symptom: Issue label doesn’t change after several minutes, or no worker activity appears.

Fix:

  1. Run colony why <N> (replace <N> with the issue number) — this is the purpose-built diagnostic and shows exactly why an issue isn’t progressing: block reason, state history, recent failures, and recommended next action.
  2. Run colony status to verify all agents are running.
  3. Run colony check to verify connectivity and configuration.
  4. Check logs with colony logs for specific errors.

Symptom: Issue stuck in colony:ready-for-dev for a long time with an active worker, or Colony posts a comment saying the turn limit was reached.

Fix: Comment /colony:decompose on the issue to send it to the planner, which breaks it into smaller sub-issues. Alternatively, comment /colony:cancel to stop processing, then re-create the issue with a narrower scope. For your first issue, start with a single function, a simple bug fix, or a minor config change.

Symptom: The wizard fails partway through (e.g., config write fails, agent won’t start) and you’re unsure what state Colony left behind.

Fix: When a wizard step fails, the runner prompts “Would you like to roll back changes made so far?” — answer yes to undo any config files written, containers started, or labels created during the session. After rollback, fix the root cause (check logs, verify env vars) and re-run colony quickstart. The wizard will prompt to resume from the last successful phase.

For comprehensive failure diagnosis, see Failure Modes Guide.


Run colony check at any time to validate your setup. It runs six progressive stages — config, credentials, database, repository, labels, and runtime — and skips the runtime stage with a clear message when agents aren’t running.

Terminal window
colony check # Full validation (all stages)
colony check --stage config # Single stage (config, credentials, database, repository, labels, runtime)
colony check --fix # Auto-remediate common failures (prompts before any destructive change)

The legacy commands colony doctor, colony preflight, and colony validate-config are aliases for specific stages of colony check and will continue to work, but colony check is the recommended entry point.