---
name: codex
description: "Delegate coding to OpenAI Codex CLI (features, PRs)."
version: 1.0.0
author: Hermes Agent
license: MIT
platforms: [linux, macos, windows]
metadata:
  hermes:
    tags: [Coding-Agent, Codex, OpenAI, Code-Review, Refactoring]
    related_skills: [claude-code, hermes-agent]
---

# 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 |
| `--sandbox workspace-write` | Sandboxed workspace-write mode; preferred replacement for deprecated `--full-auto` |
| `--sandbox read-only` | Read-only sandbox for reviews when local sandbox setup works |
| `--dangerously-bypass-approvals-and-sandbox` | No sandbox/approvals. Use only when the environment is externally trusted and Codex sandboxing prevents required local file inspection; pair with explicit “do not modify files / do not build” review instructions. |
| `--full-auto` | Deprecated; use `--sandbox workspace-write` instead |
| `--yolo` | Legacy/no-sandbox style; prefer explicit modern flags above |

## Review / Sign-off Gates

## Review / Sign-off Gates

When the user makes Codex approval a gate (e.g. “Codex must read every file and sign off before build”), treat Codex’s verdict as a hard stop:

1. Do not build, install, deploy, or otherwise proceed until Codex explicitly says `SIGN OFF` / approved.
2. Use the cheapest sufficient reasoning level. For this user, default Codex build-gate reviews to `--reasoning-effort low` for narrow backend/test deltas and `--reasoning-effort medium` for data migrations, Health Connect logic, auth, Android permissions, or APK/build gates. Reserve high/exhaustive reviews only for genuinely risky architecture/security changes.
3. Keep review prompts focused: list exact changed files/requirements and ask for blockers plus `SIGN OFF`/`DO NOT BUILD`; avoid broad “inspect everything top to bottom” prompts unless the user explicitly asks for exhaustive review.
4. Ensure Codex can actually inspect the repository. If it reports sandbox/file-access failure, that is **not** a review; rerun with an appropriate sandbox mode or, in trusted local environments only, `--dangerously-bypass-approvals-and-sandbox` plus strict read-only instructions.
5. If Codex says `DO NOT BUILD`, summarize blockers and fix them; then run Codex again before building.
6. Clean generated artifacts from the review surface (`.gradle/`, `build/`, `app/build/`, APKs) so Codex reviews source/config only.

## PR / Build-Gate Reviews

Clone to a temp directory for safe PR 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)
```

For user-requested build gates (e.g. “do not build until Codex signs off”), treat Codex’s verdict as a hard gate:

1. Run Codex in read-only review mode first: prompt it to inspect all source/config files and explicitly output either `SIGN OFF FOR BUILD` or `DO NOT BUILD`.
2. If Codex says `DO NOT BUILD`, apply only the requested fixes; do **not** build or install yet.
3. Re-run Codex until it explicitly says `SIGN OFF FOR BUILD`.
4. Only after sign-off, run the build and deployment/install steps.

Example:

```
terminal(
  command="codex exec --dangerously-bypass-approvals-and-sandbox 'READ-ONLY REVIEW. Do not modify files. Do not build. Inspect every source/config file. Produce blocking issues and explicit SIGN OFF FOR BUILD or DO NOT BUILD.'",
  workdir="~/project",
  background=true,
  pty=true,
  notify_on_complete=true,
)
```

Use `--dangerously-bypass-approvals-and-sandbox` only when the surrounding environment is already trusted and the prompt is explicitly read-only. This is useful when Codex’s sandbox cannot inspect the local workspace (for example bubblewrap/loopback setup failures). Prefer normal sandboxed `codex exec` when it can read the repo.

## 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")
```

## 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 `poll`/`log`, be patient with long-running tasks
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. **Respect user-mandated gates** — if the user requires Codex sign-off before a build/install/deploy, do not run the gated action until Codex explicitly says `SIGN OFF FOR BUILD` / equivalent. If Codex says `DO NOT BUILD`, apply fixes and re-review first.

## Read-only sign-off reviews before builds

When the user asks for Codex to approve an artifact before you build it:

1. Make the repo reviewable: initialize/use git if needed; add `.gitignore` for generated directories (`.gradle/`, `build/`, `app/build/`, `local.properties`, artifacts); stage or otherwise expose only real source/config files.
2. Run Codex in read-only intent with a strict prompt: "Do not modify files. Do not build. Inspect every source/config file. Return blocking issues, non-blocking issues, exact changes, and explicit SIGN OFF or DO NOT BUILD."
3. If the sandbox prevents local file inspection (for example bwrap/network namespace setup), rerun with `--dangerously-bypass-approvals-and-sandbox` **only for read-only review prompts** so Codex can inspect the local repo. Do not let Codex modify files in that mode.
4. Treat Codex self-report as a review, not proof: read the final output, confirm it inspected local files, and only proceed after explicit sign-off.
5. If build fails after sign-off, fix the compile issue, re-run Codex review on the delta, then build again.