Codex

Configure Codex in Happier, including the default App Server backend, installables, local control, and resume behavior.

This page documents how Happier integrates with Codex and what Codex-specific behavior matters for day-to-day usage.

Install Codex

Happier can install it for you:

happier install provider codex

Or install it yourself, then restart Happier:

npm install -g @openai/codex
codex --version

Local authentication in Happier

Codex supports machine-local auth management in:

Settings → AI & Agents → AI backends → Codex

From there you can:

see whether Codex is logged in on the selected machine
see whether Happier detected CLI login or OPENAI_API_KEY
open codex login directly inside Happier
use Check now after logging in outside Happier

For the shared user guide, see Provider authentication.

Authentication (subscriptions and API keys)

Codex can authenticate through Happier connected services:

OpenAI Codex subscription (openai-codex): OAuth via device code, paste redirect URL, or in-app browser on native
OpenAI API key (openai): manual key entry

In the app:

Settings → Connected services → OpenAI (Codex)

In the CLI:

# Subscription auth (recommended): device code flow
happier connect codex --device

# Headless fallback: paste the redirect URL
happier connect codex --paste

# API key mode
happier connect codex --api-key

Notes:

Device auth can require enabling “device code authorization for Codex” in ChatGPT settings.
If you connect multiple profiles, you can choose which one to use when starting a new session.
On web, Happier uses device or paste flows. Embedded OAuth is native-only.

Codex-connected-service selection can also affect session browsing and the Resume session picker. See:

Session handoff

Codex supports Happier session handoff as an experimental capability.

What that means in practice:

the handoff action can move the same Happier session id to another machine
Codex continuity can work across machines when the destination is ready
the feature is less mature than Claude or OpenCode handoff

Practical guidance:

prefer Claude or OpenCode when you want the most stable cross-machine handoff today
keep Codex authenticated and ready on the destination machine
use connected services when possible to reduce machine-local auth friction

See:

Backends and local control

Happier can run Codex using different backends depending on what’s available and what features you enable:

Codex App Server (default): the recommended and default path for normal Codex sessions in Happier. It supports the app-first workflow, local/remote switching, and vendor resume when the session metadata is available.
Codex ACP: still available as an explicit fallback when you switch Codex to ACP mode.
Codex MCP: still available for fresh sessions, but plain MCP is not the default or normal vendor-resume path in current Happier builds.
Local-control: Happier can switch a session into a “local control” mode that mirrors Codex activity (useful when moving control from the app back to your terminal).

Important Codex behavior:

Happier defaults Codex to App Server
old mcp_resume behavior is gone
if App Server is unavailable for a new session, the default Codex launch fails instead of silently falling back; choose ACP or MCP explicitly if you want a different backend
local/remote switching and normal Codex resume work on the default App Server path

If you manually switch Codex to plain mcp in settings, new sessions can still run, but vendor resume is not available on that plain MCP path.

With the App Server backend, Codex uses shared local control with Codex CLI 0.131.0 or newer on macOS and Linux. Happier and the Codex TUI connect to the same running app-server thread, so the app remains writable and can continue handling approvals while the TUI is attached. If a turn is already active, the normal Happier input flow waits before starting the next app turn.

This shared-control flow starts with a Happier session. If you started a thread directly in Codex CLI, Happier cannot join its running app-server by resuming that thread in a separate process: Codex keeps one active writer for the thread. To use both interfaces for a new session, start it in Happier and run happier attach on the same machine.

Windows, ACP sessions, and App Server sessions using an older Codex CLI keep the existing exclusive local-control flow. Happier waits for a safe turn boundary before moving those sessions between the app and the terminal.

Codex model availability depends on the active Codex backend, installed runtime, and account state. The new-session engine picker can show the currently available Codex models, model-specific options such as reasoning effort, and favorite Codex model shortcuts when those models are available for the selected backend.

For the full model guide, see:

Model and engine selection

For the full user-facing MCP guide in Happier, see:

MCP servers

Codex ACP installables behavior

Codex ACP depends on a machine-local Codex ACP installable.

Happier exposes that in:

Machine Details → Installables

This matters for two reasons:

cold start performance — a preinstalled Codex ACP binary avoids first-run install/setup delay
ACP-mode reliability — if you explicitly choose ACP, keeping Codex ACP installed avoids install-time waits and missing-capability errors

Default behavior

For the managed Codex ACP installable, Happier defaults to:

Auto-install when needed: on
Auto-update: auto

If you select the Codex ACP backend for a new session and Codex ACP is missing, Happier can install it in the background so that later sessions on that machine start more reliably and with less startup overhead.

Important distinction: new sessions vs resume

