PT EN
Install

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

SectionWhat for
t25Name, state directory, worktrees directory, maximum time per task, retries, whether plan approval is required.
repositoryThe repository the T25 operates on and the default branch worktrees are cut from.
projectsOther local checkouts registered, to operate more than one repository.
routingPipeline role → chain of CLIs, in order of preference.
skillsReplaces the skills list of a specific role.
timeoutsMinute limit per role; any role left out uses the global limit.
limitsGuardrails against loops and runaway agents.
riskRisk level → how much the T25 automates.
teamTeam mode: knowledge map by area, single-person alert and reviewer rotation. Off by default.
live_docsLive documentation instruction for dev and QA. It does not yet give the agent a tool (#444 open).
sandbox_imageThe Docker image for the dev roles when the level calls for a sandbox.
githubIssue import and pull request creation.
serverPort, API keys and, optionally, login through GitHub or OIDC.
cost and observabilityCost accounting per run and telemetry.
control_planeDatabase 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 }
LevelWhat changes
lowOpens the pull request without a plan gate.
mediumRequires plan approval.
highRequires plan and pull request approval.
criticalAlways 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.

KeyDefaultEffect
t25.auto_approve_specfalseSigns 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_approvaltrueGlobal plan gate. It only applies to risks whose approval is not none.
projects[].requirePlanApprovalabsent (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[].planApprovalLowRiskabsentMakes 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: falseInstitutional 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_decisionsenabled: false, mode: shadowSemantic 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

Next CLI: operate T25 from the command line →