Codex

Codex CLI

Delegate coding tasks to 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="")
process(action="log", session_id="")

# Send input if Codex asks a question
process(action="submit", session_id="", data="yes")

# Kill if needed
process(action="kill", session_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: . Commit when
  done.'", workdir="/tmp/issue-78", background=true, pty=true)
terminal(command="codex --yolo exec 'Fix issue #99: . 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 ''", workdir="~/project")

Rules

1. Always use pty=true — Codex is an interactive terminal app and hangs

without a PTY

1. Git repo required — Codex won't run outside a git directory. Use

mktemp -d && git init for scratch

1. Use exec for one-shots — codex exec "prompt" runs and exits cleanly
2. --full-auto for building — auto-approves changes within the sandbox
3. Background for long tasks — use background=true and monitor with

process tool

1. Don't interfere — monitor with poll/log, be patient with long-running

tasks

1. Parallel is fine — run multiple Codex processes at once for batch work

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: shikanime-labs
• Source: shikanime-labs/skills
• License: Apache-2.0

Install and usage instructions live in the source repository linked above.