Why does TRW ask me to sign in during install?

Current installs roll out through a gated approval flow. Approved users sign in or reuse an issued API key so the installer can download the full setup.

Can one repo be configured for more than one client?

Yes. The Python installer now prompts first-time users with a multi-select client chooser so one repo can target several client surfaces at once.

What should I verify after install?

Confirm trw-mcp is on PATH, .trw/config.yaml exists, target_platforms reflects the clients you chose, and the expected client-specific instruction files or configs were written.

What if my session is interrupted?

Open a new session and call trw_session_start(). TRW recovers active runs automatically, and trw_status() shows the last checkpoint so work resumes instead of restarting.

Docs

Quickstart

Review the current access flow, run the installer, choose your client surfaces, verify the setup, and start your first retained-context workflow. The goal is simple: wire the repo once, then let every later session inherit better context than the last one had.

Fast path

Step 1

Request or confirm access

Current installs roll out through a gated beta. Approved users can authenticate during install or reuse an existing API key.

Step 2

Run the bootstrap

The shell bootstrap installs trw-mcp, downloads the full Python installer, and starts guided setup in your project root.

Step 3

Select your client surfaces

On first install, the Python installer now prompts you with a multi-select TUI so one repo can be wired for multiple clients at once.

Step 4

Verify and start

Confirm the generated files, open one configured client, call trw_session_start(), and finish with trw_deliver().

Prerequisites

Requirement	Version	Install	Verify
Python	3.10+ (3.11+ recommended)	brew install python / apt install python3	python3 --version
pip	22.0+	python3 -m pip install --upgrade pip	python3 -m pip --version
git	2.30+	brew install git / apt install git	git --version
AI coding client	latest stable available to you	Claude Code, Cursor IDE, Cursor CLI, OpenCode, Codex CLI, GitHub Copilot CLI, Gemini CLI, or Aider	Run your client’s version command or open the repo in the client you plan to use

Installation

Run the bootstrap from the project root after approval or with an existing API key. The shell bootstrap installs trw-mcp, authenticates if needed, downloads the full Python installer, and writes the repo-local config automatically.

shell bootstrap

curl -fsSL https://trwframework.com/install.sh | bash

On first install, the Python installer now opens a guided client picker so you can wire this repo for more than one surface in the same pass.

installer client selection

Select the client surfaces you want TRW to configure

[x] Claude Code
[x] Cursor IDE
[ ] Cursor CLI
[ ] OpenCode
[x] Codex CLI
[ ] GitHub Copilot CLI
[ ] Gemini CLI
[ ] Aider

Use ↑/↓ to move • Space to toggle • Enter to confirm

Supported clients

The installer writes different instruction surfaces depending on what you select. You do not need to change clients to adopt TRW — choose the ones you already use in this repo, and TRW translates the same core workflow into each supported surface.

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

Verification

Check	Command	What success looks like
trw-mcp is on PATH	`which trw-mcp`	Returns a path such as /home/you/.local/bin/trw-mcp
.trw/config.yaml exists	`ls .trw/config.yaml`	The repo-local config file exists
Selected target_platforms were written	`grep -n "target_platforms" -A8 .trw/config.yaml`	Shows every client surface you selected during install
At least one client config exists	`ls .claude .cursor .codex .github .gemini AGENTS.md 2>/dev/null`	One or more client-specific files or directories now exist in the repo

Your first session

Start the session

Loads prior learnings and recovers an active run if the work was interrupted.

trw_session_start()

Do the work

Checkpoint whenever you cross a milestone so the session can recover instead of restart.

trw_checkpoint("rate limiter merged, tests next")

Record a discovery

If you learn something the next session should not rediscover, persist it while the context is fresh.

trw_learn(summary="Cursor CLI needs .cursor/cli.json permissions baseline", detail="...")

Close the loop

Verify the work and persist the session state before you leave the task.

trw_build_check(scope="full")
trw_deliver()

Slash commands

Slash commands are shorthand invocations that wrap multi-step TRW workflows. Typical order in a working session: trw_session_start() at the top, do the work, then /trw-commit after each logical unit and /trw-deliver before you stop. For new work, lead with /trw-prd-ready or /trw-sprint-init to get a groomed plan before implementation.

/trw-sprint-init

Initialize a sprint from draft PRDs — creates the sprint doc and run directory.

/trw-prd-ready

Full PRD lifecycle in one command: create, groom, review, refine, execution plan.

/trw-learn

Record, update, or retire a learning without breaking flow.

/trw-commit

Convention-enforced git commit — analyzes changes and generates type(scope) message.

/trw-deliver

Persist your session’s work so future agents inherit your discoveries.

/trw-sprint-finish

Close a sprint: validates deliverables, runs build gate, updates PRDs.

/trw-framework-check

Check ceremony adherence, phase gate status, and active run health.

/trw-ceremony-guide

Load the full ceremony reference: tool lifecycle, execution phases, examples.

See the full skills catalog for every slash command, including internal phases and read-only audits.

If something feels off

Need deeper debugging? Head to troubleshooting for client-specific startup issues, install errors, and runtime recovery steps.

Next: learn the model

Once the repo is wired, spend five minutes on the concepts page so the session, run, learning, and ceremony model feels obvious before the first serious task.

Read Core Concepts