Using Codex with T3 Code
Set up OpenAI Codex as your T3 Code provider — install, login, how codex app-server fits in, and why keeping the CLI current prevents most session failures.
Codex was the original target and remains the best-tested integration. If you're evaluating T3 Code and have a choice, start here.
Setup#
npm i -g @openai/codex
codex login
codex --versionThat third command isn't optional ceremony. T3 Code launches this exact binary — if it doesn't respond here, nothing downstream will work.
Then:
npx t3@latestHow the integration works#
Per session, T3 Code runs codex app-server and speaks JSON-RPC over stdio to it. Structured events stream back and become WebSocket messages for the UI.
The implication that matters: the app-server protocol is a compatibility surface between two independently-versioned tools. T3 Code updates nightly; Codex updates on OpenAI's schedule. When they drift, the handshake fails.
The three Codex problems worth knowing#
Session hangs on startup#
Timed out waiting for initialize — outdated Codex CLI. Update it. Full fix →
'codex' not found when it demonstrably exists#
codex --version works in your shell, T3 Code disagrees. PATH inheritance, not a missing binary. Most common on macOS with nvm or Homebrew, and on Windows after a global npm install without re-login. Full fix →
failed to start codex app-server#
Reported on Windows, sometimes as os error 3. Path resolution or spawn failure, often a stale npm global prefix or a broken shim. Also check 127.0.0.1:9234 — Codex uses it for remote connections and a conflict there blocks bootstrap. Full fix →
Codex CLI vs Codex app vs T3 Code#
Three things share the name, which causes real confusion:
| What it is | |
|---|---|
| Codex CLI | The terminal agent. T3 Code requires it |
| Codex app | OpenAI's own GUI for Codex |
| T3 Code | A third-party GUI that drives the Codex CLI |
T3 Code and the Codex app are alternatives to each other; both sit on the CLI. The comparison is on T3 Code vs the Codex app.
Cost#
You pay OpenAI, through whatever your Codex CLI is authenticated with — a subscription or API usage on your key. T3 Code adds nothing. Note that agentic runs consume a lot of tokens: an agent exploring a codebase reads far more than a chat conversation does, so watch usage during your first week.
Getting the most out of it#
- Use worktrees so several Codex threads run in parallel without colliding
- Start on Supervised mode to learn what Codex actually does between messages
- Roll back to a checkpoint rather than arguing with a thread that's gone wrong — it's faster
- Update the CLI weekly, especially if you're on T3 Code nightlies
FAQ#
Do I need the Codex CLI to use T3 Code?#
You need at least one supported provider CLI. Codex is the most mature option and requires npm i -g @openai/codex followed by codex login before T3 Code can start a session.
What is codex app-server?#
It's the server mode of the Codex CLI. T3 Code launches it per session and communicates over JSON-RPC on stdio, translating the structured events it returns into WebSocket messages for the UI.
Why does T3 Code time out waiting for initialize?#
Almost always an outdated Codex CLI whose app-server protocol no longer matches what T3 Code expects. Updating Codex to the latest version resolves it.
Is T3 Code better than the official Codex app?#
They're different trade-offs. T3 Code adds git worktree isolation, a diff viewer, one-click pull requests and support for multiple agents. The Codex app is first-party and tracks Codex features immediately.