Add OpenAI Codex CLI as a backend

[kovtcharov-amd]

Summary

Add Codex (@openai/codex) as a third backend alongside Claude Code and OpenCode, allowing users to orchestrate Codex agents from Claudia.

Why

Codex CLI is the second-largest terminal coding agent (75K+ stars, 3M+ weekly users). Users who work across both ecosystems would benefit from managing Codex tasks in the same orchestrator. Claudia already has a CodeBackend abstraction and a working OpenCode backend, making this a natural extension.

Scope

1. CodexBackend implementation (~backend)

Create backend/src/backends/codex-backend.ts implementing CodeBackend.

Codex is PTY-based like Claude Code (interactive TUI), so this backend would closely mirror ClaudeCodeBackend:

Concern	Claude Code	Codex	Delta
Spawn command	claude / node cli.js	codex	New spawn resolution (npm global, brew)
Approval modes	--permission-mode	--sandbox + --ask-for-approval	Map Claudia's permission settings to Codex flags
Model selection	--model claude-sonnet-4-...	--model gpt-5.4	Pass through; different model namespace
Working dir	cwd option on spawn	--cd <path> flag	Use flag instead of cwd
Session resume	--resume <sessionId>	codex resume <sessionId>	Subcommand instead of flag
MCP config	Injected via ~/.claude.json	codex mcp add CLI or config.toml	Different injection mechanism
State detection	Pattern-match for Enter to select, Allow/Deny, spinners	Different TUI — needs new patterns	New detectWaitingForInput patterns for Codex
Session files	~/.claude/projects/<ws>/*.jsonl	Unknown location/format	Research needed
Non-interactive	Not available	codex exec with --json output	Could optionally use exec mode instead of PTY

Key tasks:

• Resolve codex binary path cross-platform (npm global codex, brew, etc.)
• Map TaskConfig fields to codex CLI flags (--sandbox, --model, --cd, --image)
• Implement PTY spawn with Codex TUI
• Write Codex-specific state detection patterns (spinner chars, approval prompts, question patterns)
• Implement session resume via codex resume <id>
• Handle codex exec as an alternative non-interactive mode (optional, Phase 2)

2. Shared type updates (~shared)

• Add 'codex' to BackendType union in shared/src/index.ts
• Add Codex to BACKEND_INFO registry in backend/src/backends/types.ts

3. Backend factory (~backend)

• Add case 'codex' in createBackend() in backend/src/backends/index.ts

4. State detection (~backend)

• Create codex-state-detection.ts (or parameterize existing)
• Research: run Codex interactively and catalog its TUI output patterns for idle, busy, waiting-for-input, permission, and question states
• Codex uses a Rust TUI — different spinner characters, different prompt patterns than Claude Code's Node TUI

5. Configuration (~backend + frontend)

• Add Codex-specific config fields: OpenAI API key (or ChatGPT login), approval mode mapping, default model
• API mode: CODEX_API_KEY env var or ChatGPT OAuth
• Frontend: Settings panel for Codex configuration (API key, model default, sandbox policy)

6. MCP injection (~backend)

• Claudia MCP server needs to work with Codex tasks
• Codex supports MCP natively (codex mcp add), but injection mechanism differs from Claude Code's ~/.claude.json
• Options: (a) write to ~/.codex/config.toml before spawn, (b) pass MCP config via CLI flags, or (c) use env vars

7. Frontend backend selector (~frontend)

• Add backend selector UI (per-workspace or per-task) to choose between Claude Code, OpenCode, and Codex
• Show Codex-specific options when selected (model list, sandbox mode)

8. Task persistence (~backend)

• backendType: 'codex' already supported in persistence schema
• Session ID capture/reconnect needs Codex-specific implementation

Out of scope (future work)

• codex exec (non-interactive) mode — structured JSON-streaming exec mode for headless/CI tasks
• codex cloud — cloud-hosted Codex environments
• Codex SDK — programmatic API as alternative to PTY spawning
• Cross-agent collaboration — Claude Code and Codex tasks communicating

Open questions

1. State detection patterns: Need to run Codex interactively and document its TUI output patterns. The Rust-based TUI likely has different spinners, prompt formats, and ANSI sequences.
2. Session file format: Where does Codex store conversation history? Is it resumable the same way?
3. MCP injection: What's the cleanest way to inject Claudia's MCP server into a Codex session? Does config.toml support per-session MCP overrides?
4. Auth flow: Codex supports ChatGPT OAuth login and API keys. Claudia would need to support at least API key mode (CODEX_API_KEY). OAuth would require a separate flow.
5. Model tiering: Codex models (GPT-5.4, GPT-5.3-Codex) are a different namespace. The model tiering feature needs to support both namespaces or be backend-aware.

Estimated effort

• Phase 1 (MVP — PTY backend + basic state detection): Medium — follows ClaudeCodeBackend pattern, state detection research is the bottleneck
• Phase 2 (MCP injection, settings UI, model tiering): Medium — integration across backend + frontend
• Phase 3 (exec mode, session history, polish): Small-medium

References

• Codex CLI repo
• CLI reference
• Non-interactive mode
• Existing backend abstraction: backend/src/backends/types.ts
• OpenCode backend (reference for adding a backend): backend/src/backends/opencode-backend.ts