Skip to content

Organization Pipeline Defaults (Agents)

The tenant view of Standards → Settings (/standards/settings) is the editor for Colony pipeline and agent configuration. With a repository in scope, choose Show tenant settings to reach it. Changes here write to tenants.config.* in the Pipeline Store and become the default for every repository in the tenant. Repositories can override some fields; see Merge precedence below.

For the complete field catalog (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.

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

SectionDescriptionApplies
Claude ProviderAPI provider (Anthropic direct, Azure Foundry, or an AI gateway) and endpoint settingsRequires worker redeploy
ClaudeCLI timeout, inactivity timeout, and API retry countApplies live
ModelsPer-role model overrides (Developer, Reviewer, Analyzer, Planner, Merger, Mayor conversation)Applies live
ScalingPer-complexity-tier model, effort level, and developer turn limits (small / medium / large)Applies live
Agent Turn LimitsAnalyzer and reviewer max turns (defaults 100 and 500). Not affected by Scaling tiers; the planner’s limit is under Advanced: ExecutionApplies live
Model RoutingTask-type × complexity-tier model routing matrix and global overrideApplies live
EnginePer-agent execution engine selection (Claude Code or OpenAI Codex) and Codex CLI settingsRequires worker redeploy
ReviewAuto-merge, CI requirements, review checks, diff limits, and external PR reviewApplies live
AgentsMayor poll interval, heartbeat timeout, issue intake mode, and whether and how often the Mayor replies to addressed commentsApplies live
CostsPer-issue cost cap, budget headroom and calibration lookback; the daily cost cap is shown read-only; administrators change it in BudgetsApplies live
WorkspaceWorktree cleanup, stale-worktree pruning, and setup timeoutApplies live
LabelsColony-managed label prefixRequires worker redeploy
White-LabelSlash-command root prefixRequires worker redeploy
WorkersWorker heartbeat interval, task retry limit, and task duration deadlineApplies live
Epic ExecutionFeature-branch strategy, subtask rebase, and final-PR review policyRequires worker redeploy
Dependency updatesWhether Colony reviews dependency updates automatically, which update types (patch, minor) may merge on their own, whether migration issues are filed for breaking changes, the bot accounts treated as dependency updates, and the most dependency updates in progress at once in each repository (default 3). These are the org-wide values; a repository can override any of them (see below).Applies live
Self-ImprovementAutonomous self-improvement issue generationApplies live
Pattern MemoryFew-shot pattern retrieval from past issue resolutionsRequires worker redeploy
Code BoundariesForbidden and read-only path globs for the developer agentRequires worker redeploy
Conflict ResolutionLLM-assisted merge conflict resolution via the merger agentRequires worker redeploy
MergingHow Colony merges a change (merge commit, squash or rebase), plus the opt-in pre-merge analysis that finds concurrent changes to semantically coupled files across branches and defers the later PR for re-review. Different from Conflict Resolution, which resolves git text conflictsRequires worker redeploy
Advanced: ExecutionRepo context bundle, plan-file gate, overlap threshold, and per-executor effort overridesRequires worker redeploy
Advanced: ReliabilityMayor auto-unblock, sync intervals, and starvation thresholdsRequires worker redeploy
AttributionEU AI Act Article 50(1) disclosure footerApplies live
IntelligenceRepo intelligence auto-promotion thresholds, embedding settings, retrieval tuning (intelligence.retrieval.*) and the analyzer code-map snapshot (code_map.*). Retrieval always runs and is injected into every agent’s prompt. The former retrieval enable, injection and per-role switches (intelligence.retrieval.{enabled,inject,agents}) are removed; the keys are still accepted and ignored.Applies live

Applies live means the change reaches running Workers within one heartbeat through the config_refresh command. Requires worker redeploy means the change takes effect on the next Worker redeploy.

Per-repository dependency update overrides

Section titled “Per-repository dependency update overrides”

On Autonomy → Settings, with the repository in scope, use the dependency update rows to override any of the six dependency update settings for that repository alone, so you can pilot auto-review on a few repositories or keep auto-merge off where automated dependency merges are not acceptable. Each setting shows where its value comes from: this repository, the tenant, or the default. Choose Use the tenant value to drop an override. Changes reach running workers within one heartbeat.

Choose AI gateway under Claude Provider to route Claude Code through an Anthropic-compatible gateway such as LiteLLM or TrueFoundry.

SettingWhereNotes
Gateway Base URLStandards → Settings → Claude ProviderRequired, and must start with https://
Disable experimental betasStandards → Settings → Claude ProviderFor gateways that reject Anthropic beta headers
Opus / Sonnet / Haiku modelsStandards → Settings → Claude ProviderOptional model names to pin, as exposed by your gateway
Gateway Auth TokenOperations → Settings → Secrets (anthropic_gateway_auth_token)Delivered to workers as ANTHROPIC_AUTH_TOKEN
Gateway Custom HeadersOperations → Settings → Secrets (anthropic_gateway_custom_headers)Optional. One Name: value per line, passed unchanged as ANTHROPIC_CUSTOM_HEADERS. Write-only, because headers often carry credentials

Changing the provider takes effect on the next worker redeploy. Cloud’s own platform features, such as the Mayor and draft assist, use Colony’s key unless an administrator turns on Mayor routing on Operations → Settings. With it on, they go through your provider, including your gateway, and never fall back to Colony’s key.

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

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

FieldConfig keyUnitDefaultDescription
Max cost per issueclaude.max_cost_per_issueUSDnoneColony halts the task when this per-issue ceiling is reached. Set to 0 or leave blank for no limit.
Daily cost capmax_daily_usdUSD$50Read-only here. Administrators change the daily cost cap in Budgets, with a reason; the page shows $50 (default) until a value is stored. All pipeline work halts when the effective ceiling is reached and resumes at the next UTC midnight.
Budget headroombudget_headroom_pct%10Share of the daily cost cap held back to absorb overage from concurrent Workers. The effective daily ceiling is max_daily_usd × (1 − pct/100), so $45 with the defaults.
Daily ceiling commentdaily_ceiling_comment—OffPost a comment on the most recently updated open item when the daily cost ceiling halts work.
Calibration lookbackcalibration.lookback_daysdays7Days of issue history the analyzer uses to calibrate complexity estimates. Leave blank for the default.

The monthly tenant ceiling and per-repo caps aren’t set here. Set them in Operations → Settings (/operations/settings); see Cost & Budget and Dashboards.

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.

TierFieldConfig keyDescription
small / medium / largeModelclaude.scaling.<tier>.modelOverride the Claude model for this tier. Leave blank to use the global model setting.
small / medium / largeEffortclaude.scaling.<tier>.effortReasoning effort level: low, medium, high, or max. Higher effort uses more tokens but produces better results on complex tasks.
small / medium / largeDeveloper max turnsclaude.scaling.<tier>.developer_max_turnsMaximum 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.

Controls which issues Colony picks up for processing.

FieldConfig keyValuesDefaultDescription
Intake modeagents.sprint_master.intake_modeall | taggedtaggedall processes every new issue automatically; tagged processes only issues that carry the Colony intake label.

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

FieldConfig keyUnitDefaultDescription
Heartbeat intervalworkers.heartbeat_intervalseconds—Seconds between Worker heartbeat pings to the Colony Cloud API.
Max task retriesworkers.max_task_retriescount—Maximum consecutive failures for a repo + issue + task-type combination within 60 minutes before the task is permanently dropped.
Max task durationworkers.max_task_durationminutes45Wall-clock deadline per task. Workers abort and fail the task if it exceeds this limit.
Stale task thresholdworkers.stale_task_thresholdminutes3Minutes 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.
Warm repos per workerworkers.max_cached_reposcount4Repositories each multi-repo (pool) Worker keeps warm at once. Applies to multi-repo Workers only; takes effect when replicas restart.
Clone cache budgetworkers.max_cache_disk_mbMBNo limitDisk budget for a multi-repo Worker’s warm clones. Applies to multi-repo Workers only; takes effect when replicas restart.
Mirror budgetworkers.max_mirror_disk_mbMBNo limitDisk budget for a multi-repo Worker’s shared object mirror. Applies to multi-repo Workers only; takes effect when replicas restart.
Toolchain budgetworkers.max_toolchain_disk_mbMBNo limitDisk budget for a multi-repo Worker’s mise toolchain directory. When exceeded, tool versions no warm repo needs are uninstalled, oldest first. Applies to multi-repo Workers only; takes effect when replicas restart.
Max in-flight tasks per repoworkers.max_in_flight_per_repocount2Most tasks one repository can have running across a multi-repo Worker at once. Applies to multi-repo Workers only; takes effect when replicas restart.
Cold repo escapeworkers.cold_repo_escape_minutesminutes30Minutes a task waits for a Worker that already has its repository warm before any Worker may take it and clone it cold. Applies to multi-repo Workers only; takes effect when replicas restart.

Controls how the final epic PR review fixes small findings itself. Changes to Epic Execution require a worker redeploy.

FieldConfig keyUnitDefaultDescription
Auto-fix thresholdepic.review.auto_fix_thresholdminor | noneminorSeverity of findings Colony may fix in-session on the final epic PR. none escalates every finding.
Auto-fix line capepic.review.auto_fix_max_changed_lineslines150Maximum added plus removed source lines an in-session auto-fix may change on the final epic PR. Test and documentation lines don’t count. A larger diff is reverted and the epic is approved with the minor findings as polish. Blank means 150.
Max remediation cyclesepic.review.max_remediation_cyclescount—Maximum remediation cycles for the final epic review.
FieldConfig keyDefaultDescription
How Colony merges a changemerge.methodBlankmerge, squash or rebase. Blank sends no method, so the code host merges with a merge commit. Applies to every repository in the organization, so repositories that allow different methods cannot all be satisfied. Epic changes into the default branch always merge-commit.

Two branches can merge cleanly as text and still break each other. One PR renames a config key while another adds a consumer of the old name, for example. When enabled, Colony analyzes concurrent changes to semantically coupled files before merging and defers the later PR for re-review. This differs from Conflict Resolution, which resolves git text conflicts.

FieldConfig keyDefaultDescription
Enabledmerge.semantic_conflict_check.enabledOffOpt-in. Colony changes nothing about merging until you turn it on.
Min confidence (0–1)merge.semantic_conflict_check.min_confidence0.75Colony defers the later PR when the assessment’s confidence meets or exceeds this value. Lower values catch more conflicts and raise more false positives.
Max candidate branchesmerge.semantic_conflict_check.max_candidate_branches10Most open branches Colony compares against. Raise it for repos with many parallel contributors.
Lookback (hours)merge.semantic_conflict_check.lookback_hours24How far back Colony looks for recently merged branches when building the candidate set.
Model overridemerge.semantic_conflict_check.modelBlankClaude model for the assessment. Blank uses the global merger model.

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 Operations → Settings.
  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.

This page edits the tenant-level (tenants.config) layer. A few settings can also be set for a repository group or a single repository: workflow, standards set, the analyzer, developer and reviewer models, review checks, timeout per check, required CI checks, CI check timeout, intake mode, auto-merge and the setup timeout, plus setup commands and dependency updates on the repository. For those, the most specific level wins: repository, then groups by rank, then tenant, then Colony’s built-in default. Everything else on this page applies to the whole tenant. See Repo Settings.

ActionRequired role
View org pipeline configurationOwner or Admin
Save org pipeline configurationOwner or Admin

Both GET and PUT /api/orgs/:orgId/pipeline/config require the tenant-administrator grant (org-pipeline-config-read and org-pipeline-config-update). Without it, the tenant view of Standards → Settings shows the page inert and names the grant.

MethodPathAccessDescription
GET/api/orgs/:orgId/pipeline/configOwner or AdminFetch the current org-level pipeline configuration.
PUT/api/orgs/:orgId/pipeline/configOwner or AdminSave the org-level pipeline configuration.