For a new Codex session:

Happier can install Codex ACP in the background when policy allows it
later ACP sessions on that machine benefit from having the installable ready ahead of time

For resume in ACP mode:

Codex ACP must already be available
Happier does not silently replace resume with a fresh session

If you want predictable Codex resume while using ACP on a machine, keep Codex ACP installed there and leave automatic updates enabled unless you have a specific reason not to. If you stay on the default App Server path, this ACP installable is not required for normal resume.

Full guide: Installables.

Start in Happier, continue in the terminal

Codex supports Happier’s attach flow for app-started sessions:

start the session from the Happier app,
let it run remotely in the background on your machine,
later run happier attach <session-id> from a terminal on that same machine,
switch into local control when you want to use Codex’s terminal UI directly.

You can later switch back to remote control and keep using the same session from Happier.

Local control starts from the terminal. Use happier attach <session-id> on the owning machine.

On supported Codex CLI versions with App Server, app messages and approvals stay available while the Codex TUI is attached. Both clients use the same running thread. On the older exclusive path, app messages use the pending queue until Happier can safely resume remote processing.

The shared App Server path uses Codex’s native local socket attach on macOS and Linux. It does not require a terminal host. In current development builds, selecting Herdr (or another supported host) for new sessions starts the Codex TUI there automatically against that same App Server thread; selecting no host leaves the server-backed session headless until you attach.

For the end-to-end workflow, see Features → Attach to a running session.

Resume inactive Codex sessions

Codex resume in Happier normally uses the default App Server path. ACP resume still works when you explicitly choose ACP.

An inactive Codex session can be resumed when:

the session has valid Codex resume metadata
the current backend/machine combination supports resume for that session (App Server by default, or ACP when explicitly selected)
any required machine dependency for the selected resume path is already installed

From the CLI, use:

happier resume

or:

happier resume <session-id>

From the app/web UI, inactive Codex sessions are resumable only when those same checks pass.

Resume is strict: Happier does not silently replace a failed Codex resume with a fresh Codex session.

Permissions and modes

Happier uses a provider-agnostic permission intent (read_only, default, auto, yolo) and applies it to Codex in the best available way.

For the full user guide (CLI flags, UI picker, defaults, apply timing), see:

What permission modes mean in Codex

Codex enforcement is a combination of:

Happier tool-approval gating (what Happier will auto-approve vs deny vs prompt for), and
provider-native sandbox/policy (what the Codex backend enforces internally).

Important notes:

Read-only is enforced by Happier by denying write-like actions (edits/patches/exec) when Happier is the approver.
Auto and YOLO control whether Happier prompts vs auto-approves actions it can approve.
On a Codex app-server that rejects granular Auto approvals under a managed policy but allows on-request, Happier retries once with on-request and keeps the workspace sandbox. That session then sends approval requests to you for review; its Auto review behavior is unavailable. If Codex also rejects on-request, the session reports the policy error.
Codex backends may have sandbox policies that are fixed at session start. Changing permission mode mid-session can still update Happier’s approval behavior, but it may not change Codex’s internal sandbox until you start a new Codex session.

Plan mode

Plan is a session mode, not a permission mode, and Codex reaches it differently from Claude.

Claude's plan mode is provider-native, so Happier gives it a dedicated control. Codex's modes arrive over ACP from the running Codex app-server, so what is available is whatever that build advertises for the session — plan among them. You select it from the Mode control rather than a plan-specific toggle.

Because the list comes from the runtime, Happier shows the Mode control only when the current Codex backend and session actually advertise modes. If they do not, the control is hidden rather than offering a mode that would fail.

Happier keeps the older spelling working: --permission-mode plan maps to --agent-mode plan.

Code review

Codex can run a review through its own review API rather than by being asked in prose, which produces structured findings instead of a paragraph.

Start one inline with:

/codex.review

Happier's own review entry point uses the same path where the request can be represented safely. Findings come back normalized, so they render as a review card in the transcript rather than as free text, and entering and leaving review show up as transcript events.

Where the running Codex build does not offer the review API, Happier reports the method as unsupported rather than silently falling back to an ordinary prompt that would look like a review but not be one.

For marking up a diff yourself and sending those notes to an agent — any agent, not just Codex — see Review comments.

Switching and permission persistence

When you change permission mode:

it is stored canonically in session metadata, and
it follows you when you open the same session on another device or switch local ↔ remote.

If you choose Apply timing: next prompt in the app:

the selection applies to the next message you send (as message metadata), and
it becomes session-wide only after that message is committed.

Agent capabilities — what this agent supports, generated from the manifest.
Choosing an agent
Model and engine selection
Agent authentication

On this page