Config schema reference
Every field in .trw/config.yaml, its default, and the env var that overrides it. The live source is the Pydantic TRWConfig model — treat this page as a flat view of that model.
File location
The config file lives at .trw/config.yaml at the repo root. It is created by trw-mcp init-project and contains only the overrides you choose — every unspecified field inherits its default.
Precedence (highest wins):
- Environment variables prefixed
TRW_. .trw/config.yamloverrides.- Field defaults declared in
models/config/_fields_*.py.
Unknown keys (in both env and config.yaml) are silently ignored — model_config.extra = "ignore" on the BaseSettings class.
Top-level keys
The flat keys you see in config.yaml are the same as the field names on TRWConfig. A curated list of the keys users touch most often:
| Key | Type | Default | Description |
|---|---|---|---|
| framework_version | str | "v24.6_TRW" | Pinned framework version for this repo. |
| target_platforms | list[str] | ["claude-code"] | Client profiles the installer keeps in sync. First entry resolves the primary client profile. |
| ceremony_mode | "full" | "light" | "full" | Profile-derived when unchanged. light suppresses chatty nudges. |
| response_format | "yaml" | "json" | "yaml" | MCP tool response format. |
| mcp_transport | str | "stdio" | Transport when starting the server. streamable-http for shared-server mode. |
| mcp_host | str | "127.0.0.1" | Bind address when transport is HTTP/SSE. |
| mcp_port | int | 8100 | Bind port when transport is HTTP/SSE. |
| installation_id | str | "" | Installation ID used for telemetry correlation. |
| parallelism_max | int | 10 | Maximum concurrent shards/waves during orchestration. |
| timebox_hours | int | 8 | Total session timebox in hours. |
| task_root | str | "docs" | Root directory for PRDs and task artifacts. |
| runs_root | str | ".trw/runs" | Directory for run artifacts. |
| build_check_enabled | bool | true | Whether trw_build_check gates delivery. |
| embeddings_enabled | bool | false | Enable dense vector embeddings (requires the [vectors] extra). |
| platform_url | str | "" | Primary platform URL for sync and telemetry. |
| platform_api_key | SecretStr | "" | Platform API key. Prefer TRW_PLATFORM_API_KEY in CI. |
Check source for the full list of ~200 fields: trw-mcp/src/trw_mcp/models/config/. Run trw-mcp config-reference for a generated list keyed by env var name.
Sub-configs
Fields on TRWConfig are grouped into domain sub-configs for type-narrowed access (config.build, config.memory, etc.). The sub-config models are defined in _sub_models.py. At the YAML layer they remain flat keys.
build
| Key | Default | Description |
|---|---|---|
| build_check_enabled | true | Run build-check as a delivery gate. |
| build_check_coverage_min | 85.0 | Minimum coverage percentage to pass the gate. |
| build_check_pytest_cmd | null | Override the pytest invocation; null uses the default. |
| build_gate_enforcement | "lenient" | One of strict, lenient, off. |
| mutation_enabled | false | Opt-in mutation testing. |
| auto_checkpoint_tool_interval | 25 | Tool calls between auto trw_checkpoint suggestions. |
memory
| Key | Default | Description |
|---|---|---|
| learning_max_entries | 500 | Cap on total learnings before pruning runs. |
| recall_max_results | 25 | Default result cap for trw_recall. |
| memory_store_path | ".trw/memory/vectors.db" | SQLite database path for the memory store. |
| dedup_skip_threshold | 0.95 | Cosine threshold above which dedupe treats entries as duplicates. |
| dedup_merge_threshold | 0.85 | Cosine threshold above which near-duplicates merge. |
| memory_consolidation_enabled | true | Periodic cluster consolidation of related entries. |
orchestration
| Key | Default | Description |
|---|---|---|
| parallelism_max | 10 | Maximum parallel shards. |
| timebox_hours | 8 | Session timebox. |
| max_research_waves | 3 | Cap on research iteration waves. |
| auto_recall_enabled | true | Auto-inject relevant learnings before tool calls. |
| agent_teams_enabled | true | Gate for Agent Teams. Requires CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 in the client env. |
ceremony
| Key | Default | Description |
|---|---|---|
| nudge_enabled | null | Null defers to profile. Set explicit true/false to force. |
| nudge_urgency_mode | "adaptive" | One of adaptive, always_low, always_high, off. |
| nudge_budget_chars | 600 | Character budget per nudge (clamped 100-2000). |
| phase_gate_enforcement | "lenient" | strict, lenient, or off. |
| cleanup_on_boot | true | Run the stale-pin + stale-run sweep on server startup. |
| run_staleness_hours | 48 | Hours with no activity before a run is sweep-eligible. |
tools
| Key | Default | Description |
|---|---|---|
| tool_exposure_mode | "all" | One of all, core, minimal, standard, custom. |
| tool_exposure_list | [] | Explicit tool names when mode is custom. |
| tool_descriptions_variant | "default" | One of default, minimal, verbose. |
| mcp_server_instructions_enabled | null | Send MCP instructions string; null defers to profile. |
Example config
Trimmed and commented version of the .trw/config.yaml this repo uses today. Every field not listed falls back to its default.
# .trw/config.yaml
framework_version: v24.6_TRW
# Orchestration
parallelism_max: 10
timebox_hours: 8
# Platform sync (optional — local runs work without these)
platform_urls:
- https://api.trwframework.com
- http://localhost:8000
platform_telemetry_enabled: true
installation_id: trw-framework-dev
# MCP transport — this dev repo runs a shared streamable-http server.
# User projects should leave these at defaults (stdio).
mcp_transport: streamable-http
mcp_host: 127.0.0.1
mcp_port: 8100
# Client profiles to keep in sync.
target_platforms:
- claude-code
- cursor-ide
- cursor-cli
- opencode
- codex
- copilot
- gemini
# Memory
embeddings_enabled: true
retrieval_embedding_model: all-MiniLM-L6-v2
# Secrets belong in env vars, not config.yaml. Shown here for completeness.
# platform_api_key: "${TRW_PLATFORM_API_KEY}"
Live copy: .trw/config.yaml.
Env var overrides
Every field on TRWConfig accepts an environment-variable override with the TRW_ prefix. The lookup is case-insensitive; unknown vars are ignored (same policy as unknown YAML keys).
| Pattern | Example variable | Maps to config key |
|---|---|---|
| Scalar | TRW_TASK_ROOT=docs | task_root |
| Number | TRW_BUILD_CHECK_COVERAGE_MIN=90 | build_check_coverage_min |
| Bool | TRW_EMBEDDINGS_ENABLED=true | embeddings_enabled |
| List (JSON) | TRW_TARGET_PLATFORMS=["cursor-ide","codex"] | target_platforms |
| Secret | TRW_PLATFORM_API_KEY=trw_dk_… | platform_api_key |
| Transport | TRW_MCP_TRANSPORT=streamable-http | mcp_transport |
| Port | TRW_MCP_PORT=8181 | mcp_port |
Generator for the full list: trw-mcp config-reference. Prefix configured in _main_fields.py via SettingsConfigDict(env_prefix="TRW_").
Related pages