Set up TRW for Codex CLI

Adopt TRW inside Codex sessions that want tighter context control and repo-local guidance, without changing your core coding loop.

Prerequisites

Codex CLI installed and on your PATH. Confirm with your build’s version flag.
Python 3.10+ (3.11+ recommended) and pip 22+.
A git repository you can write to — TRW writes repo-local files only.

Install

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

When the installer prompts for target clients, select Codex CLI. The bootstrap installs trw-mcp, runs the Python installer, and writes a Codex-specific surface into the repo.

What the installer writes

.codex/config.toml — Codex profile that registers trw-mcp and any Codex-specific toggles.
.codex/INSTRUCTIONS.md — the durable instruction surface Codex reads every session. Encodes the TRW tool lifecycle so it survives context compaction.
.codex/agents/ — translated specialist agents from the TRW roster that map onto Codex session roles.
.codex/hooks.json (optional) — written only when your Codex build reports hook support. Otherwise TRW enforces ceremony via the instruction file.
.trw/config.yaml — repo-local TRW config listing Codex in target_platforms and recording install state.

Run your first session

From the project root, start Codex the way you normally would — for most builds that is simply codex. On startup Codex loads .codex/INSTRUCTIONS.md, which tells the model to begin with trw_session_start().

trw_session_start() — loads prior learnings and any active run state.
Do the work. Checkpoint after each milestone so you can resume after compaction.
trw_learn(summary, detail) whenever you discover a non-obvious gotcha.
trw_build_check() then trw_deliver() to persist state for the next session.

Differences from Claude Code

Hook coverage is partial. Codex hook support depends on your build; when hooks are unavailable, TRW relies on instructions to carry ceremony, not automated triggers. Check your Codex release notes for the current state of hook support.
Agent teams are a subset. Not all 12 Claude Code specialists translate cleanly to .codex/agents/. Expect the core roster (research, implementer, reviewer, auditor, groomer) plus any specialists your Codex version can host.
No .mcp.json. Codex registers trw-mcp through .codex/config.toml instead.
Skills are curated. TRW ships a focused slash-skill set for Codex rather than the full Claude Code catalog.

Common problems

Next steps

Core concepts

Sessions, runs, learnings, and the ceremony loop that TRW enforces on every client.

See the flagship profile

Claude Code is the reference integration — use it to understand the full surface.

Workflows overview

The six-phase lifecycle your Codex sessions will run through.