TRWConfiguration

Docs

Configuration

TRW works with sensible defaults, but one setting matters more than any other on modern installs: target_platforms. That list tells TRW which client surfaces to write, update, and keep in sync for this repo.

Precedence

Environment variables (TRW_*) override .trw/config.yaml, which overrides built-in defaults and profile-derived behavior. Use env vars for CI and secrets. Use the config file for repo-level behavior.

Common config changes

Target more than one client

If one repo needs Claude Code, Cursor IDE, and Codex, list them all under target_platforms. TRW syncs the matching instruction surfaces for each selected client.

Point build-check at your code

Set source_package_name, source_package_path, and tests_relative_path when the defaults do not match your repo layout.

Connect to the hosted platform only when you want to

Platform sync is optional. Local runs, checkpoints, and learnings work without it. Add platform_url and platform_api_key only when you need hosted features.

Client profiles

The installer selects these profiles for you, but you can always edit target_platforms later. Full profiles expose more automation. Light profiles prefer smaller instruction surfaces and fewer ceremony defaults.

Client	Ceremony	What TRW writes	Automation	Best fit
Claude Code Best-understood end-to-end profile for local, hook-heavy TRW workflows.	Full	CLAUDE.md, .claude/INSTRUCTIONS.md, .claude/hooks/, .mcp.json	Deepest local hook, skill, and agent-team surface	Users who want the fullest TRW surface in one CLI
Cursor IDE Full TRW surface tuned for Cursor’s IDE-native rules and automation.	Full	.cursor/rules/, .cursor/mcp.json, .cursor/hooks/, .cursor/skills/	IDE rules plus translated hooks, commands, skills, and subagents	Interactive editor-first workflows inside Cursor
Cursor CLI A lighter profile for headless Cursor runs where explicit permissions matter.	Light	AGENTS.md, .cursor/cli.json, .cursor/hooks.json, .cursor/mcp.json	Headless-safe permissions and CLI hook subset	cursor-agent, CI, and scripted terminal workflows
OpenCode Instruction-first TRW integration with OpenCode-native commands and agents.	Light	opencode.json, .opencode/INSTRUCTIONS.md, .opencode/commands/, .opencode/agents/	Curated commands, agents, and instruction-first guidance	Lean terminal workflows with curated TRW surfaces
Codex CLI A light TRW profile shaped around Codex’s workflow and context constraints.	Light	.codex/config.toml, .codex/INSTRUCTIONS.md, .codex/agents/, optional .codex/hooks.json	Codex-specific config, agents, curated skills, optional hooks	Codex users who want tighter context and lighter ceremony defaults
GitHub Copilot CLI Full TRW support translated into Copilot’s GitHub-first surfaces.	Full	.github/copilot-instructions.md, .github/instructions/, .github/hooks/, .github/agents/	Repo instructions, path-scoped guidance, hooks, agents, and skills	GitHub-native repos adopting agent workflows and path-scoped guidance
Gemini CLI Full TRW support adapted to Gemini’s native instruction and subagent surfaces.	Full	GEMINI.md, .gemini/settings.json, .gemini/agents/	Gemini-native instructions, MCP config, and subagents	Very large-context sessions and Gemini-native agent work
Aider A light TRW profile for users who want compounding context without heavy scaffolding.	Light	AGENTS.md and .aider/instructions.md-compatible guidance	Instruction-first, low-ceremony integration	Minimal terminal workflows that still need durable project memory

Claude Code

Best-understood end-to-end profile for local, hook-heavy TRW workflows.

Ceremony: Full

What TRW writes: CLAUDE.md, .claude/INSTRUCTIONS.md, .claude/hooks/, .mcp.json

Automation: Deepest local hook, skill, and agent-team surface

Best fit: Users who want the fullest TRW surface in one CLI

Cursor IDE

Full TRW surface tuned for Cursor’s IDE-native rules and automation.

Ceremony: Full

What TRW writes: .cursor/rules/, .cursor/mcp.json, .cursor/hooks/, .cursor/skills/

Automation: IDE rules plus translated hooks, commands, skills, and subagents

Best fit: Interactive editor-first workflows inside Cursor

Cursor CLI

A lighter profile for headless Cursor runs where explicit permissions matter.

Ceremony: Light

What TRW writes: AGENTS.md, .cursor/cli.json, .cursor/hooks.json, .cursor/mcp.json

Automation: Headless-safe permissions and CLI hook subset

Best fit: cursor-agent, CI, and scripted terminal workflows

OpenCode

Instruction-first TRW integration with OpenCode-native commands and agents.

Ceremony: Light

What TRW writes: opencode.json, .opencode/INSTRUCTIONS.md, .opencode/commands/, .opencode/agents/

Automation: Curated commands, agents, and instruction-first guidance

Best fit: Lean terminal workflows with curated TRW surfaces

Codex CLI

A light TRW profile shaped around Codex’s workflow and context constraints.

Ceremony: Light

What TRW writes: .codex/config.toml, .codex/INSTRUCTIONS.md, .codex/agents/, optional .codex/hooks.json

Automation: Codex-specific config, agents, curated skills, optional hooks

Best fit: Codex users who want tighter context and lighter ceremony defaults

GitHub Copilot CLI

Full TRW support translated into Copilot’s GitHub-first surfaces.

Ceremony: Full

What TRW writes: .github/copilot-instructions.md, .github/instructions/, .github/hooks/, .github/agents/

Automation: Repo instructions, path-scoped guidance, hooks, agents, and skills

