Colony Configuration Reference

Colony Configuration Reference

This document is the Colony configuration reference. It covers global infrastructure sections, agent configuration, and the config resolution chain. For multi-repo and multi-tenant configuration (Colony Cloud), see the Multi-Repo (Colony Cloud) section at the bottom.

Config File Format

Colony uses YAML configuration files. The config is loaded from the first location found in this order:

1. Path passed via the --config CLI flag
2. ./colony.config.yaml (current working directory)
3. ~/.colony/config.yaml (user home directory)

If no config file is found, Colony uses built-in defaults where available.

Environment Variable Resolution

Call resolveConfig() before any GitHub operations. This function validates the config and resolves credentials from environment variables — reading GITHUB_TOKEN (or the value of token_env) into github.token, reading GitHub App private keys from disk, and resolving per-repo secrets.

Never use the raw parsed config object directly for GitHub operations; always go through resolveConfig().

github

Authentication and identity settings for the target repository.

Field	Type	Default	Description
owner	string	required	GitHub organization or user that owns the target repository
repo	string	required	Target repository name
token_env	string	'GITHUB_TOKEN'	Name of the environment variable containing the Personal Access Token used for GitHub API calls
app	GitHubAppConfig	—	GitHub App credentials for the coder identity (Analyzer, Developer). Use instead of token_env for App-based auth
ops_app	GitHubAppConfig	—	Separate GitHub App credentials for the ops identity (Sprint Master, Reviewer, Merger). Allows two distinct bot identities
ops_token_env	string	—	Name of the environment variable containing the PAT for the ops identity. Alternative to ops_app
bot_username	string	—	Display name shown for bot-authored comments and labels

GitHubAppConfig

Used by github.app and github.ops_app.

Field	Type	Default	Description
app_id	number	required	GitHub App ID (found in the App settings page)
private_key_path	string	required	Path to the .pem private key file for this App
installation_id	number	required	Installation ID for this App on the target organization or repo

labels

Controls the prefix used for all pipeline state labels created by Colony on GitHub issues.

Field	Type	Default	Description
prefix	string	'colony'	Prefix for pipeline state labels (e.g. colony:analyzing, colony:in-development). Change this if you need to run multiple Colony instances against the same repo with distinct label namespaces

logging

Controls log output from all Colony processes.

Field	Type	Default	Description
level	string	'info'	Pino log level. Valid values: 'trace', 'debug', 'info', 'warn', 'error', 'fatal'
format	'json' | 'pretty'	'pretty'	Log output format. Use 'json' in production/containerized deployments for structured log ingestion; use 'pretty' for local development

workspace

Controls how Colony creates and manages git worktrees for each issue.

Field	Type	Default	Description
repo_dir	string	'.'	Path to the local git clone of the target repository. Colony creates worktrees under this directory
base_dir	string	'~/.colony/workspaces/{owner}/{repo}'	Base directory for worktrees. Supports {owner} and {repo} template tokens which are substituted at runtime
cleanup_after_merge	boolean	true	Remove the worktree after a PR is merged. Set to false to retain worktrees for post-merge inspection
setup_command	string	—	Command to run after creating a worktree, instead of the default npm install. Use for non-TypeScript repos (e.g. 'bundle install' for Ruby/Rails)
setup_timeout	number	300	Seconds to allow the setup command to run before timing out
prune_blocked_after_days	number	7	Days before worktrees for blocked issues are automatically pruned
review_workspace_base	string	—	Container-local path for ephemeral reviewer worktrees. Required when the reviewer runs in an isolated container with a different filesystem layout
skip_pre_push_hook	boolean	—	When true, passes --no-verify to git push. Colony runs its own validation steps, so this is safe in containerized deployments where the local pre-push hook is not meaningful
branch	string	'main'	Default branch name for the repository. Override when the repo’s default branch is not main (e.g. 'master', 'develop')

database

Connection settings for the Postgres database used by the pipeline store. This section is optional for configuration — if omitted, Colony reads DATABASE_URL from the environment using built-in defaults. However, a Postgres connection is always required at runtime — colony doctor will always validate database connectivity regardless of whether this section is present.

Field	Type	Default	Description
url_env	string	'DATABASE_URL'	Name of the environment variable containing the Postgres connection string
max_connections	number	10	Maximum number of connections in the pg connection pool. Increase for high-throughput deployments with many concurrent workers
idle_timeout	number	10000	idleTimeoutMillis for the pg connection pool (milliseconds). Lower this for connection-constrained environments
ssl	boolean	false	Enable SSL for Postgres connections. Required for most cloud-hosted Postgres instances (e.g. RDS, Cloud SQL)

