Coordinator: Codex

Codex depth is MCP-grade, deliberately: a generated config.toml MCP server block, an optional generated subagent, and steering that rides Codex's own resume rail - no bespoke wrapper or watcher process. This is the narrowest of the three coordinator front-ends, because it's what Codex primitives support today. Revisit this page when Codex ships a real steering channel or live push, not before.

Connect local Codex

This integration is for local Codex CLI, IDE extension, and ChatGPT desktop clients on the same machine. It requires Codex 0.149 or later and the Rensei CLI. Rensei configures Codex's native OAuth support and starts the browser login for you.

First create a named user context through the browser login, activate it, and select its default organization and project:

rensei auth add --user --name codex-acme
rensei auth activate codex-acme
rensei setup

rensei setup opens the organization and project selector. The generator pins the selected user context and writes those organization and project values as static MCP headers, so later changes to your active CLI context do not silently change an existing Codex connection.

Then install the integration:

rensei codex install

The command performs four operations as one lifecycle: it provisions or reuses your durable requester registration, assigns your stable codex-… A2A handle, safely updates the Rensei-owned block in ~/.codex/config.toml, and runs Codex's native CIMD browser login. Start a new Codex session afterward and use /mcp to confirm that rensei is connected.

Auth: native OAuth, no exported token

The managed config uses only Codex-supported OAuth fields:

[mcp_servers.rensei]
url = "https://app.rensei.ai/api/cli/mcp"
auth = "oauth"
oauth_resource = "https://app.rensei.ai/api/cli/mcp?registration_id=rreg_..."
scopes = ["dispatch:invoke", "code-intel:read", "a2a:invoke", "spawn:invoke"]
http_headers = { "X-Rensei-Org" = "acme", "X-Rensei-Project" = "website" }

The browser login still authenticates you through the Rensei platform. Codex owns the resulting OAuth access and refresh tokens in its credential store. Rensei saves only the identity, origin, tenant scope, registration id, A2A handle, resource, and scope names. No WorkOS bearer or OAuth token is exported to your shell, written to config.toml, or stored in Rensei metadata.

The OAuth resource binds the browser grant to your exact requester registration. The platform fetches and validates the callback-specific Codex client metadata document, binds it to Codex's loopback callback, and verifies that the signed-in user owns the registration. A different platform origin, registration, callback id, client document, or user is refused. If a project is selected, its canonical id is also stored as the registration's authorization fence; changing or removing the static project header cannot widen the token into another project.

Manage the lifecycle

rensei codex status
rensei codex update
rensei codex uninstall

When you run install or update, Rensei also migrates the exact historical static-token entry below to the canonical rensei OAuth server:

[mcp_servers.rensei-platform]
url = "https://app.rensei.ai/api/cli/mcp"
bearer_token_env_var = "RENSEI_API_TOKEN"

Only that exact block is removed automatically. If the old entry has been edited, extended, reformatted, or appears more than once, Rensei preserves the file and stops with manual-repair guidance. Inspect ~/.codex/config.toml, resolve the conflicting [mcp_servers.rensei-platform] entry, then rerun rensei codex install or rensei codex update. The managed server created by the current lifecycle is [mcp_servers.rensei].

status checks the saved binding, the exact managed TOML, Codex server entry, and OAuth state. update reconciles the server-side registration and project/scope fence, updates local configuration, then renews the browser login. uninstall logs Codex out and removes only Rensei's marked TOML block and local profile; it retains the server-side A2A handle so reinstalling preserves your identity and mailbox continuity. If Codex logout fails, local state is retained so cleanup can be retried. rensei codex uninstall --force is the explicit escape hatch when you accept that credentials may remain in Codex's store.

Use rensei codex install --no-login only when you deliberately need to prepare configuration without opening the browser; finish with rensei codex update. Rensei serializes its own config writers and re-checks the source file, but unrelated editors do not share its lock, so don't edit config.toml concurrently with installation.

The older rensei dispatch mcp --client codex generator remains a compatibility preview for an already installed OAuth profile. It no longer emits http_headers_helper; current Codex versions reject a helper that returns the reserved Authorization header. For an API-key or CI integration instead, use Use Rensei from any agent session.

Poll-inbox discipline

Codex has no live push. The pi capability pack's native-wake trick has no Codex equivalent: Codex is a local CLI process with no background listener and no live-injection path. A Codex coordinator, or a Codex child, is never interrupted by an arriving message - it only sees one if it asks.

The generated subagent bakes this discipline into its instructions:

• call a2a_inbox for your own agent handle at the start of every turn, and again before reporting done or going idle;
• on a long-running turn, re-poll every few tool calls, not just once;
• treat an empty inbox as "nothing new right now," not "nothing will ever arrive" - a message sent while you're between turns waits for your next invocation's poll.

If you're hand-writing your own Codex config instead of using the generated subagent, copy this discipline into your own instructions - there is no code-level substitute for it.

Steer-via-resume

What works today, and what doesn't yet: steer_child is real and callable against a Codex child today: it enqueues a message for delivery on the child's next turn. Whether that message reaches a busy child depends on the child's harness:

• Inject-capable harnesses (Claude, for example) get the message injected mid-turn, live.
• Resume-only harnesses - Codex is one of these - the documented fallback is "stop the current session and resume it with the queued content." That fallback is not built yet: injection is attempted and fails cleanly for a resume-only harness, and the runner soft-fails through to a deterministic backstop instead. Codex's own resume capability exists at the provider level, but nothing in production calls it yet - only the conformance test suite does. Building the automatic stop-and-resume fallback is tracked work, informed by this integration but not part of it.

Stated plainly:

• Calling steer_child against a Codex child succeeds at the API layer - you get back an enqueued acknowledgment.
• Whether the child acts on it before its current turn ends is not guaranteed today. Don't build coordinator logic that assumes immediate delivery to a busy Codex child.
• What reliably works right now: let the child reach a natural stop (or cancel it), then dispatch or resume it with the queued context folded into the next prompt yourself. watch_session tells you when a child is between turns.
• Once the automatic fallback lands, steer_child against a resume-only child becomes fully automatic and this caveat goes away - watch this page for the update.

On-platform Codex

An interactive session the platform launched with the Codex harness gets the same automatic MCP tool access an on-platform Claude coordinator does - the swarm/lifecycle tools are already served on the session's own MCP endpoint, with no config.toml to generate and no token to export. Everything above about poll-inbox discipline and the steer-via-resume caveat still applies unchanged - both are properties of the Codex harness itself, not of where the coordinator session happens to run.

Tool vocabulary - treat tools/list as the source of truth

The MCP server serves, subject to your token's scopes and your org's feature flags: the baseline dispatch tools, the swarm/lifecycle family documented in Spawning sub-agents, and the A2A mailbox pack. Tool names and schemas are a wire contract discovered via tools/list - this page names them for orientation, but an older platform deployment may serve a narrower set. Don't hard-code an assumption that every tool named here exists.

Related pages

• Coordinator Overview - comparing this front-end to Claude on- and off-platform
• Spawning sub-agents - the tool vocabulary and refusal codes
• A2A Delivery Tiers - the per-harness honesty model this page's caveats come from
• Use Rensei from any agent session - the general external-facade doc, useful for any MCP-capable harness beyond Codex
• Auth - user contexts, refresh behavior, and context selection