codex

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 via the Hermes terminal. Codex is OpenAI's autonomous coding agent CLI.

Reference: See references/multi-agent-evaluation.md for comparison with Claude Code, Nyx, Antigravity, and fleet deployment patterns.

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.

Pre-flight Verification (MANDATORY)

Never claim Codex is "ready" without running these checks:

# 1. Binary exists and version is known
which codex && codex --version

# 2. Auth is functional (dry-run)
codex exec "echo 'auth ok'"

# 3. If targeting a remote node over SSH, verify there too
ssh user@node "which codex && codex --version"

If any step fails, install/re-auth before proceeding. Do not speculate.

Using Moonshot Kimi (or any OpenAI-compatible API)

Codex CLI natively supports OpenAI-compatible endpoints — unlike Claude Code.

export OPENAI_BASE_URL="https://api.moonshot.cn/v1"
export OPENAI_API_KEY="sk-xxx"
export OPENAI_MODEL="kimi-k2-6"
codex exec "Build a feature"

Or one-shot:

OPENAI_BASE_URL=https://api.moonshot.cn/v1 OPENAI_API_KEY=sk-xxx OPENAI_MODEL=kimi-k2-6 codex exec "Refactor auth"

For Hermes-managed Codex auth: model.provider: openai-codex uses Hermes OAuth from ~/.hermes/auth.json after hermes auth add openai-codex. For standalone Codex CLI, set the env vars above.

Collaboration with Claude Code

Codex is the muscle (implementation); Claude Code is the brain (review/architecture).

Tool	Best Role	Why
Codex	Feature implementation, refactoring, batch fixes	Native OpenAI-compatible API → works with Kimi
Claude Code	Architecture review, security audit, PR review	Better at multi-file reasoning and planning

Shared Handoff Protocol

Use team-collab-skills for structured handoffs:

codex plugin marketplace add https://github.com/dadwadw233/team-collab-skills.git

Then in either agent:

$handoff refactor-auth

This writes the current state to CURRENT.md, NEXT.md, RISKS.md so the other agent can pick up seamlessly.

File-Based Coordination (No plugins)

Keep these files in repo root:

• SPEC.md — what we're building
• CURRENT.md — what's done
• NEXT.md — what's next
• RISKS.md — blockers and concerns

Claude Code plans → writes to SPEC.md + NEXT.md → Codex reads and implements → Claude Code reviews.

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")
### Alternative UI: Nyx Mission Control

[Nyx](https://getnyx.dev/) is an infinite-canvas IDE that spawns Codex, Claude Code, and other CLI agents as live PTY tiles on a single screen. Use it when you need visual oversight of multiple parallel agent sessions without tab switching or context loss. Status: closed-source beta (as of 2026-05).

### Simplest Collaboration (No tools needed)
Tmux with 2 panes:
- **Pane 1:** `claude` — architect / reviewer (brain)
- **Pane 2:** `codex` — implementer (muscle)
- Share context via `SPEC.md` and `CURRENT.md` in the repo

### tokligence-works (Heavyweight)
Multi-agent team with Jira, YAML config, role-based agents. Overkill for 1–2 person setups.

## Fleet Deployment (24/7 Multi-Node Operation)

When deploying across company hardware (GPU workstations, interface nodes, etc.):

### 1. Audit every node
```bash
for host in node-01 node-02 node-03; do
  echo "=== $host ==="
  ssh $host "which codex && codex --version" 2>&1 || echo "MISSING"
done

2. Ensure shared repo access

All nodes need git credentials for target repositories:

# Test from each node
ssh node-01 "git ls-remote https://github.com/org/repo.git" 2>&1 || echo "AUTH FAIL"

3. Persistent background sessions

# Start long-running Codex task in tmux
tmux new-session -d -s codex-build -x 140 -y 40
tmux send-keys -t codex-build 'cd /shared/project && codex exec --full-auto "Implement auth refactor"' Enter

# Monitor remotely
tmux capture-pane -t codex-build -p -S -20

4. Hermes integration

Use Hermes process tool to monitor background Codex sessions:

process(action="poll", session_id="<codex-bg-id>")
process(action="log", session_id="<codex-bg-id>")

5. Cost guardrails for 24/7

• Always set --max-turns to prevent runaway loops
• Use --full-auto only inside sandboxed worktrees
• Rotate API keys per node if rate-limiting becomes an issue

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. Verify before claiming readiness — run pre-flight checks on every node