Database migrations: Colony runs Postgres migrations automatically at agent startup — both the sprint-master and worker call PipelineStore.initialize() which applies all pending migrations before the agent begins processing. No manual migration step is needed. If startup fails with a migration error, verify DATABASE_URL connectivity and that the Postgres user has CREATE TABLE privileges.

event_log

Controls the local event log written by Colony agents. This section is optional.

Field	Type	Default	Description
enabled	boolean	—	Enable or disable event logging
dir	string	'~/.colony/events'	Directory where event log files are written
retention_days	number	30	Number of days to retain event log files before pruning

webhook

Configures the webhook receiver that listens for incoming GitHub webhook events. This section is optional — omit it if you are not running the webhook receiver.

Field	Type	Default	Description
enabled	boolean	required	Enable the webhook receiver
port	number (1–65535)	required	Port for the webhook receiver HTTP server to listen on
secret_env	string	—	Name of the environment variable containing the HMAC secret used to verify webhook payloads from GitHub
dispatch_host	string	—	Host used for agent wake dispatch when a webhook event is received

claude

Controls Claude CLI invocation behaviour and model selection for all agents.

Field	Type	Default	Description
timeout	number	1800	Overall Claude CLI invocation timeout in seconds
max_retries	number	1	Number of times to retry a failed Claude invocation
inactivity_timeout	number	300	Seconds without stdout/stderr output before the process is killed with SIGKILL
max_cost_per_issue	number	—	USD cost cap per issue. When the accumulated cost for an issue reaches this limit, the Claude invocation is aborted, the issue is moved to colony:blocked, and Colony posts a comment with the cost breakdown. To unblock: raise this value in config, then remove the colony:blocked label from the GitHub issue to re-trigger processing. Omit for no limit.
binary_path	string	'claude'	Path to the Claude CLI binary. Override when the binary is not on PATH or you need a specific version
provider	'anthropic' | 'foundry'	'anthropic'	API provider for Claude Code CLI. Use 'foundry' to route through Azure Foundry
foundry	ClaudeFoundryConfig	—	Azure Foundry configuration. Only used when provider: 'foundry'
models	ClaudeModelsConfig	—	Per-agent model overrides
scaling	ClaudeScalingConfig	—	Per-complexity turn limits and model overrides. When omitted, built-in defaults are used (see below)

ClaudeFoundryConfig

Used by claude.foundry. Only applies when claude.provider is 'foundry'.

Field	Type	Default	Description
resource	string	—	Azure resource name. URL constructed as https://{resource}.services.ai.azure.com/anthropic. Mutually exclusive with base_url
base_url	string	—	Full Foundry base URL. Mutually exclusive with resource
api_key_env	string	'ANTHROPIC_FOUNDRY_API_KEY'	Environment variable holding the Foundry API key
pin_models.opus	string	—	Pin the Opus deployment name (sets ANTHROPIC_DEFAULT_OPUS_MODEL)
pin_models.sonnet	string	—	Pin the Sonnet deployment name (sets ANTHROPIC_DEFAULT_SONNET_MODEL)
pin_models.haiku	string	—	Pin the Haiku deployment name (sets ANTHROPIC_DEFAULT_HAIKU_MODEL)

Example:

claude:
  provider: foundry
  foundry:
    resource: my-azure-resource
    api_key_env: ANTHROPIC_FOUNDRY_API_KEY
    pin_models:
      opus: claude-opus-4-6
      sonnet: claude-sonnet-4-6
      haiku: claude-haiku-4-5

Authentication: set ANTHROPIC_FOUNDRY_API_KEY in your environment, or omit it to use Azure Entra ID (DefaultAzureCredential chain). See the Claude Code Foundry docs for details.

ClaudeModelsConfig

Used by claude.models.

Field	Type	Default	Description
developer	string	'claude-opus-4-6'	Model used for the developer agent
reviewer	string	'claude-sonnet-4-6'	Model used for the reviewer agent
analyzer	string	'claude-sonnet-4-6'	Model used for the analyzer agent
planner	string	'claude-opus-4-6'	Model used for the planner agent
merger	string	'claude-sonnet-4-6'	Model used for the merger agent

ClaudeScalingConfig

