Codex

Codex CLI

Delegate coding tasks to Codex via the Hermes terminal. Codex is OpenAI's autonomous coding agent CLI.

When to use

• Building features
• Refactoring
• PR reviews
• Batch issue fixing

Requires the codex CLI and a git repository.

Prerequisites

• Codex installed: npm install -g @openai/codex
• OpenAI auth configured: either OPENAI_API_KEY or Codex OAuth credentials from the Codex CLI login flow
• Must run inside a git repository — Codex refuses to run outside one
• Use pty=true in terminal calls — Codex is an interactive terminal app

For Hermes itself, model.provider: openai-codex uses Hermes-managed Codex OAuth from ~/.hermes/auth.json after hermes auth add openai-codex. For the standalone Codex CLI, a valid CLI OAuth session may live under ~/.codex/auth.json; do not treat a missing OPENAI_API_KEY alone as proof that Codex auth is missing.

One-Shot Tasks

terminal(command="codex exec 'Add dark mode toggle to settings'", workdir="~/project", pty=true)

For scratch work (Codex needs a git repo):

terminal(command="cd $(mktemp -d) && git init && codex exec 'Build a snake game in Python'", pty=true)

Background Mode (Long Tasks)

# Start in background with PTY
terminal(command="codex exec --full-auto 'Refactor the auth module'", workdir="~/project", background=true, pty=true)
# Returns session_id

# Monitor progress
process(action="poll", session_id="<id>")
process(action="log", session_id="<id>")

# Send input if Codex asks a question
process(action="submit", session_id="<id>", data="yes")

# Kill if needed
process(action="kill", session_id="<id>")

Key Flags

PR Reviews

Clone to a temp directory for safe review:

terminal(command="REVIEW=$(mktemp -d) && git clone https://github.com/user/repo.git $REVIEW && cd $REVIEW && gh pr checkout 42 && codex review --base origin/main", pty=true)

Parallel Issue Fixing with Worktrees

# Create worktrees
terminal(command="git worktree add -b fix/issue-78 /tmp/issue-78 main", workdir="~/project")
terminal(command="git worktree add -b fix/issue-99 /tmp/issue-99 main", workdir="~/project")

# Launch Codex in each
terminal(command="codex --yolo exec 'Fix issue #78: <description>. Commit when done.'", workdir="/tmp/issue-78", background=true, pty=true)
terminal(command="codex --yolo exec 'Fix issue #99: <description>. Commit when done.'", workdir="/tmp/issue-99", background=true, pty=true)

# Monitor
process(action="list")

# After completion, push and create PRs
terminal(command="cd /tmp/issue-78 && git push -u origin fix/issue-78")
terminal(command="gh pr create --repo user/repo --head fix/issue-78 --title 'fix: ...' --body '...'")

# Cleanup
terminal(command="git worktree remove /tmp/issue-78", workdir="~/project")

Batch PR Reviews

# Fetch all PR refs
terminal(command="git fetch origin '+refs/pull/*/head:refs/remotes/origin/pr/*'", workdir="~/project")

# Review multiple PRs in parallel
terminal(command="codex exec 'Review PR #86. git diff origin/main...origin/pr/86'", workdir="~/project", background=true, pty=true)
terminal(command="codex exec 'Review PR #87. git diff origin/main...origin/pr/87'", workdir="~/project", background=true, pty=true)

# Post results
terminal(command="gh pr comment 86 --body '<review>'", workdir="~/project")

CLIProxyAPI / CPA for Codex accounts

When the user says "CPA" in the context of Codex accounts, they often mean CLIProxyAPI: a proxy that exposes Codex/ChatGPT OAuth subscriptions as OpenAI/Codex-compatible API endpoints for other clients.

Key configuration facts:

• Default CLIProxyAPI port: 8317
• Client base URL shape: http://HOST:8317/v1 — stop at /v1; do not append /responses or /chat/completions in client/provider config
• Codex CLI should use wire_api = "responses"
• OAuth login command: ./cli-proxy-api --codex-login; use --no-browser when setting up a headless/remote server
• Codex OAuth callback uses local port 1455; for remote servers, use SSH port forwarding: ssh -L 1455:127.0.0.1:1455 user@server, then run the login command on the server under the same service user that will run the daemon
• Share proxy API keys with trusted users, not server passwords or OpenAI/Codex credentials; recommend per-user keys for revocation

See references/cliproxyapi-codex-proxy.md for a deploy/checklist reference, client config snippets, verification curls, and security notes.

CLIProxyAPI / shared Codex API endpoint

When the user asks to use "CPA", "CLIProxyAPI", or to let other tools/people use a Codex account through a base_url, use the CLIProxyAPI workflow rather than ordinary codex exec.

Key facts:

• Default CLIProxyAPI client base_url is http://127.0.0.1:8317/v1 locally or http://<server>:8317/v1 remotely; do not include /responses or /chat/completions in the base URL.
• Codex CLI clients should set wire_api = "responses", use model = "gpt-5-codex", and may set model_reasoning_effort = "xhigh" for maximum reasoning (minimal|low|medium|high|xhigh are the documented effort values; support is model-dependent).
• Remote Codex OAuth login needs an SSH tunnel for callback port 1455: ssh -L 1455:127.0.0.1:1455 <user>@<server>; then run cli-proxy-api --codex-login --no-browser on the server as the service/auth owner.
• For server deployments, create a dedicated service user, store auth files under a service-owned auth directory, run under systemd, and open TCP 8317 in both the host firewall and cloud security group.
• If credentials or server passwords were pasted into chat, advise rotating them after deployment; never persist real secrets in skills/templates.

Support files:

• references/cliproxyapi-codex-proxy.md — full setup notes, endpoint shapes, OAuth tunnel, verification, security notes, and current Codex model/reasoning config.
• templates/cliproxyapi-codex-config.yaml — reusable server config skeleton with placeholders.
• templates/codex-client-cliproxyapi-config.toml — reusable Codex CLI client provider config using gpt-5-codex, model_reasoning_effort = "xhigh", and wire_api = "responses".
• scripts/install-cliproxyapi-codex-ubuntu.sh — Ubuntu/systemd installer template; requires a config file at /tmp/cliproxyapi-config.yaml or CONFIG_SOURCE=....

Rules

1. Always use pty=true — Codex is an interactive terminal app and hangs without a PTY
2. Git repo required — Codex won't run outside a git directory. Use mktemp -d && git init for scratch
3. Use exec for one-shots — codex exec "prompt" runs and exits cleanly
4. --full-auto for building — auto-approves changes within the sandbox
5. Background for long tasks — use background=true and monitor with process tool
6. Don't interfere — monitor with poll/log, be patient with long-running tasks
7. Parallel is fine — run multiple Codex processes at once for batch work
8. For CPA/CLIProxyAPI questions — answer with base_url = http://HOST:8317/v1, wire_api = "responses", and include the OAuth callback tunnel pattern for remote setup