TRWDocumentation

Configuration

TRW works with sensible defaults. Most projects never edit the config. When you need to customize, everything is in one file: .trw/config.yaml

Info

Precedence: Environment variables (TRW_*) override .trw/config.yaml, which overrides built-in defaults. Use env vars for CI/CD and secrets. Use the config file for project-level settings.

Common config changes

Three changes cover 90% of configuration needs. Everything else can stay at defaults.

1. Set coverage threshold

Controls the minimum test coverage required by trw_build_check. Default is 80%.

.trw/config.yaml

coverage_threshold: 0.90  # Require 90% coverage

2. Enable telemetry

Opt-in anonymized telemetry. Sends session duration, tool usage counts, and ceremony scores. No code, no secrets, no PII.

.trw/config.yaml

telemetry_enabled: true

3. Connect to the platform

Syncs learnings, PRDs, and session data to the TRW dashboard. Requires a platform API key.

.trw/config.yaml

platform_url: https://trwframework.com
org_id: your-org-id
# API key set via environment variable — see warning below

All config fields

Field	Type	Default	Description
task_root	str	docs	Root directory for PRDs and run artifacts
coverage_threshold*	float	0.80	Minimum test coverage to pass build gate
telemetry_enabled*	bool	false	Enable anonymized telemetry (opt-in)
platform_url*	str \| None	None	TRW platform URL for learning sync
platform_api_key*	str \| None	None	API key for platform authentication
org_id	str \| None	None	Organization ID for multi-tenant separation
max_learnings_per_recall	int	25	Max learnings returned per recall query
response_format	'yaml' \| 'json'	'yaml'	Output format for MCP tool responses. YAML reduces token overhead ~20%. Per-client-profile defaults: claude-code/opencode → yaml, cursor → json. Override via TRW_RESPONSE_FORMAT env var.
auto_recall_min_score	float	0.7	Minimum relevance score for contextual learning injection via the user-prompt-submit hook
auto_recall_max_tokens	int	100	Maximum tokens for auto-injected learnings per phase change

* Fields most users change. Everything else can stay at defaults.

Environment variables

Every config field can be overridden via environment variables prefixed with TRW_. Recommended for CI/CD and containerized deployments.

Warning

Never commit TRW_PLATFORM_API_KEY to version control. Set it via environment variables or .env files (add .env to your .gitignore).

Variable	Maps to	Description
TRW_TASK_ROOT	task_root	Override task root directory
TRW_COVERAGE_THRESHOLD	coverage_threshold	Override coverage threshold
TRW_TELEMETRY_ENABLED	telemetry_enabled	Enable telemetry via env
TRW_PLATFORM_URL	platform_url	Override platform URL
TRW_PLATFORM_API_KEY	platform_api_key	Set API key via env (recommended for CI)
TRW_ORG_ID	org_id	Override organization ID
TRW_RESPONSE_FORMAT	response_format	Override MCP tool response format ('yaml' or 'json'). Useful in CI or for clients that expect JSON.

Config validation

TRW validates configuration at startup using Pydantic v2. Invalid values produce clear error messages with the field name and expected type.

terminal

> trw_session_start()

# Valid config loads silently. Invalid config shows:
ValidationError: 1 validation error for TRWConfig
coverage_threshold
  Input should be a valid number, unable to parse
  string as a number [type=float_parsing, input_value='high']
    For further information visit
    https://errors.pydantic.dev/2.6/v/float_parsing

Full example

.trw/config.yaml

# Project settings
task_root: docs
coverage_threshold: 0.80

# Platform sync (API key via TRW_PLATFORM_API_KEY env var)
platform_url: https://trwframework.com
org_id: your-org-id

# Optional
telemetry_enabled: false  # opt-in only
max_learnings_per_recall: 25

# Response format (yaml reduces token overhead ~20%)
response_format: yaml  # 'yaml' or 'json'; override via TRW_RESPONSE_FORMAT

# Contextual learning injection (user-prompt-submit hook)
auto_recall_min_score: 0.7   # minimum relevance score for injection
auto_recall_max_tokens: 100  # max tokens injected per phase change

Advanced configuration

Client profiles

TRW adapts ceremony, scoring, and instruction sync per AI coding tool. The active profile is resolved from target_platforms[0] in config. Five built-in profiles:

Profile	Ceremony	Context	Notes
claude-code	Full	200K	Default. Full ceremony, hooks, scoring.
opencode	Light	32K	Reduced ceremony. Skips review scoring.
cursor	Full	128K	Full ceremony, no shell hooks.
codex	Light	32K	Minimal phases. IMPLEMENT + DELIVER only.
aider	Light	32K	Minimal phases. Suppresses framework references.

Ceremony mode override

Override the ceremony mode regardless of client profile. Useful for testing or when you want full ceremony on a light-mode client.

.trw/config.yaml

# Options: full, light, off
ceremony_mode: light

Source package paths

Tell trw_build_check where your source code lives. Defaults auto-detect, but monorepos or non-standard layouts may need explicit paths.

.trw/config.yaml

source_packages:
  - src/backend
  - src/workers
  - lib/shared

Next steps

Troubleshooting

Solutions for common configuration issues

Getting Started

Install TRW and start your first session

Troubleshooting API Reference