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.

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. Each client gets a different mix of instruction files, config, hooks, and agents based on what that surface actually supports.

Client	Support shape	What TRW writes	Support notes	Common workflow
Claude Code End-to-end TRW integration for local CLI workflows that lean on hooks and durable instructions.	Hooks & agents	CLAUDE.md, .claude/INSTRUCTIONS.md, .claude/hooks/, .mcp.json	Hooks, skills, MCP config, and agent-team translation	Local CLI workflows that want repo-native hooks, agents, and guidance
Cursor IDE TRW translated into Cursor’s IDE rules, hooks, MCP config, and editor-first automation.	IDE-native	.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 TRW adapted for headless Cursor runs where explicit permissions and CLI-safe defaults matter.	Headless-safe	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 TRW translated into OpenCode’s instruction, command, and agent surfaces.	Command-first	opencode.json, .opencode/INSTRUCTIONS.md, .opencode/commands/, .opencode/agents/	Curated commands, agents, and instruction-first guidance	Terminal workflows built around commands and repo-local instructions
Codex CLI TRW adapted to Codex’s workflow and context constraints without changing the core loop.	Codex-native	.codex/config.toml, .codex/INSTRUCTIONS.md, .codex/agents/, optional .codex/hooks.json	Codex-specific config, agents, curated skills, optional hooks	Codex sessions that want tighter context control and repo-local guidance
GitHub Copilot CLI TRW translated into GitHub-native repo instructions, hooks, and agent surfaces.	GitHub-native	.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 TRW adapted to Gemini’s native instruction, settings, and subagent surfaces.	Gemini-native	GEMINI.md, .gemini/settings.json, .gemini/agents/	Gemini-native instructions, MCP config, and subagents	Very large-context sessions and Gemini-native agent work
Aider TRW guidance adapted to Aider-compatible instruction surfaces.	Instruction-first	AGENTS.md and .aider/instructions.md-compatible guidance	Instruction-first guidance with repo-local project context	Minimal terminal workflows that still need durable project memory

Claude Code

End-to-end TRW integration for local CLI workflows that lean on hooks and durable instructions.

Support shape: Hooks & agents

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

Support notes: Hooks, skills, MCP config, and agent-team translation

Common workflow: Local CLI workflows that want repo-native hooks, agents, and guidance

Cursor IDE

TRW translated into Cursor’s IDE rules, hooks, MCP config, and editor-first automation.

Support shape: IDE-native

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

Support notes: IDE rules plus translated hooks, commands, skills, and subagents

Common workflow: Interactive editor-first workflows inside Cursor

Cursor CLI

TRW adapted for headless Cursor runs where explicit permissions and CLI-safe defaults matter.

Support shape: Headless-safe

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

Support notes: Headless-safe permissions and CLI hook subset

Common workflow: cursor-agent, CI, and scripted terminal workflows

OpenCode

TRW translated into OpenCode’s instruction, command, and agent surfaces.

Support shape: Command-first

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

Support notes: Curated commands, agents, and instruction-first guidance

Common workflow: Terminal workflows built around commands and repo-local instructions

Codex CLI

TRW adapted to Codex’s workflow and context constraints without changing the core loop.

Support shape: Codex-native

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

Support notes: Codex-specific config, agents, curated skills, optional hooks

Common workflow: Codex sessions that want tighter context control and repo-local guidance

GitHub Copilot CLI

TRW translated into GitHub-native repo instructions, hooks, and agent surfaces.

Support shape: GitHub-native

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

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

Common workflow: GitHub-native repos adopting agent workflows and path-scoped guidance

Gemini CLI

TRW adapted to Gemini’s native instruction, settings, and subagent surfaces.

Support shape: Gemini-native

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

Support notes: Gemini-native instructions, MCP config, and subagents

Common workflow: Very large-context sessions and Gemini-native agent work

Aider

TRW guidance adapted to Aider-compatible instruction surfaces.

Support shape: Instruction-first

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

Support notes: Instruction-first guidance with repo-local project context

Common workflow: 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.

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