Codex

Files (1)

• SKILL.md

SKILL.md (first lines)

# Codex — Hermes Orchestration Guide

Delegate coding tasks to [Codex](https://code.Codex.com/docs/en/cli-reference) (Anthropic's autonomous coding agent CLI) via the Hermes terminal. Codex v2.x can read files, write code, run shell commands, spawn subagents, and manage git workflows autonomously.

## Prerequisites

- **Install:** `npm install -g @anthropic-ai/Codex`
- **Auth:** run `Codex` once to log in (browser OAuth for Pro/Max, or set `ANTHROPIC_API_KEY`)
- **Console auth:** `Codex auth login --console` for API key billing
- **SSO auth:** `Codex auth login --sso` for Enterprise
- **Check status:** `Codex auth status` (JSON) or `Codex auth status --text` (human-readable)
- **Health check:** `Codex doctor` — checks auto-updater and installation health
- **Version check:** `Codex --version` (requires v2.x+)
- **Update:** `Codex update` or `Codex upgrade`

## Two Orchestration Modes

Hermes interacts with Codex in two fundamentally different ways. Choose based on the task.

### Mode 1: Print Mode (`-p`) — Non-Interactive (PREFERRED for most tasks)

Print mode runs a one-shot task, returns the result, and exits. No PTY needed. No interactive prompts. This is the cleanest integration path.

```
terminal(command="Codex -p 'Add error handling to all API calls in src/' --allowedTools 'Read,Edit' --max-turns 10", workdir="/path/to/project", timeout=120)
```

**When to use print mode:**
- One-shot coding tasks (fix a bug, add a feature, refactor)
- CI/CD automation and scripting
- Structured data extraction with `--json-schema`
- Piped input processing (`cat file | Codex -p "analyze this"`)
- Any task where you don't need multi-turn conversation

**Print mode skips ALL interactive dialogs** — no workspace trust prompt, no permission confirmations. This makes it ideal for automation.

### Mode 2: Interactive PTY via tmux — Multi-Turn Sessions

Interactive mode gives you a full conversational REPL where you can send follow-up prompts, use slash commands, and watch Codex work in real time. **Requires tmux orchestration.**

```
# Start a tmux session
terminal(command="tmux new-session -d -s Codex-work -x 140 -y 40")

# Launch Codex inside it
terminal(command="tmux send-keys -t Codex-work 'cd /path/to/project && Codex' Enter")

# Wait for startup, then send your task
# (after ~3-5 seconds for the welcome screen)
terminal(command="sleep 5 && tmux send-keys -t Codex-work 'Refactor the auth module to use JWT tokens' Enter")

# Monitor progress by capturing the pane
terminal(command="sleep 15 && tmux capture-pane -t Codex-work -p -S -50")

# Send follow-up tasks
terminal(command="tmux send-keys -t Codex-work 'Now add unit tests for the new JWT code' Enter")

# Exit when done
terminal(command="tmux send-keys -t Codex-work '/exit' Enter")
```

**When to use interactive mode:**
- Multi-turn iterative work (refactor → review → fix → test cycle)
- Tasks requiring human-in-the-loop decisions
- Exploratory coding sessions
- When you need to use Codex's slash commands (`/compact`, `/review`, `/model`)

## PTY Dialog Handling (CRITICAL for Interactive Mode)

Codex presents up to two confirmation dialogs on first launch. You MUST handle these via tmux send-keys:

### Dialog 1: Workspace Trust (first visit to a directory)
```
❯ 1. Yes, I trust this folder    ← DEFAULT (just press Enter)
  2. No, exit
```
**Handling:** `tmux send-keys -t <session> Enter` — default selection is correct.

### Dialog 2: Bypass Permissions Warning (only with --dangerously-skip-permissions)
```
❯ 1. No, exit                    ← DEFAULT (WRONG choice!)
  2. Yes, I accept
```
**Handling:** Must navigate DOWN first, then Enter:
```
tmux send-keys -t <session> Down && sleep 0.3 && tmux send-keys -t <session> Enter
```

### Robust Dialog Handling Pattern
```
# Launch with permissions bypass
terminal(command="tmux send-keys -t Codex-work 'Codex --dangerously-skip-permissions \"your task\"' Enter")

# Handle trust dialog (Enter for default "Yes")
terminal(command="sleep 4 && tmux send-keys -t Codex-work Enter")

# Handle permissions dialog (Down then Enter for "Yes, I accept")
terminal(command="sleep 3 && tmux send-keys -t Codex-work Down && sleep 0.3 && tmux send-keys -t Codex-work Enter")

# Now wait for Codex to work
terminal(command="sleep 15 && tmux capture-pane -t Codex-work -p -S -60")
```

**Note:** After the first trust acceptance for a directory, the trust dialog won't appear again. Only the permissions dialog recurs each time you use `--dangerously-skip-permissions`.

## CLI Subcommands

| Subcommand | Purpose |
|------------|---------|
| `Codex` | Start interactive REPL |
| `Codex "query"` | Start REPL with initial prompt |
| `Codex -p "query"` | Print mode (non-interactive, exits when done) |
| `cat file \| Codex -p "query"` | Pipe content as stdin context |
| `Codex -c` | Continue the most recent conversation in this directory |
| `Codex -r "id"` | Resume a specific session by ID or name |
| `Codex auth login` | Sign in (add `--console` for API billing, `--sso` for Enterprise) |
| `Codex auth status` | Check login status (returns JSON; `--text` for human-readable) |
| `Codex mcp add <name> -- <cmd>` | Add an MCP server |
| `Codex mcp list` | List configured MCP servers |

From AvaTar-ArTs/.Agent-skills, MIT.

More from AvaTar-ArTs/.Agent-skills