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 preserve the decisions and evidence later sessions would otherwise lose.
Fast path
01
Open the project root
Start in the repository you want TRW to configure. Your source tree and existing client stay in place.
02
Run the bootstrap
One shell command installs trw-mcp and starts guided setup.
03
Sign in and choose clients
Approve the device when prompted, then select every AI surface this repository already uses.
04
Verify and start
Confirm the generated files, open one configured client, and start a small real session.
Prerequisites
- Requirement
- Python
- Version
- 3.10+ (3.11+ recommended)
- Install
- brew install python / apt install python3
- Verify
- python3 --version
- Requirement
- pip
- Version
- 22.0+
- Install
- python3 -m pip install --upgrade pip
- Verify
- python3 -m pip --version
- Requirement
- git
- Version
- 2.30+
- Install
- brew install git / apt install git
- Verify
- git --version
- Requirement
- AI coding client
- Version
- latest stable available to you
- Install
- Use one of the installer-supported clients listed below
- Verify
- Run your client’s version command or open the repo in the client you plan to use
| 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 | Use one of the installer-supported clients listed below | Run your client’s version command or open the repo in the client you plan to use |
Installation
Run one command from the project root. The bootstrap installs trw-mcp, opens device sign in when needed, and starts the guided setup. CI can pass an existing API key instead.
curl -fsSL https://trwframework.com/install.sh | bashAuthenticate
Create an account or approve the device when prompted.
Choose clients
Select every supported surface used in this repository.
Write config
Review the repo-local files before opening your client.
Select clients during setup
The guided installer presents the current profiles below; the retired entry after them is listed for reference only and cannot be selected. Choose the surfaces already used by this repository; detailed file mappings belong in the configuration reference, not in the critical install path.
Installer profile preview
During setup, you can select one client or several. This preview is not interactive.
Claude Code
Hooks & agents
Cursor IDE
IDE-native
Cursor CLI
Headless-safe
OpenCode
Command-first
Codex CLI
Codex-native
GitHub Copilot CLI
GitHub-native
Antigravity CLI
Antigravity-native
Aider
The Aider target was retired because it never had a native adapter. Current installation rejects the identifier.
Not sure? Pick the client you will open immediately after installation. You can rerun the installer later without replacing your source code.
Compare profilesVerification
- Check
- trw-mcp is on PATH
- Command
which trw-mcp- What success looks like
- Returns a path such as /home/you/.local/bin/trw-mcp
- Check
- .trw/config.yaml exists
- Command
ls .trw/config.yaml- What success looks like
- The repo-local config file exists
- Check
- Selected target_platforms were written
- Command
grep -n "target_platforms" -A8 .trw/config.yaml- What success looks like
- Shows every client surface you selected during install
- Check
- At least one client config exists
- Command
ls .claude .cursor .codex .github .opencode .antigravitycli ANTIGRAVITY.md AGENTS.md opencode.json 2>/dev/null- What success looks like
- One or more client-specific files or directories now exist in the repo
| 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 .opencode .antigravitycli ANTIGRAVITY.md AGENTS.md opencode.json 2>/dev/null | One or more client-specific files or directories now exist in the repo |
Run your first session
Do one small, real task. The first session should prove that TRW can start, preserve a useful checkpoint, record a discovery, and close with validation evidence.
- 01
Start the session
Loads prior learnings and recovers an active run if the work was interrupted.
trw_session_start() - 02
Do the work
Checkpoint whenever you cross a milestone so the session can recover instead of restart.
trw_checkpoint("Milestone reached; tests next") - 03
Record a discovery
If you learn something the next session should not rediscover, persist it while the context is fresh.
trw_learn( summary="What changed", detail="Why it matters later" ) - 04
Close the loop
Run the project-native checks first, then record each actual command result before you persist the session state.
npm test npm run type-check trw_build_check(command_results=[ {"command_id": "tests", "label": "npm test", "command_class": "test", "exit_code": 0}, {"command_id": "static_checks", "label": "npm run type-check", "command_class": "static", "exit_code": 0} ]) trw_deliver()
If something feels off
Need deeper debugging? Head to troubleshooting for client-specific startup issues, install errors, and runtime recovery steps.
Hit a bug or have feedback? Run the /trw-feedback skill or call trw_submit_feedback to send it straight to the maintainer - PII is redacted before it leaves your machine.
When you need more control