TRWDocumentation

Quickstart

Install TRW and see your first knowledge-compounding session in under 5 minutes. By the end, you will have an AI that remembers what it learned — and proves it in session 2.

Prerequisites

Requirement	Version	Install	Verify
Python	3.10+ (3.11+ recommended)	brew install python / apt install python3	`python3 --version`
pip	22.0+	python -m pip install --upgrade pip	`pip --version`
AI Coding CLI	latest	Claude Code, OpenCode, or Cursor	`claude --version or opencode --version`
git	2.30+	brew install git / apt install git	`git --version`

Installation

Recommended: one-liner install

Run this in your project directory. The installer downloads TRW, detects your AI coding tool, and writes all config files automatically.

terminal

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

expected output

  [TRW] Checking Python...
  ✓ Python 3.12 (python3)
  [TRW] Installing trw-mcp...
  ✓ trw-mcp installed
  [TRW] Initializing TRW in current project...
  ✓ Project initialized

  Authenticate now? [Y/n] y

  ✓ Browser opened — approve the request to continue
  Verify this code matches: WDJB-MJHT

  ✓ Authenticated as you@example.com
  ✓ Organization: my-org
  ✓ API key saved

  TRW Framework installed successfully!

Authentication is optional — TRW works fully offline. Connect anytime later with trw-mcp auth login. For CI/CD, pass --api-key or set TRW_API_KEY.

Alternative: manual install

If you prefer manual setup or need to customize the installation, install the packages directly and bootstrap the project yourself.

terminal

# Install packages
pip install trw-mcp trw-memory

# Bootstrap your project (run from project root)
cd /path/to/your/project
trw-mcp init-project .

# Start your AI coding tool
claude

This writes .mcp.json, .trw/, and .claude/ into your repo. Commit them so your team shares the same setup.

Your first session

This walkthrough shows a realistic first session — starting TRW, doing work, recording a discovery, verifying the build, and delivering. Then starting a second session to prove the knowledge persisted.

Start the session

Open your AI coding tool and ask it to start a TRW session. It calls trw_session_start() which loads prior learnings and checks for interrupted runs.

session 1 — start

> trw_session_start()

TRW Session Started
  Run ID:     run_a1b2c3d4
  Phase:      RESEARCH
  Learnings:  0 loaded (first session — knowledge starts here)
  Config:     .trw/config.yaml

Ready. Describe your task and TRW will guide the workflow.

Do some work

Work on your task as usual. TRW does not change how you write code — it adds structure around it. Ask your AI to implement a feature, fix a bug, or refactor. TRW tracks the phase and saves checkpoints.

session 1 — work

You: "Add rate limiting to the /api/users endpoint"

Agent: I'll implement this. Let me save a checkpoint first.

> trw_checkpoint(message="Starting rate limiter implementation")

[implements rate limiter in src/middleware/rate_limit.py]
[writes tests in tests/test_rate_limit.py]

Record a discovery

During implementation, the agent discovers something worth remembering. It calls trw_learn() to persist the finding for future sessions.

session 1 — learning

> trw_learn(
    summary="Rate limiter is per-process, not per-deployment",
    detail="Redis-backed limiter needed for multi-instance. Local
            dict-based limiter only works for single-process dev."
  )

Learning saved
  ID:       learn_x7y8z9
  Impact:   medium (auto-scored)
  Recall:   will surface in sessions about rate limiting, Redis, scaling

Verify the build

Before delivering, the agent runs build verification — pytest, type checking, and coverage. This is the gate that prevents false completion.

session 1 — verify

> trw_build_check(scope="full")

Build Check PASSED
  Tests:    142 passed, 0 failed
  Mypy:     clean (0 errors)
  Coverage: 89% (threshold: 80%)

All gates passed. Ready to deliver.

Deliver

The agent calls trw_deliver() which persists all learnings, syncs CLAUDE.md, and closes the run. Nothing is lost.

session 1 — deliver

> trw_deliver()

Delivery Complete
  Learnings:   1 new, 0 updated
  CLAUDE.md:   synced (behavioral protocol current)
  Analytics:   session scored, ceremony compliance 94%
  Run:         closed (run_a1b2c3d4)

Session ended. Your discoveries are persisted for next time.

Start session 2 — the knowledge compounds

This is the moment that matters. A new session starts. A new context window. But the knowledge from session 1 is already loaded — the agent starts smarter than it was yesterday.

session 2 — knowledge recalled

> trw_session_start()

TRW Session Started
  Run ID:     run_e5f6g7h8
  Phase:      RESEARCH
  Learnings:  1 loaded (1 relevant to current project)
  Recalled:
    - "Rate limiter is per-process, not per-deployment"
      (medium impact, from session run_a1b2c3d4)

You: "Scale the rate limiter for multi-instance deployment"

Agent: Based on the learning from the previous session, I know the
current rate limiter is per-process and won't work across instances.
I'll implement a Redis-backed solution directly — no need to
rediscover this limitation.

That is knowledge compounding. Session 2 starts where session 1 left off — not from zero.

Verify your installation

Run these checks to confirm TRW is correctly installed. All four should pass.

Check	Command	Expected
trw-mcp is on PATH	`which trw-mcp`	Returns a path (e.g. /home/you/.local/bin/trw-mcp)
.trw/config.yaml exists	`ls .trw/config.yaml`	File exists in your project root
MCP config has TRW entry	`grep trw .mcp.json`	Shows the "trw" server entry
CLAUDE.md contains TRW section	`grep "TRW Behavioral Protocol" CLAUDE.md`	Shows the auto-generated protocol section

Troubleshooting

MCP tools not available

Verify .mcp.json (Claude Code) or opencode.json (OpenCode) exists and contains a "trw" entry. Run which trw-mcp to confirm the binary is on PATH. Restart your AI coding tool to reconnect MCP.

trw_build_check fails with "path not found"

Set source_package_path, source_package_name, and tests_relative_path in .trw/config.yaml. These tell TRW where your source code and tests live.

Session interrupted, work lost

Start a new session — trw_session_start() auto-detects active runs and resumes from the last checkpoint. Use trw_status() to see exactly where you left off.

Hooks not firing

Check that .claude/settings.json has hook registrations. Run chmod +x .claude/hooks/*.sh to ensure scripts are executable.

Info

WSL2 cold starts take 15-20 seconds on first MCP connection. This is normal. Subsequent calls are fast. If tools disappear mid-session, run /mcp to reconnect.

Next steps

You have a working TRW installation with your first learning persisted. Here is where to go deeper.

Core Concepts

Understand sessions, runs, learnings, the flywheel, and how knowledge compounds over time

Lifecycle Phases

Deep dive into the 6-phase workflow, adaptive ceremony tiers, and quality gates

Tools Reference

All 24 MCP tools — what each does, when to use it, and common patterns

Getting Started Core Concepts