Used by claude.scaling. The config is a map with keys small, medium, and large (matching issue complexity levels). Each entry is a ClaudeScalingEntry.

Example:

claude:
  scaling:
    small:
      developer_max_turns: 80
    medium:
      developer_max_turns: 150
    large:
      developer_max_turns: 250
      no_progress_window: 75

ClaudeScalingEntry

Field	Type	Default	Description
developer_max_turns	number	required	Maximum Claude turns for a developer invocation at this complexity. Built-in defaults: 80 (small), 150 (medium), 250 (large)
model	string	—	Override the model for this complexity level, taking precedence over claude.models.developer
effort	'low' | 'medium' | 'high' | 'max'	—	Effort level hint passed to the Claude CLI for this complexity
planning_max_turns	number	500	Maximum turns for planning sub-tasks at this complexity
no_progress_window	number	—	Number of turns without measurable progress before aborting. Only set by default for large issues (75)
backstop_max_turns	number	500	Hard turn ceiling regardless of other limits

Tuning for first use: The defaults work well for evaluation. If you find issues timing out or review checks failing on slow test suites, these are the first fields to adjust:

Field	Default	Recommended starting point
claude.timeout	1800	Increase to 3600 for large repos with long build times
review.timeout_per_check	120	Raise to 300 for slow test suites
agents.sprint_master.poll_interval	30	30 is sufficient for evaluation; lower only if you need sub-30s latency and have webhooks configured

review

Controls PR review behaviour: deterministic check commands, LLM review rounds, CI gating, and merge policy.

Field	Type	Default	Description
checks	Record<string, string>	{}	Named shell commands to run as deterministic review checks (e.g. test: 'npm test', lint: 'npm run lint'). Keys are check names; values are shell commands
timeout_per_check	number	120	Seconds allowed for each check command before it is killed
max_review_cycles	number	—	Maximum number of LLM review rounds before giving up. Unlimited if unset
max_reimplement_cycles	number	—	Maximum number of times the developer re-implements after a review rejection. Unlimited if unset
max_diff_lines	number	3000	Truncate the PR diff at this many lines when sending it to the LLM reviewer
rebase_before_check	boolean	true	Rebase the PR branch onto the base branch before running check commands
auto_merge_on_approval	boolean	false	Automatically merge the PR after the reviewer approves it
require_ci_pass	boolean	true	Wait for all required CI checks to pass before merging
ci_check_timeout	number	300	Seconds to wait for CI checks to complete before timing out
ci_required_checks	string[]	[]	Names of specific CI checks that must pass. When empty, all checks must pass
format_command	string	—	Formatting command to run before review checks (e.g. 'npm run format:fix'). Optional
empty_verdict_auto_approve	boolean	true	Auto-approve when the LLM returns an empty or unparseable verdict and all deterministic checks passed

agents

Configures the Colony agent processes. Each agent type extends a common set of fields. Agents run as standalone processes (singletons) or as part of the per-repo worker pool.

Common AgentConfig Fields

All agent types share these base fields:

Field	Type	Default	Description
enabled	boolean	true	Whether the agent runs
poll_interval	number	30	Seconds between poll cycles (minimum 5)
health_port	number	(per agent)	HTTP health check port
effort	'low' | 'medium' | 'high' | 'max'	—	Claude effort level for this agent

agents.sprint_master

Issue intake and pipeline monitoring. Enqueues tasks to the Postgres work queue when issues transition states.

Field	Type	Default	Description
Common fields		health_port: 9100	See Common AgentConfig Fields
intake_mode	'all' | 'tagged'	'tagged'	Whether to pick up all new issues or only colony-tagged ones
heartbeat_timeout_minutes	number	5	Minutes before reclaiming stale tasks from workers that stopped heartbeating
sweep_cooldown_minutes	number	10	Minutes to suppress re-enqueueing a sweep task after completion (0 to disable)
label_sync_limit	number	25	Max issues to reconcile labels for per poll cycle
projection_drain_limit	number	50	Max queued GitHub write projections to drain per poll cycle

agents.analyzer

Issue analysis and triage. Uses bare AgentConfig with no additional fields.

Field	Type	Default	Description
Common fields		health_port: 9101	See Common AgentConfig Fields

agents.reviewer

PR review: deterministic checks plus LLM review. Uses bare AgentConfig with no additional fields.

Field	Type	Default	Description
Common fields		health_port: 9103	See Common AgentConfig Fields

