Client guide
Set up TRW for Codex CLI
Merge TRW into Codex’s native config, verify the MCP server before working, and opt into project hooks only when you are ready to inspect and trust them.
Support model
Native surfaces, explicit authority
Codex supports project-scoped MCP servers, durable AGENTS.md guidance, repository skills, custom agents, and trusted-project hooks. TRW writes into those surfaces, but none of them turns advisory copy into proof that work passed.
Connection
Project MCP
Codex starts trw-mcp over stdio from the trusted project configuration.
Guidance
Instructions + skills
Small durable rules stay visible; richer workflows load only when matched.
Enforcement
Tool gates first
Hooks can prompt or block at lifecycle edges; delivery still depends on recorded evidence and configured gates.
Installation
Merge into an existing project
trw-mcp init-project . --ide codexBefore running
Confirm the target repository and inspect any existing .codex/, AGENTS.md, and skill files.
The guided installer can select the same Codex target. Initialization smart-merges supported config, preserves recognized user-owned entries, and writes managed files. It is still a mutation: review the resulting diff rather than assuming an idempotent run cannot change content.
Generated surface map
Know what owns each behavior
.codex/config.tomlInspect
- TRW behavior
- Merges the trw stdio MCP server, enabled tool list, instruction path, Codex skills, and OpenAI docs MCP when absent
- Boundary
- Preserves other normalized config entries; review the generated diff
.codex/INSTRUCTIONS.mdInspect
- TRW behavior
- TRW-specific workflow guidance referenced by the generated Codex config
- Boundary
- Guidance is advisory; tool gates remain authoritative
AGENTS.mdInspect
- TRW behavior
- Portable repository guidance for build, test, review, and operating conventions
- Boundary
- Keep durable project rules concise and place narrower files near their code
.codex/agents/*.tomlInspect
- TRW behavior
- Four current custom agents: explorer, implementer, reviewer, and docs researcher
- Boundary
- Agents are optional delegation surfaces, not background workers
.agents/skills/Inspect
- TRW behavior
- Twenty-five current Codex skill packages with progressive, task-matched loading
- Boundary
- A skill runs when requested or matched; installing it does not run it automatically
.codex/hooks.jsonInspect
- TRW behavior
- Five TRW-managed lifecycle hooks, written only when [features].hooks is already enabled
- Boundary
- Trusted-project review is still required; hooks are additive guidance and enforcement adapters
| Surface | TRW behavior | Boundary |
|---|---|---|
.codex/config.toml | Merges the trw stdio MCP server, enabled tool list, instruction path, Codex skills, and OpenAI docs MCP when absent | Preserves other normalized config entries; review the generated diff |
.codex/INSTRUCTIONS.md | TRW-specific workflow guidance referenced by the generated Codex config | Guidance is advisory; tool gates remain authoritative |
AGENTS.md | Portable repository guidance for build, test, review, and operating conventions | Keep durable project rules concise and place narrower files near their code |
.codex/agents/*.toml | Four current custom agents: explorer, implementer, reviewer, and docs researcher | Agents are optional delegation surfaces, not background workers |
.agents/skills/ | Twenty-five current Codex skill packages with progressive, task-matched loading | A skill runs when requested or matched; installing it does not run it automatically |
.codex/hooks.json | Five TRW-managed lifecycle hooks, written only when [features].hooks is already enabled | Trusted-project review is still required; hooks are additive guidance and enforcement adapters |
Current counts come from the shipped Codex bootstrap: four agent templates and 25 skill directories. Generic root scaffolding may also exist, but Codex’s MCP registration lives in .codex/config.toml, not .mcp.json.
First verified run
Verify before relying on memory
Optional hooks
Opt in before generation
The bootstrap does not detect hook support and silently fall back. It checks the existing project config for [features].hooks = true; only then does it merge five TRW-managed hook groups into .codex/hooks.json.
# .codex/config.toml
[features]
hooks = trueThen review in Codex
Re-run project update, open /hooks, and review SessionStart, UserPromptSubmit, PreToolUse, PostToolUse, and Stop before approval.
Troubleshooting
Diagnose the owning layer
trw tools are missing
Run codex mcp list, inspect .codex/config.toml, and verify the configured command resolves in the Codex environment. Use /mcp in the TUI for current server state.
TRW guidance is missing
Confirm AGENTS.md is in scope and the generated config points its model instruction file at INSTRUCTIONS.md. Restart or reload after config changes.
hooks.json was not written
Enable [features].hooks in the existing project config before rerunning the Codex bootstrap. Support is not inferred from a version string.
A custom agent is not selected
Agent files make roles available; they do not run automatically. Ask Codex to delegate explicitly or put bounded delegation guidance in the applicable AGENTS.md or skill.
Codex MCP configuration is shared by local Codex clients on the same host. Review the official MCP guide for current CLI and config options.