Best fit: GitHub-native repos adopting agent workflows and path-scoped guidance

Gemini CLI

Full TRW support adapted to Gemini’s native instruction and subagent surfaces.

Ceremony: Full

What TRW writes: GEMINI.md, .gemini/settings.json, .gemini/agents/

Automation: Gemini-native instructions, MCP config, and subagents

Best fit: Very large-context sessions and Gemini-native agent work

Aider

A light TRW profile for users who want compounding context without heavy scaffolding.

Ceremony: Light

What TRW writes: AGENTS.md and .aider/instructions.md-compatible guidance

Automation: Instruction-first, low-ceremony integration

Best fit: Minimal terminal workflows that still need durable project memory

Example config

.trw/config.yaml

task_root: docs
runs_root: .trw/runs
build_check_coverage_min: 90.0
source_package_name: trw_mcp
source_package_path: trw-mcp/src/trw_mcp
tests_relative_path: trw-mcp/tests

target_platforms:
  - "cursor-ide"
  - "codex"
  - "gemini"

platform_url: "https://api.trwframework.com"
platform_api_key: "{TRW_PLATFORM_API_KEY{'}'}"
platform_telemetry_enabled: false

The installer rewrites this file carefully. If you re-run install after choosing a new client mix, TRW updates target_platforms without clobbering the rest of your repo-local configuration.

Core fields

Field	Type	Default	What it controls
target_platforms	list[str]	["claude-code"]	The client surfaces TRW should keep in sync for this repo. The installer writes your selection here on first run.
response_format	"yaml" \| "json"	profile-derived	MCP response format. Full IDE profiles often use JSON for tool wiring; others prefer YAML.
task_root	str	docs	Root directory used for PRDs and run artifacts.
build_check_coverage_min	float	85.0	Minimum coverage required for build-check pass/fail.
platform_url	str	""	Primary hosted platform endpoint for sync and telemetry.
platform_urls	list[str]	[]	Additional platform endpoints. The installer preserves line breaks before appending this block.
platform_api_key	SecretStr	""	API key used for hosted platform auth. Prefer env vars in CI.
platform_telemetry_enabled	bool	false	Allow telemetry to be sent to the hosted platform when configured.
auto_recall_min_score	float	0.7	Minimum score for auto-injected learnings during session-start and phase changes.

target_platforms

Type: list[str]

Default: ["claude-code"]

What it controls: The client surfaces TRW should keep in sync for this repo. The installer writes your selection here on first run.

response_format

Type: "yaml" | "json"

Default: profile-derived

What it controls: MCP response format. Full IDE profiles often use JSON for tool wiring; others prefer YAML.

task_root

Type: str

Default: docs

What it controls: Root directory used for PRDs and run artifacts.

build_check_coverage_min

Type: float

Default: 85.0

What it controls: Minimum coverage required for build-check pass/fail.

platform_url

Type: str

Default: ""

What it controls: Primary hosted platform endpoint for sync and telemetry.

platform_urls

Type: list[str]

Default: []

What it controls: Additional platform endpoints. The installer preserves line breaks before appending this block.

platform_api_key

Type: SecretStr

Default: ""

What it controls: API key used for hosted platform auth. Prefer env vars in CI.

platform_telemetry_enabled

Type: bool

Default: false

What it controls: Allow telemetry to be sent to the hosted platform when configured.

auto_recall_min_score

Type: float

Default: 0.7

What it controls: Minimum score for auto-injected learnings during session-start and phase changes.

Environment variable overrides

Variable	Maps to	Use it for
TRW_TARGET_PLATFORMS	target_platforms	Override selected clients with a JSON list such as ["cursor-ide","codex"].
TRW_TASK_ROOT	task_root	Override where PRDs and run artifacts are stored.
TRW_BUILD_CHECK_COVERAGE_MIN	build_check_coverage_min	Override the build gate coverage threshold.
TRW_PLATFORM_URL	platform_url	Override the primary platform URL.
TRW_PLATFORM_API_KEY	platform_api_key	Inject the platform API key without writing it into the repo.
TRW_RESPONSE_FORMAT	response_format	Force yaml or json regardless of the client profile default.

TRW_TARGET_PLATFORMS

Maps to: target_platforms

Use it for: Override selected clients with a JSON list such as ["cursor-ide","codex"].

TRW_TASK_ROOT

Maps to: task_root

Use it for: Override where PRDs and run artifacts are stored.

TRW_BUILD_CHECK_COVERAGE_MIN

Maps to: build_check_coverage_min

Use it for: Override the build gate coverage threshold.

TRW_PLATFORM_URL

Maps to: platform_url

Use it for: Override the primary platform URL.

TRW_PLATFORM_API_KEY

Maps to: platform_api_key

Use it for: Inject the platform API key without writing it into the repo.

TRW_RESPONSE_FORMAT

Maps to: response_format

Use it for: Force yaml or json regardless of the client profile default.

Sharp edge to remember

When installer code updates platform_urls, it must preserve line breaks before appending YAML. That prevents malformed config files and subtle MCP startup failures in clients like Codex.

Next: tools and troubleshooting

Once configuration feels clear, learn which tools the runtime actually calls and how to debug client-specific setup issues.

Tool Reference Troubleshooting

Troubleshooting API Reference

Configuration

Common config changes

Target more than one client

Point build-check at your code

Connect to the hosted platform only when you want to

Client profiles

Example config

Core fields

Environment variable overrides

Sharp edge to remember

Next: tools and troubleshooting

Tune TRW for your repo, client surface, and deployment shape.