agents.developer

Issue implementation via Claude Code.

Field	Type	Default	Description
Common fields		health_port: 9102	See Common AgentConfig Fields
repo_context	RepoContextConfig	—	Controls repository context injection into prompts
pr_overlap_threshold	number (0–1)	—	Fraction of plan files overlapping with open PRs to trigger block
max_tooling_retries	number	2	Poll-level retries for transient push failures

RepoContextConfig

Used by agents.developer.repo_context.

Field	Type	Default	Description
enabled	boolean	—	Enable repository context injection
max_tokens	number	—	Maximum tokens for the context payload
tree_depth	number	—	Depth of the directory tree to include

agents.planner

Epic decomposition — breaks large issues into sub-tasks.

Field	Type	Default	Description
Common fields		health_port: 9105	See Common AgentConfig Fields
max_turns	number	200	Max Claude turns for planning
model	string	—	Override model for planner

agents.merger

Merge orchestration — handles PR merging and conflict resolution.

Field	Type	Default	Description
Common fields		health_port: 9104	See Common AgentConfig Fields
conflict_resolution	ConflictResolutionConfig	—	Automated merge conflict resolution settings

ConflictResolutionConfig

Used by agents.merger.conflict_resolution.

Field	Type	Default	Description
enabled	boolean	—	Enable automated conflict resolution
max_conflict_files	number	—	Maximum number of conflicting files to attempt resolution on
max_conflict_regions	number	—	Maximum number of conflict regions to attempt resolution on
timeout	number	—	Timeout in seconds for conflict resolution
model	string	—	Override model for conflict resolution
auto_merge_high_confidence_resolutions	boolean	—	Automatically merge when conflict resolution has high confidence

agents.monitor

Pipeline observability, self-healing, and Prometheus metrics. Disabled by default.

Field	Type	Default	Description
Common fields		enabled: false, health_port: 9106	See Common AgentConfig Fields
agent_down_timeout	number	120	Seconds before alerting that an agent is down
pipeline_stall_timeout_minutes	number	60	Minutes before alerting a pipeline stall
error_rate_threshold	number (0–1)	0.5	Alert if error rate exceeds this fraction
error_rate_window	number	30	Minutes, rolling window for error rate calculation
cost_alert_threshold	CostAlertThreshold	—	Cost alerting thresholds
alert_cooldown	number	30	Minutes, deduplication window for alerts
alert_channels	MonitoringAlertChannel[]	[]	Alert delivery channels
metrics_refresh_minutes	number	10	How often to refresh pipeline metrics
sweep_cooldown_minutes	number	10	Minutes to suppress re-enqueueing a sweep task after completion (0 to disable)
agent_health_host	string	'localhost'	Host for polling agent health endpoints
auth	MonitorAuth	—	Basic auth for the monitor HTTP API
self_healing	SelfHealingConfig	(see below)	Self-healing automation settings

CostAlertThreshold

Used by agents.monitor.cost_alert_threshold.

Field	Type	Default	Description
daily_usd	number	—	Alert when daily cost exceeds this USD amount
monthly_usd	number	—	Alert when monthly cost exceeds this USD amount

MonitorAuth

Used by agents.monitor.auth.

Field	Type	Default	Description
username	string	required	Username for basic auth
password_env	string	required	Name of the environment variable containing the password

MonitoringAlertChannel

Used by agents.monitor.alert_channels.

Field	Type	Default	Description
type	'github_issue' | 'webhook' | 'slack' | 'pagerduty'	required	Alert channel type
url	string	—	Endpoint URL for webhook/slack/pagerduty
url_env	string	—	Name of the environment variable containing the endpoint URL
routing_key	string	—	PagerDuty integration routing key (literal value, not an env var name)

Example: Alerting Configuration

agents:
  monitor:
    alert_cooldown: 30
    cost_alert_threshold:
      daily_usd: 50
      monthly_usd: 500
    alert_channels:
      - type: slack
        url_env: COLONY_SLACK_WEBHOOK_URL
      - type: pagerduty
        routing_key: YOUR_PAGERDUTY_ROUTING_KEY
      - type: webhook
        url_env: COLONY_ALERT_WEBHOOK_URL
      - type: github_issue

