Codex
Run Codex from Proliferate against connected repositories and reviewable branches.
Codex runs through a pinned codex-acp adapter driving OpenAI's official Codex
CLI, so you get Codex's native behavior with Proliferate's workspace lifecycle
and review surface around it.
Proliferate pins both pieces — the CLI at an exact release, the adapter at an
exact commit — and repairs them at startup, so every session runs a known
version. A codex on your own PATH is left alone; the managed copy wins.
Supported functionality
| Capability | Support |
|---|---|
| Repository workspaces | Attach Codex runs to a local checkout or an isolated worktree with full repo and branch context. Cloud workspaces are coming soon. |
| Access mode | Read-only, auto, or full-access filesystem and execution permission. |
| Reasoning effort | Choose among Low, Medium, High, Xhigh, Max, and Ultra when the selected model and route support them. |
| Fast mode | Request lower-latency processing on supported models and routes. |
| Plan mode | Ask Codex to propose an approach before implementation, independently of access mode. |
| Goals | Hand Codex a standing objective it pursues across turns, tracked in a goal bar. |
| Subagents | Spawn native collaboration child threads, or delegate to a separate session. |
| Review | Inspect generated diffs, the transcript, and command output before merge. |
| Credentials | Sign in with your Codex account, bring an OpenAI API key, or route through the Proliferate Gateway. |
Cloud workspaces are coming soon. The currently available Codex workspace targets are a local checkout and a local worktree.
Modes
Access mode decides how much of the filesystem and shell Codex may touch.
| Mode | What it does |
|---|---|
| Read-only | Codex can read and search the repo, but can't edit files or run state-changing commands. Default. |
| Auto | Codex edits files and runs commands on its own, pausing for approval on riskier actions. |
| Full access | Codex edits files and runs commands without stopping for approval. |
Reasoning effort is separate. The ladder — Low through Ultra — depends on the
model and route, so changing either changes what you see. Fast mode requests
lower-latency processing (Codex's service_tier=fast) without changing the
reasoning level.
The working mode is independent of access mode. Choose Plan when you want Codex to work out an approach and post it as a plan card before implementation; choose the default working mode when you want it to work directly within the selected access permissions.
Plan approval
When Codex runs in plan mode, it posts its plan through the same plan-card flow as every other agent that produces one: an Awaiting approval chip with Reject and Approve buttons. See Claude Code's plan approval walkthrough for how the card behaves. After approval you continue with Run here in the current session, or hand the plan to a fresh New session.
Goals
Like Claude, Codex supports a standing goal it pursues across turns. Set one from the composer's Set a goal affordance, and a slim goal bar above the composer tracks the objective until it's met, blocked, stopped, or cleared. Proliferate mirrors Codex's own native goal state, so the bar reflects what Codex is actually working toward.
Codex goals differ from Claude Code goals in a few ways:
- Pause and resume are native. Put a goal on hold without clearing it, then pick it back up later.
- Edits steer the running turn. Change the objective mid-turn and Codex works toward the new text immediately, rather than from the next turn.
- The token budget is optional. Codex reports tokens and time used either
way; a goal that exhausts an attached budget ends in Codex's
budgetLimitedstate. - No evaluator reason or iteration count. A finished Codex goal reports its status and usage; those details are Claude-specific.
Subagents
Codex can spawn its own collaboration child threads inside a session — native subagents that show up in the session's activity roster.
The Codex protocol exposes only lifecycle and activity information for those children, so the transcript shows that a child started, what it is doing, and when it finished — not its full prose, its reasoning, or its inner tool stream. When you need a readable, reviewable transcript of the sub-task, hand it to a separate Proliferate session instead; see Parallel agents.
Authenticate Codex
From Settings -> Agents -> Codex you can:
- Leave every configured source disabled to reuse your existing ChatGPT or
Codex login. Select CLI login; Authenticate appears when
codex loginis needed. - Select API key, then paste your own OpenAI key or bind one already
saved in your vault; Proliferate wires it in as
OPENAI_API_KEYfor you. See your own API key. - Turn on the Proliferate Gateway for managed access with no setup at all.
Cloud workspaces and their separate authentication surface are coming soon.
An admin can restrict which managed routes members may newly configure; see Managed model gateway. For routes, BYOK, and gateway details shared across harnesses, see Authentication.