Codex Agent Reference for Hermes Terminal

This document describes how to delegate coding tasks to OpenAI's Codex autonomous coding agent through the Hermes terminal. Codex can handle building features, refactoring, PR reviews, and batch issue fixing.

Prerequisites

Before using Codex, ensure the following are in place:

• Codex installed globally: npm install -g @openai/codex
• OpenAI authentication configured. This can be done via the OPENAI_API_KEY environment variable or through Codex OAuth credentials obtained from the Codex CLI login flow.
• You must be inside a git repository. Codex refuses to run outside one. For scratch work, create a temp directory and initialize git with mktemp -d && git init.
• Always set pty=true in terminal calls. Codex hangs without a PTY.

Parameters

• exec "prompt" – One-shot execution; exits when done. Required for one-shot tasks.
• --sandbox workspace-write (short: -s) – Sandboxed execution that auto-approves file changes in the workspace. This is the recommended auto-build mode.
• --dangerously-bypass-approvals-and-sandbox – No sandbox, no approvals. Fastest but most dangerous. Hidden alias: --yolo.
• --sandbox danger-full-access – No Codex sandbox; useful when host service context breaks bubblewrap.
• pty=true – Must be set in terminal calls because Codex is an interactive terminal app. Always required.
• background=true – Runs the task in background, returns a session_id for monitoring. Required for long tasks.

One-Shot Task

For a single, self-contained coding task:

1. Ensure you are inside a git repository (or create a temp one with mktemp -d && git init).
2. Run the following command:

terminal(command="codex exec 'Add dark mode toggle to settings'", workdir="~/project", pty=true)

For scratch work without an existing repo:

terminal(command="cd $(mktemp -d) && git init && codex exec 'Build a snake game in Python'", pty=true)

Background Mode (Long Task)

For long-running tasks that need monitoring:

1. Start the task in background:

# Start in background with PTY
terminal(command="codex exec --sandbox workspace-write 'Refactor the auth module'", workdir="~/project", background=true, pty=true)
# Returns session_id

2. Monitor progress using process:

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

3. If Codex asks a question, send input:

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

4. Kill the task if needed:

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

Sandbox Modes

The recommended sandbox mode for building is --sandbox workspace-write. When invoking from a Hermes gateway or service context, the workspace-write sandboxing may fail due to bubblewrap or user-namespace errors such as setting up uid map: Permission denied or loopback: Failed RTM_NEWADDR: Operation not permitted. In that case, use --sandbox danger-full-access:

codex exec --sandbox danger-full-access "<task>"

Rely on process boundaries for safety: explicit workdir, clean git status, narrow task prompts, git diff review, targeted tests, and human or agent confirmation before committing broad changes.

Note: --full-auto is deprecated. Use --sandbox workspace-write instead.

PR Review

To review a pull request:

1. Clone the repo to a temp directory and check out the PR:

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

For fixing multiple issues in parallel:

1. Create 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")

2. Launch Codex in each worktree:

# Launch Codex in each
terminal(command="codex --sandbox workspace-write exec 'Fix issue #78: <description>. Commit when done.'", workdir="/tmp/issue-78", background=true, pty=true)
terminal(command="codex --sandbox workspace-write exec 'Fix issue #99: <description>. Commit when done.'", workdir="/tmp/issue-99", background=true, pty=true)

3. Monitor all tasks:

# Monitor
process(action="list")

4. After completion, push and create PRs:

# 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 '...'")

5. Cleanup:

# Cleanup
terminal(command="git worktree remove /tmp/issue-78", workdir="~/project")

Batch PR Reviews

For reviewing multiple PRs at once:

1. Fetch all PR refs:

# Fetch all PR refs
terminal(command="git fetch origin '+refs/pull/*/head:refs/remotes/origin/pr/*'", workdir="~/project")

2. Review multiple PRs in parallel:

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

3. Post results:

# Post results
terminal(command="gh pr comment 86 --body '<review>'", workdir="~/project")

Authentication

For Hermes itself, use model.provider: openai-codex which uses Hermes-managed Codex OAuth from ~/.hermes/auth.json after running hermes auth add openai-codex. For 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.

Failure Modes

• Codex hangs if pty=true is not set.
• Codex refuses to run outside a git repository.
• Sandbox workspace-write fails in Hermes gateway or service context with bubblewrap or user-namespace errors.
• Missing or invalid OpenAI auth (OPENAI_API_KEY or Codex OAuth).