Codex Skill for Hermes Agent: Delegate Coding Tasks to OpenAI Codex CLI

The Codex skill lets Hermes Agent hand coding work to OpenAI's Codex CLI, an autonomous coding agent that runs in your terminal. You reach for it when you want features built, code refactored, pull requests reviewed, or a batch of issues fixed without driving every step yourself. It is bundled with Hermes Agent, so there is nothing to install on the Hermes side, but Codex itself and a git repository are required.

What it does

This skill wraps the codex command inside Hermes terminal calls. You give Codex a prompt in natural language, point it at a working directory, and it works on the code there. The skill's job is to get the invocation right: the PTY setting, the sandbox flag, the working directory, and whether the process runs in the foreground or background. It also documents the patterns that make Codex usable from an agent runtime, such as scratch repositories, background monitoring, worktrees for parallel fixes, and temporary clones for PR review.

In practice you use it for four kinds of work: building features, refactoring, PR reviews, and batch issue fixing. Each has a recommended shape in the sections below.

Before you start

Four things must be true before the first call.

1. Codex is installed. The source gives the install command as npm install -g @openai/codex.
2. OpenAI authentication is configured. You can use an OPENAI_API_KEY, or Codex OAuth credentials obtained through the Codex CLI login flow.
3. You are inside a git repository. Codex refuses to run outside one, so a scratch directory needs git init first.
4. Terminal calls set pty=true. Codex is an interactive terminal application and needs a PTY.

On authentication, the source makes a distinction worth keeping straight. For Hermes itself, model.provider: openai-codex uses Hermes-managed Codex OAuth stored in ~/.hermes/auth.json, populated by hermes auth add openai-codex. For the standalone Codex CLI, a valid CLI OAuth session may live under ~/.codex/auth.json. A missing OPENAI_API_KEY on its own does not prove that Codex authentication is absent.

One-shot tasks

For a single task that should run and finish, use codex exec with a prompt and a working directory:

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

If you want to try something without touching a real project, Codex still needs a git repository. The source's pattern creates a temporary directory and initialises git inside it:

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

Background mode for long tasks

Long jobs should not block the agent. Start Codex in the background with a PTY, then use the process tool to watch and steer it:

# 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

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

The background call returns a session ID. poll checks status, log reads output, submit answers a prompt from Codex, and kill stops the process. The source's rule is to be patient with long-running tasks and not interfere beyond monitoring.

Key flags

Flag	Effect
exec "prompt"	One-shot execution, exits when done
--sandbox workspace-write (-s)	Sandboxed but auto-approves file changes in the workspace (the recommended auto-build mode)
--dangerously-bypass-approvals-and-sandbox	No sandbox, no approvals (fastest, most dangerous; --yolo still works as a hidden alias)
--sandbox danger-full-access	No Codex sandbox; useful when the host service context breaks bubblewrap

--full-auto still works but is deprecated; the live CLI warns to use --sandbox workspace-write instead.

Hermes gateway caveat

When Codex runs from a Hermes gateway or service context, such as a Telegram-driven agent session, workspace-write sandboxing may fail even though the same command works in your interactive shell. Typical symptoms are bubblewrap or user-namespace errors like setting up uid map: Permission denied or loopback: Failed RTM_NEWADDR: Operation not permitted.

In that context the source recommends:

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

Because the sandbox is off, the process boundary becomes the safety layer. The source lists the controls: an explicit workdir, a clean git status before launch, narrow task prompts, git diff review, targeted tests, and human or agent confirmation before committing broad changes.

PR reviews

Reviewing a pull request is safer in a throwaway clone. The source's pattern clones the repository into a temporary directory, checks out the PR with gh pr checkout, and runs codex review against the base branch:

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 several independent fixes, give each one its own worktree and its own Codex process. The source creates branches from main under ~/.hermes/cache/scratch/, launches Codex in each with background=true, monitors with process(action="list"), then pushes and opens PRs:

# Create worktrees
terminal(command="git worktree add -b fix/issue-78 ~/.hermes/cache/scratch/issue-78 main", workdir="~/project")
terminal(command="git worktree add -b fix/issue-99 ~/.hermes/cache/scratch/issue-99 main", workdir="~/project")

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

# Monitor
process(action="list")

# After completion, push and create PRs
terminal(command="cd ~/.hermes/cache/scratch/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 ~/.hermes/cache/scratch/issue-78", workdir="~/project")

Batch PR reviews

To review many PRs at once, fetch all PR refs, launch a Codex process per PR in the background, and post the results with gh pr comment:

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

When not to use it

The source does not list explicit exclusions, but its prerequisites imply the boundaries. If you cannot install Codex, cannot authenticate with OpenAI, or cannot work inside a git repository, this skill is not the right tool. For coding work that does not fit those constraints, the related skills below are the place to look.

Limits and gotchas

The source's rules are the practical limits.

1. Always use pty=true. Codex hangs without a PTY.
2. A git repository is required. Use mktemp -d && git init for scratch work.
3. Use exec for one-shot tasks so the process exits cleanly.
4. Use --sandbox workspace-write for building; --full-auto is deprecated for that purpose.
5. Run long tasks in the background and monitor them with the process tool.
6. Do not interfere with running tasks. Poll and read logs, and be patient.
7. Parallel processes are fine for batch work.

Related skills

If you need a different coding agent, see the claude-code skill. For work on Hermes Agent itself, see the hermes-agent skill.