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.

## Prerequisites

- Codex installed: `npm install -g @openai/codex`
- OpenAI API key configured
- **Must run inside a git repository** — Codex refuses to run outside one
- Use `pty=true` in terminal calls — Codex is an interactive terminal app

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

```
# Robust background pattern: redirect stdin so Codex doesn't hang waiting for extra input
# Prefer --sandbox workspace-write; older notes/examples may use deprecated --full-auto.
terminal(command="codex exec --sandbox workspace-write 'Refactor the auth module' < /dev/null 2>&1 | tee /tmp/codex-auth.log", workdir="~/project", background=true, notify_on_complete=true)
# Returns session_id

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

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

Critical learned behavior:
- In Hermes background mode, `codex exec ...` may print `Reading additional input from stdin...` and then hang indefinitely if stdin is left open.
- For non-interactive/background runs, always add `< /dev/null`.
- When the prompt is long, write it to a file and run: `codex exec "$(cat prompt.md)" < /dev/null 2>&1 | tee out.log`.
- If a background Codex run shows no progress and the output file only contains that stdin message, kill it and relaunch with stdin redirected.
- In some sandboxed environments, Codex review runs may emit `bwrap: loopback: Failed RTM_NEWADDR: Operation not permitted` when trying to shell-read local files. The run may still finish using only prompt-provided context, but its retrieval adequacy is degraded. For adversarial reviews, prefer embedding the full plan text in the prompt instead of assuming Codex can read repo files itself.

## Key Flags

| Flag | Effect |
|------|--------|
| `exec "prompt"` | One-shot execution, exits when done |
| `--sandbox workspace-write` | Auto-approves changes inside the workspace sandbox; preferred current flag for build lanes |
| `--full-auto` | Deprecated legacy alias for workspace-write style automation; avoid in new prompts |
| `--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")
```

## 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. **`--sandbox workspace-write` for building** — auto-approves changes within the workspace sandbox; `--full-auto` is deprecated and should only appear in legacy command transcripts
5. **Background for long tasks** — use `background=true` and monitor with `process` tool plus PID/`ps` checks when launching through shell wrappers
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