Codex in Orca

Codex is OpenAI's agentic CLI. Orca's Codex integration is one of the deepest in the app — usage, hot-swap, and restart all preserve account identity.

Setup

  1. Install Codex per OpenAI's docs.
  2. Log in from any terminal.
  3. Orca reads ~/.codex for accounts and credentials.

Launching

Pick Codex from the agent combobox. Orca launches codex with the worktree as cwd and routes auth through the currently selected account.

Account hot-swap

Many Codex users run multiple accounts to stretch rate limits. Orca's account switcher swaps the active account without re-login or config edits. See Hot-swap Codex accounts.

System default vs extra accounts

System default uses your real ~/.codex login (the same home a bare codex outside Orca would use). Extra accounts Orca manages get their own home under Orca's account data so credentials and rollouts stay isolated. New Codex launches follow the active account. Open Codex chats move to it before their next message; already-running terminal sessions keep the home they started with until you restart them.

Wrapper scripts that set CODEX_HOME

Orca installs its status hooks in the home each launch uses: ~/.codex for System default, or the account's own home for extra accounts (passed as CODEX_HOME). If a codex wrapper earlier on your PATH always exports a different CODEX_HOME, Codex reads a home Orca didn't set up: status hooks never fire and account switching has no effect. To keep a custom home:

  • Make the wrapper respect a home that is already set, so extra accounts keep working:

    export CODEX_HOME="${CODEX_HOME:-$HOME/.codex-openai}"
  • Make ~/.codex point at your custom home (ln -s ~/.codex-openai ~/.codex, after moving any existing ~/.codex aside), so System default and the wrapper read the same folder.

Nested Task subagents

When Codex spawns Task subagents, Orca can show them as child rows under the parent agent on the worktree agent list and Agent Dashboard. Expand the chevron to see each child; click a child to focus the parent terminal (subagents do not own a separate pane).

Hand off to another agent

From an agent terminal's header or context menu, choose Hand off to agent. Orca starts a fresh agent session (same or different CLI) and injects a bounded handoff prompt from the prior transcript or captured context. The original session is left alone — this is not codex resume.

Restart chip

When Codex exits, the restart chip relaunches the agent with the same account. If you swapped accounts mid-session and want to restart with the new one, use the account switcher first, then restart.

Usage & rate limits

Orca fetches Codex usage for the active account with your existing Codex login and surfaces it in the status bar. See Usage & rate-limit tracking.

Codex on Windows (WSL)

On Windows, Orca can run Codex either from your host install or from a WSL distro. Add a WSL-hosted Codex account from the account switcher — Orca creates an isolated account home inside the distro (under ~/.local/share/orca/codex-accounts/<id>/home), maps it back to the host as a \\wsl.localhost\<distro>\... path for auth reads, and routes launches, hot-swap, and rate-limit fetches through the selected distro. If Codex isn't installed in the target distro, the Add account dialog fails with an actionable message telling you which distro is missing the binary.