Reference
Configuration.
Almost everything that changes T25's behavior lives in t25.yaml at the root: agent routing, limits, risk, GitHub, authentication. This page is the map of the sections; the field-by-field reference is docs/CONFIGURATION.md.
Shallow merging happens by section, not by nested key. A section present in YAML replaces the default at that level. It is not deep-merged. Declared routing? Declare the roles you want, because missing roles do not come back from the default.
Secrets do not belong in versioned YAML. A URL do banco vem de
DATABASE_URL, a credencial de worker vem de
T25_WORKER_CREDENTIAL, e os segredos de OAuth vêm do ambiente. Um valor
committed value is an incident, not a typo.
The sections
| Section | What for |
|---|---|
t25 | Name, state directory, worktrees directory, maximum time per task, retries, whether plan approval is required. |
repository | The repository the T25 operates on and the default branch worktrees are cut from. |
projects | Other local checkouts registered, to operate more than one repository. |
routing | Pipeline role → chain of CLIs, in order of preference. |
skills | Replaces the skills list of a specific role. |
timeouts | Minute limit per role; any role left out uses the global limit. |
limits | Guardrails against loops and runaway agents. |
risk | Risk level → how much the T25 automates. |
team | Team mode: knowledge map by area, single-person alert and reviewer rotation. Off by default. |
live_docs | Live documentation instruction for dev and QA. It does not yet give the agent a tool (#444 open). |
sandbox_image | The Docker image for the dev roles when the level calls for a sandbox. |
github | Issue import and pull request creation. |
server | Port, API keys and, optionally, login through GitHub or OIDC. |
cost and observability | Cost accounting per run and telemetry. |
control_plane | Database and artifact store. The URL always comes from the environment. |
Routing: a chain, not a fixed CLI
This is the concept most likely to cause confusion. Each role receives an ordered list, and T25 uses the first CLI available on the machine. It is not a quality choice or a lottery: it is the first door that opens.
routing: triage: [kimi, claude, codex] planner: [claude, codex, kimi] research: [kimi, claude] dev-frontend: [claude, kimi, codex] dev-backend: [codex, claude, kimi] qa-frontend: [claude, kimi] qa-backend: [codex, claude, kimi] reviewer: [claude, codex, kimi] security: [claude, codex] docs: [kimi, claude, codex] release: [claude, codex]
There are twelve roles, and every list must be a non-empty array. An empty list or the wrong type is rejected at load time, not discovered during execution. The available CLI adapters are claude, codex, kimi, gemini, grok, opencode, cursor, pi and vibe; mock is the test adapter.
Risk: how far it runs on its own
risk:
low: { approval: none, sandbox: docker }
medium: { approval: plan, sandbox: docker }
high: { approval: plan_and_pr, sandbox: docker }
critical: { approval: human_required, sandbox: docker }
| Level | What changes |
|---|---|
low | Opens the pull request without a plan gate. |
medium | Requires plan approval. |
high | Requires plan and pull request approval. |
critical | Always requires human intervention. |
No level automates the merge. The risk configuration controls how far T25 goes without asking before the pull request. The merge is always yours, through the cockpit or CLI. Briefing approval at SPEC is mandatory at every level, except the t25.auto_approve_spec key, which ships off (see the approvals section below).
The default isolates the stage. The code, t25 init and this repository's t25.yaml use sandbox: docker at all four levels. sandbox: none is an explicit escape: the agent runs on the host with the worker environment, and Claude uses --dangerously-skip-permissions when T25_CLAUDE_SKIP_PERMISSIONS is unset. On a shared machine, run the worker as a dedicated user or VM, without personal secrets, or set T25_CLAUDE_SKIP_PERMISSIONS=0 so Claude only accepts file edits (acceptEdits).
A chore task without an explicit --risk uses low. This is the deliberate adoption path: upgrades, CVEs and lint, with verifiable criteria and a low cost of error.
Approvals: spec, plan and merge
These are the keys that decide where T25 stops and waits for a person. The names are those of t25.yaml; per-project keys live inside each projects entry.
| Key | Default | Effect |
|---|---|---|
t25.auto_approve_spec | false | Signs the spec on its own when its risk is low or medium, as long as there is no spec gate, no open comment and no missing acceptance criterion. high and critical stay manual. |
t25.require_plan_approval | true | Global plan gate. It only applies to risks whose approval is not none. |
projects[].requirePlanApproval | absent (inherits the global flag) | Project overlay: true keeps the gate when the global flag is off; false removes the gate when it is on. |
projects[].planApprovalLowRisk | absent | Makes the plan gate apply to low risk too, which has approval: none. It only takes effect while the gate is on. |
delegation (and projects[].delegation) | enabled: false | Institutional delegation per action: merge, approve-spec, approve-plan and apply-improvement. Turning delegation on and promoting an action does not take the person out of the merge: the pipeline does not call the delegated merge execution. |
semantic_decisions | enabled: false, mode: shadow | Semantic decisions layer (JEV). It ships off, with provider fake, send_code: false (only accepts false) and routing: manual. It also has a per-project overlay, with enabled and routing. |
Limits: the brake
limits: max_runtime_minutes: 60 max_queue_attempts: 5 max_failed_commands: 8 max_same_error_retries: 2 max_files_changed: 40 max_diff_lines: 2000 max_duplicate_line_ratio: 0.5
The first two in the second half are the guardrail against an agent that decides to rewrite the world: limits on changed files and diff lines, checked after implementation. If either is exceeded, the task fails. max_duplicate_line_ratio catches excessive copy-paste and is the only one that turns itself off in bootstrap mode, where legitimate repetition would create a false positive.
Authentication
API keys work without extra configuration and are the path for scripts and the CLI. Human login through GitHub or OIDC is optional: when enabled, it requires a session secret and the complete configuration for one of the two providers. Authorized users start declared in YAML and move to a local overlay after the first cockpit edit. There is no user database. A GitHub access token is never persisted, and removing someone from the list revokes their session on the next request.
Before you change anything
- Run
t25 doctor: it fails onerrorchecks. Missing Docker,psqlorweb/distproduce warnings. - A reference to a role or skill that does not exist is rejected at load time. The error appears on startup, not in the middle of a task.
- No secrets in versioned YAML. None.