TRWDocumentation

Integration Guide

Already have a project? This guide adds TRW to your existing codebase. For new projects, see the Quickstart.

Works with any language or framework. Install takes under 15 minutes regardless of project size.

Prerequisites

Requirement	Version	Check
Python	3.10+ (3.11+ recommended)	python --version
pip	22.0+	pip --version
Claude Code CLI	latest	claude --version
git	2.30+	git --version

Setup Steps

Install trw-mcp

terminal

# Create a virtual environment (recommended)
python -m venv .venv
source .venv/bin/activate

# Install the MCP server package
pip install trw-mcp

# Optional: LLM-augmented features
pip install trw-mcp[ai]

Bootstrap the project

terminal

# Run from your project root
trw-mcp init-project .

Configure .trw/config.yaml

terminal

# Required fields for trw_build_check
source_package_path: "src/your_package"
source_package_name: "your_package"
tests_relative_path: "tests"

Verify installation

terminal

# Start Claude Code
claude

# In Claude Code:
# 1. Session-start hook fires automatically
# 2. Call trw_session_start()
# 3. Call trw_status()

What Bootstrap Creates

.trw/config.yaml-- Project configuration
.trw/learnings/-- Persistent learning storage
.trw/logs/-- Debug and event logs
.mcp.json-- MCP server registration
.claude/hooks/-- Lifecycle hook scripts

Verification Checklist

which trw-mcp returns a path
.trw/config.yaml exists in your project root
.mcp.json contains a "trw" entry
.claude/hooks/session-start.sh exists and is executable

First Session Test

A successful first trw_session_start() in an existing project looks like this:

Claude Code session

> trw_session_start()

Session started (run_id: abc-123)
Phase: PLAN
Learnings loaded: 0          # Normal for first session
Config: .trw/config.yaml
Hooks: 4 registered
Tools: 24 available

# Test the learning loop:
> trw_learn(summary="Integration verified", detail="TRW installed and tools responding")
> trw_recall("integration")
# Should return the learning you just created

Tip

Zero learnings on first session is expected. After a few sessions with trw_learn() calls, future sessions surface relevant context automatically.

Monorepo Integration

Scoping with task_root

Set task_root in .trw/config.yaml to scope TRW to a specific package.

# Scope to a specific package
task_root: "packages/api"
source_package_path: "packages/api/src"
tests_relative_path: "packages/api/tests"

Multi-Package Projects

Use a shared .trw/ at the repo root (recommended) so learnings from one package benefit work in another. Alternatively, run trw-mcp init-project . in each package for independent tracking.

CI/CD Integration

.github/workflows/ci.yml

name: CI
on: [push, pull_request]
jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-python@v5
        with:
          python-version: '3.11'
      - run: pip install trw-mcp[dev] -e ".[dev]"
      - run: python -m pytest tests/ --cov --cov-fail-under=80
      - run: python -m mypy --strict src/your_package/

MCP Server Configuration

Claude Code

The .mcp.json file registers TRW with Claude Code:

{
  "mcpServers": {
    "trw": {
      "command": "trw-mcp",
      "args": ["--debug"]
    }
  }
}

OpenCode beta

The opencode.json file registers TRW with OpenCode. The installer auto-generates this when it detects OpenCode on your system.

{
  "mcp": {
    "trw": {
      "type": "local",
      "command": ["trw-mcp"],
      "args": ["--debug"],
      "enabled": true
    }
  }
}

OpenCode supports local models via Ollama — your code never leaves your machine. TRW adapts its ceremony to shorter nudges for local model context budgets.

How It Connects

Each CLI instance spawns its own trw-mcp process via stdio. Your learnings, ceremony state, and configuration live in .trw/ — shared across all CLIs in the same project.

Multi-CLI Comparison

TRW works with multiple AI coding tools. Each uses a different config file, but all share the same .trw/ project state.

CLI	Config file	Ceremony mode	Hooks
Claude Code	`.mcp.json`	Full (200K context)	supported
OpenCode	`opencode.json`	Light (32K context)	not yet
Cursor	`.cursor/mcp.json`	Full (128K context)	not yet

Custom Extensions

Custom Skills

Create a directory with a SKILL.md file in data/skills/. Auto-discovered at runtime.

data/skills/your-skill/SKILL.md

Custom Agents

Create a .md file with frontmatter in data/agents/. Auto-discovered at runtime.

data/agents/your-agent.md

Custom Hooks

Create a .sh file in data/hooks/. Register in .claude/settings.json.

data/hooks/your-hook.sh

Updating TRW

terminal

# Update the package
pip install --upgrade trw-mcp

# Update project files (preserves your config)
trw-mcp update-project .

The update command selectively updates framework files while preserving your config and accumulated learnings.

Next Steps

Troubleshooting

Solutions for common integration issues

Tools

All 24 MCP tools and when to use them

Configuration

Customize TRW for your project

Requirements Troubleshooting