Codex CLI
Delegate coding tasks to 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=truein 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)
# 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")
Rules
- Always use
pty=true— Codex is an interactive terminal app and hangs without a PTY - Git repo required — Codex won't run outside a git directory. Use
mktemp -d && git initfor scratch - Use
execfor one-shots —codex exec "prompt"runs and exits cleanly --full-autofor building — auto-approves changes within the sandbox- Background for long tasks — use
background=trueand monitor withprocesstool - Don't interfere — monitor with
poll/log, be patient with long-running tasks - Parallel is fine — run multiple Codex processes at once for batch work
