# Codex

> Delegate coding to OpenAI Codex CLI (features, PRs).

- Skill: `wyattjy/codex` (Agent Skill, multi-file: 5 files)
- Install (CLI): `npx skillmds@latest add wyattjy/codex`
- Raw SKILL.md: https://api.skillmd.com/api/skills/wyattjy/codex/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- License: MIT
- Author: WyattJY (https://skillmd.com/u/wyattjy)
- Updated: 2026-09-21
- Page: https://skillmd.com/skills/wyattjy/codex

---


# Codex CLI

Delegate coding tasks to [Codex](https://github.com/openai/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

| Flag | Effect |
|------|--------|
| `exec "prompt"` | One-shot execution, exits when done |
| `--full-auto` | Sandboxed but auto-approves file changes in workspace |
| `--yolo` | No sandbox, no approvals (fastest, most dangerous) |

## 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](https://github.com/router-for-me/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