Organization Pipeline Defaults (Agents)

The Agents settings page (/settings/agents) is the org-level editor for Colony pipeline and agent configuration. Changes here write to tenants.config.* in the Colony Cloud database and become the default for every repository in your organization. Repo-level settings can override any field; see Merge precedence below.

For the complete field catalogue (all ~100 fields, types, and defaults) see the Configuration schema reference. For cost tuning and model routing guidance see the Tune Model Routing and Cost Caps guide.

Configuration sections

The page is divided into the following sections, accessible via the in-page section navigator:

Section	Description
Claude Provider	API provider (Anthropic direct or Azure Foundry) and endpoint settings
Claude	CLI timeout, inactivity timeout, and API retry count
Models	Per-role model overrides (Developer, Reviewer, Analyzer, Planner, Merger)
Scaling	Per-complexity-tier model, effort level, and developer turn limits (small / medium / large)
Agent Turn Limits	Deprecated per-role max-turn overrides (use Scaling tiers instead)
Model Routing	Task-type × complexity-tier model routing matrix and global override
Engine	Per-agent execution engine selection (Claude Code or OpenAI Codex) and Codex CLI settings
Review	Auto-merge, CI requirements, review checks, diff limits, and external PR review
Agents	Mayor poll interval, heartbeat timeout, and issue intake mode
Costs	Per-issue and daily USD cost caps
Workspace	Worktree cleanup, stale-worktree pruning, and setup timeout
Labels	Colony-managed label prefix
White-Label	Slash-command root prefix
Workers	Worker heartbeat interval, task retry limit, and task duration deadline
Epic Execution	Feature-branch strategy, subtask rebase, and final-PR review policy
Dependabot	Automatic review and merge policy for Dependabot PRs
Self-Improvement	Autonomous self-improvement issue generation
Pattern Memory	Few-shot pattern retrieval from past issue resolutions
Code Boundaries	Forbidden and read-only path globs for the developer agent
SLA Thresholds	Per-state warn-after-minutes thresholds (surfaced on Inbox)
Conflict Resolution	LLM-assisted merge conflict resolution via the merger agent
Advanced: Execution	Repo context bundle, plan-file gate, overlap threshold, and per-executor effort overrides
Advanced: Reliability	Mayor auto-unblock, sync intervals, and starvation thresholds
Attribution	EU AI Act Article 50(1) disclosure footer
Intelligence	Repo intelligence auto-promotion thresholds and embedding settings
Retrieval	Vector-search retrieval: enable, injection, per-role enablement, token budget, and snippet limits (intelligence.retrieval.*)
Code Map	Analyzer code-map snapshot: enable, injection into prompts, token budget, and minimum confidence (code_map.*)

Note

The Model Routing section has a dedicated field reference. See Model Routing for the full field table, resolution precedence chain, and configuration examples.

Representative fields

The tables below cover the highest-impact fields. All other fields are documented in the Configuration schema reference.

Costs

Controls how much Colony may spend on Claude API calls before halting work.

Field	Config key	Unit	Default	Description
Max cost per issue	claude.max_cost_per_issue	USD	none	Colony halts the task when this per-issue ceiling is reached. Set to 0 or leave blank for no limit.
Max daily spend	max_daily_usd	USD	none	Global daily ceiling. All pipeline work halts when exceeded and automatically resumes at the next UTC midnight.

Tip

See the Tune Model Routing and Cost Caps guide for a walkthrough of setting effective cost limits alongside model routing.

Scaling tiers

Colony classifies each issue as small, medium, or large based on the analyzer’s complexity estimate. Each tier has independent model, effort, and turn-limit settings.

Tier	Field	Config key	Description
small / medium / large	Model	claude.scaling.<tier>.model	Override the Claude model for this tier. Leave blank to use the global model setting.
small / medium / large	Effort	claude.scaling.<tier>.effort	Reasoning effort level: low, medium, high, or max. Higher effort uses more tokens but produces better results on complex tasks.
small / medium / large	Developer max turns	claude.scaling.<tier>.developer_max_turns	Maximum conversation turns the developer agent may take for issues at this tier. Each turn is one Claude Code CLI invocation. (turns)

Additional per-tier fields (backstop_max_turns, no_progress_window, planning_max_turns) are documented in the Configuration schema reference.

Agents (intake mode)

Controls which issues Colony picks up for processing.

Field	Config key	Values	Default	Description
Intake mode	agents.sprint_master.intake_mode	all | tagged	all	all processes every new issue automatically; tagged only processes only issues that carry the Colony intake label.

Workers

Controls how managed Colony Workers communicate with the Cloud API and how long a task may run.

Field	Config key	Unit	Default	Description
Heartbeat interval	workers.heartbeat_interval	seconds	—	Seconds between Worker heartbeat pings to the Colony Cloud API.
Max task retries	workers.max_task_retries	count	—	Maximum consecutive failures for a repo + issue + task-type combination within 60 minutes before the task is permanently dropped.
Max task duration	workers.max_task_duration	minutes	45	Wall-clock deadline per task. Workers abort and fail the task if it exceeds this limit.
Stale task threshold	workers.stale_task_threshold	minutes	3	Minutes a claimed task may go without a heartbeat before a Worker’s sweep reclaims it and requeues it for another Worker. Distinct from the Mayor’s Heartbeat timeout, which applies the same reclaim check on the Mayor’s sweep — raise both together to reliably delay reclaim.

Note

workers.heartbeat_interval is in seconds. workers.max_task_duration is in minutes. Most other numeric config fields use seconds — check the field label or the Configuration schema reference for the unit of each field.

Execution engine

The Engine section lets operators switch any agent role to the OpenAI Codex CLI on a per-role basis. By default, all roles use claude-code (the Claude Code CLI). Setting agents.<role>.engine: codex routes that role’s tasks to the Codex CLI instead.

Codex is opt-in — switching a role requires:

1. The OPENAI_API_KEY secret to be configured in Settings → Secrets.
2. Codex model IDs (e.g. codex-1, o4-mini) to be set in the Codex model fields if you want to override the CLI default.
3. A Worker redeploy after saving — engine selection is read on startup and is not hot-reloadable.

claude.models.* and claude.scaling apply only to Claude Code-engine roles. When a role runs on Codex, configure its model via codex.models.<role> instead.

For the complete field reference see ## codex and Engine selection in the Configuration schema reference.

Merge precedence

This page edits the org-level (tenants.config) layer. The effective value for any field follows:

repo_configs.field ?? tenants.config.field ?? hardcoded default

Repository-level overrides take precedence over org-level defaults, which take precedence over Colony’s built-in defaults. Repo-level settings are configured per-repository under each repository’s Settings tab. Omitting a field at the repo level inherits the org default set here.

Role permissions

Action	Required role
View org pipeline configuration	Owner or Admin
Save org pipeline configuration	Owner or Admin

Both GET and PUT /api/orgs/:orgId/pipeline/config require the owner or admin role (requireOrgMembership('owner', 'admin'), packages/api/src/org-routes.ts:1664,2053). The Agents settings page is only reachable from the admin-only scope in the settings navigation.

API reference

Method	Path	Access	Description
GET	/api/orgs/:orgId/pipeline/config	Owner or Admin	Fetch the current org-level pipeline configuration.
PUT	/api/orgs/:orgId/pipeline/config	Owner or Admin	Save the org-level pipeline configuration.