• slack — Posts Block Kit messages to a Slack incoming webhook. Set url_env to the name of the environment variable containing the webhook URL.
• pagerduty — Sends Events API v2 triggers. Set routing_key to the PagerDuty integration routing key (literal value, not an env var).
• webhook — POSTs a JSON payload to any HTTP endpoint. Set url_env to the name of the environment variable containing the URL.
• github_issue — Creates a GitHub issue labeled colony:alert in the first configured repo. No additional fields required.

The alert_cooldown (minutes) controls deduplication — each unique alert ID is only dispatched once per window. The cost_alert_threshold fires a warning when aggregate daily or monthly spend exceeds the configured USD amounts.

SelfHealingConfig

Used by agents.monitor.self_healing.

Field	Type	Default	Description
auto_relabel_orphans	boolean	false	Automatically relabel issues that have fallen out of the state machine
worktree_cleanup_interval_hours	number	6	Hours between worktree cleanup sweeps
auto_unblock_transient	boolean	false	Automatically unblock issues that were blocked by transient failures
max_auto_unblocks_per_issue	number	—	Maximum automatic unblocks per issue before requiring manual intervention
auto_restart	boolean	false	Enable automatic agent restart on failure
restart_strategy	'pid' | 'systemd' | 'pm2'	'pid'	Process restart mechanism
restart_cooldown	number	300	Seconds between restart attempts
max_restart_attempts	number	3	Maximum restart attempts before giving up
restart_dry_run	boolean	false	Log restart actions without executing them
work_task_retention_days	number	7	Days to retain completed work tasks before pruning

agents.workers

Per-repo worker pool configuration. Workers claim tasks from the Postgres work_tasks queue and dispatch to executor libraries. This section is optional — omit it when using standalone agent processes.

Field	Type	Default	Description
Common fields		—	Inherits enabled, poll_interval, health_port from Common AgentConfig Fields; defaults depend on deployment configuration
heartbeat_interval	number	—	Seconds between task heartbeats. Workers send heartbeats to the Postgres queue to signal liveness — if a worker stops heartbeating for longer than sprint_master.heartbeat_timeout_minutes, the task is reclaimed
max_task_retries	number	3	Max failures for a repo+issue+taskType combination within 60 minutes before dropping re-enqueue

Resolution Chain

Note: The resolution chain applies to multi-repo deployments using repos[]. For single-repo setups (the default), all settings are configured at the top level — no per-repo overrides are needed. See Multi-Repo (Colony Cloud) for details.

When a field can be set both globally and per-repo, Colony resolves the value using this fallback chain:

repoConfig.<field> ?? config.<field> ?? default

The per-repo value takes precedence when set; it falls back to the global value, then to the built-in default. The following helper functions in packages/core/src/config.ts implement this pattern for specific fields:

• resolveIntakeMode(repoConfig, config) — resolves intake_mode
• resolveAutoMerge(repoConfig, config) — resolves auto-merge behavior
• resolveSelfImprovement(repoConfig, config) — resolves self_improvement settings
• resolveDependabotConfig(repoConfig) — resolves dependabot settings

self_improvement

Controls Colony’s self-improvement feature, which allows Colony to file issues against itself.

Field	Type	Default	Description
enabled	boolean	false	Enable the self-improvement feature
label	string	'colony:self-improvement'	GitHub label used to tag self-improvement issues
cooldown_minutes	number (≥1)	30	Minimum minutes between self-improvement issue filings
tracks	SelfImprovementTrack[]	—	Per-track configuration for self-improvement. See deprecated fields

calibration

Controls the complexity calibration feature used to tune issue complexity estimates.

Field	Type	Default	Description
lookback_days	number	7	Number of days of historical issues to consider when calibrating complexity estimates

executors (ExecutorsConfig)

Executor-specific settings that belong to the execution logic of each agent type (distinct from agent process infrastructure such as poll_interval and health_port).

If executors is not set, values are auto-populated from the corresponding agents.* fields for backward compatibility via populateExecutorsFromAgents() in config.ts.

executors.analyzer

Field	Type	Default	Description
effort	'low' | 'medium' | 'high'	—	Claude effort level for the analyzer. Maps to claude --effort

executors.developer

Field	Type	Default	Description
repo_context	RepoContextConfig	—	Controls how the developer builds repository context for Claude Code
pr_overlap_threshold	number	—	Number of overlapping files with another open PR before blocking development
max_tooling_retries	number	—	Maximum retries for transient tooling errors during development
effort	'low' | 'medium' | 'high'	—	Claude effort level for the developer

executors.reviewer

