← all skills

codex

/home/avalon/.hermes/skills/autonomous-ai-agents/codex/SKILL.md · raw

Codex CLI

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

Prerequisites

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

Troubleshooting / Fallbacks

Before launching a long Codex task, verify the CLI and auth when uncertainty is high:

terminal(command="command -v codex || npm install -g @openai/codex", pty=true)

If Codex exits with Command 'codex' not found, install it globally with npm install -g @openai/codex, then retry.

If Codex exits with 401 Unauthorized, Missing bearer or basic authentication, or websocket auth failures against api.openai.com/v1/responses, the CLI is not authenticated in this environment. Do not keep retrying the same command. Either:

  1. Ask the user to configure Codex/OpenAI credentials if they specifically require Codex execution, or
  2. If the task can be completed directly with Hermes tools, proceed with the closest equivalent workflow: inspect the repo with read_file/search_files, write the requested files, commit, push, and clearly report that Codex auth failed and Hermes completed the work directly.

For planning-only tasks, a good fallback is to use the writing-plans skill directly and create the markdown plan yourself after repo inspection.

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. Do not stall on missing Codex auth — after one authenticated retry fails, switch to direct Hermes implementation when feasible and disclose the fallback.