Field	Type	Default	Description
effort	'low' | 'medium' | 'high'	—	Claude effort level for the reviewer

executors.planner

Field	Type	Default	Description
max_turns	number	—	Maximum number of turns for the planner’s Claude session
effort	'low' | 'medium' | 'high'	—	Claude effort level for the planner
model	string	—	Override the Claude model used by the planner

executors.merger

Field	Type	Default	Description
conflict_resolution	ConflictResolutionConfig	—	LLM-assisted conflict resolution settings. See the agents.merger section for field details

Multi-Repo (Colony Cloud)

Colony Cloud supports managing multiple repositories from a single Colony instance using repos[] or tenants[] configuration. For single-repo deployments (the default open-source path), these sections are not needed — the flat github + workspace top-level config is all you need.

repos[] (RepoConfig)

Multi-repo deployments list each repository under repos. Each entry configures authentication, workspace, and pipeline behavior for one repository. Config cannot have both top-level repos and tenants.

Field	Type	Default	Description
owner	string	required	GitHub organization or user that owns the repository
repo	string	required	Repository name
token_env	string	—	Name of the environment variable containing the PAT for this repo. Either token_env or app is required
app	GitHubAppConfig	—	Per-repo GitHub App credentials for the coder identity. Either app or token_env is required
ops_app	GitHubAppConfig	—	Per-repo GitHub App credentials for the ops identity
ops_token_env	string	—	Name of the environment variable containing the PAT for the ops identity. Alternative to ops_app
bot_username	string	—	Display name shown for bot-authored comments and labels for this repo
workspace	RepoWorkspaceConfig	required	Per-repo workspace settings. Overrides the global workspace section
review	RepoReviewConfig	—	Per-repo review overrides. Only the fields in the explicit pick list can be overridden
self_improvement	SelfImprovementConfig	—	Per-repo override for self-improvement settings
pattern_memory	PatternMemoryConfig	—	Per-repo pattern memory settings. See fields below
sla	SlaConfig	—	Per-repo SLA thresholds. See fields below
intake_mode	'all' | 'tagged'	—	Overrides the global agents.sprint_master.intake_mode for this repo. When set, only this repo’s intake behavior changes
workers	WorkerPoolConfig	—	Per-repo worker pool settings. See fields below
dependabot	DependabotConfig	—	Per-repo Dependabot integration settings. See fields below

pattern_memory

Field	Type	Default	Description
enabled	boolean	required	Enable pattern memory for this repo
max_results	number (≥1)	required	Maximum number of pattern results to include in prompts
lookback_days	number (≥1)	required	Number of days of history to search for patterns

sla

Field	Type	Default	Description
warn_after_minutes	Record<string, number>	—	Map of pipeline state name (e.g. 'in-development') to the number of minutes before a warning is emitted. Only states that need a threshold need to be listed

workers

Field	Type	Default	Description
pool_size	number (integer ≥1)	—	Number of worker processes to run for this repo
memory	string	—	Container memory limit for worker processes (e.g. '4g', '6G')
health_port_start	number	—	Starting port for sequential health check endpoint allocation. Port ranges must not overlap across repos

dependabot

Field	Type	Default	Description
auto_review	boolean	—	Automatically trigger a review cycle for Dependabot PRs
auto_merge_patch	boolean	false	Auto-merge patch updates after deterministic checks pass
auto_merge_minor	boolean	false	Require LLM review for minor updates before merging
auto_migrate_breaking	boolean	false	Automatically create migration issues for breaking major updates (opt-in)
bot_usernames	string[]	['dependabot[bot]']	GitHub usernames to treat as Dependabot for triggering this integration

Per-Repo Workspace Overrides (RepoWorkspaceConfig)

Each entry in repos[] requires a workspace block. Fields here override the corresponding global workspace values for that repo using the fallback chain repoConfig.workspace.<field> ?? config.workspace.<field> ?? default.

Field	Type	Default	Scope	Description
repo_dir	string	required	overrides global	Path to the local git clone for this repo
base_dir	string	required	overrides global	Base directory for this repo’s worktrees. Supports {owner} and {repo} template tokens
setup_command	string	—	overrides global	Command to run after creating a worktree (e.g. 'bundle install'). Overrides the global workspace.setup_command
setup_timeout	number	300	overrides global	Seconds to allow the setup command to run. Overrides the global workspace.setup_timeout
review_workspace_base	string	—	overrides global	Container-local path for ephemeral reviewer worktrees
skip_pre_push_hook	boolean	—	overrides global	Pass --no-verify to git push for this repo
branch	string	'main'	overrides global	Default branch name for this repo
secret_env_vars	string[]	—	per-repo only	Names of environment variables to resolve and inject into worker processes for this repo
timeouts	TimeoutsConfig	—	per-repo only	Fine-grained clone and tooling timeouts. See fields below

timeouts (TimeoutsConfig)

Field	Type	Default	Description
clone	number	600 (recommended)	Seconds before git clone is timed out
mise_install	number	600	Seconds before mise install is timed out
mise_reshim	number	30	Seconds before mise reshim is timed out
submodule_init	number	120	Seconds before git submodule update --init is timed out

Per-Repo Review Overrides (RepoReviewConfig)

The review block inside a repos[] entry accepts an explicit subset of the global ReviewConfig fields. Only fields in the following pick list can be overridden per-repo:

Field	Type	Description
checks	Record<string, string>	Override the review check commands for this repo
timeout_per_check	number	Seconds to allow each check to run
rebase_before_check	boolean	Rebase the PR branch onto the base branch before running checks
require_ci_pass	boolean	Require all CI checks to pass before merging
ci_check_timeout	number	Seconds to wait for CI checks to complete
ci_required_checks	string[]	Names of CI checks that must pass
format_command	string	Command to auto-format code before review
auto_merge_on_approval	boolean	Auto-merge the PR when the reviewer approves

The following ReviewConfig fields are global-only and cannot be overridden per-repo: max_review_cycles, max_reimplement_cycles, max_diff_lines, empty_verdict_auto_approve.

Note: New fields added to ReviewConfig are not automatically per-repo-overridable. The pick list in RepoReviewConfig must be updated explicitly to expose them.

tenants[] (TenantConfig)

Multi-tenant deployments group repositories by tenant under tenants. Each tenant has its own GitHub App credentials and optional cost budget. Config cannot have both top-level tenants and repos.

Field	Type	Default	Description
id	string	required	Unique identifier for this tenant
name	string	—	Human-readable tenant name
app	GitHubAppConfig	—	Tenant-level GitHub App credentials for the coder identity
ops_app	GitHubAppConfig	—	Tenant-level GitHub App credentials for the ops identity
anthropic_api_key_env	string	—	Name of the environment variable containing the Anthropic API key for this tenant. Overrides the global ANTHROPIC_API_KEY
cost_budget	object	—	Cost budget settings for this tenant. See fields below
defaults	object	—	Default settings cascaded to repos in this tenant that do not override them. Currently supports timeouts (TimeoutsConfig)
repos	RepoConfig[]	required	List of repositories belonging to this tenant

cost_budget

Field	Type	Default	Description
monthly_usd	number	—	Monthly spending cap in USD for this tenant

Per-agent-type keys alongside repos[].workers

When repos[].workers (the worker pool model) is configured, setting per-agent-type keys under agents (developer, analyzer, reviewer, merger, planner) for executor-specific settings is deprecated. Use the executors section instead.

# Before (deprecated — when repos[].workers is set)
agents:
  developer:
    effort: high

# After
executors:
  developer:
    effort: high

Deprecated Configuration

The following fields are still accepted by the config loader but will be removed in a future release. Migrate away from them as soon as possible.

---

llm.* (LlmConfig)

Fields: llm.analyzer_max_turns, llm.reviewer_max_turns, llm.developer_max_turns

Migration: Use claude.scaling (ClaudeScalingConfig) instead. Per-agent max_turns are now configured via claude.scaling entries keyed by complexity (small, medium, large).

# Before (deprecated)
llm:
  developer_max_turns: 150

# After
claude:
  scaling:
    medium:
      developer_max_turns: 150

---

monitoring.* (legacy top-level key)

Migration: Move all fields under agents.monitor. The loader still accepts monitoring: as a top-level key and merges it into agents.monitor for backward compatibility (see config.ts:179–194), but this bridge will be removed in a future release.

# Before (deprecated)
monitoring:
  enabled: true
  port: 9100

# After
agents:
  monitor:
    enabled: true
    port: 9100

---

self_improvement.tracks (SelfImprovementTrack[])

Migration: Manage tracks via the dashboard UI or the monitor REST API (POST /api/si/tracks). YAML track definitions in the config file are ignored as of the deprecation warning emitted at config load time (see config.ts:249–257) and will be fully removed in a future release.