---
name: ai-coding-agents
description: "Use when delegating coding work to autonomous AI coding agent CLIs: Claude Code (Anthropic), Codex (OpenAI), or OpenCode (provider-agnostic). Feature building, refactoring, PR reviews, batch issue fixing."
version: 1.0.0
author: Hermes Agent
license: MIT
platforms: [linux, macos, windows]
metadata:
  hermes:
    tags: [Coding-Agent, Claude, Codex, OpenAI, OpenCode, Autonomous, Refactoring, Code-Review, PTY, Automation]
---

# AI Coding Agents — Orchestration Guide

Delegate coding tasks to autonomous CLI coding agents. Three tools with different strengths:

| Agent | Vendor | Best for | Auth |
|-------|--------|----------|------|
| **Claude Code** | Anthropic | Complex multi-turn work, structured JSON output, tmux orchestration | OAuth or API key |
| **Codex** | OpenAI | One-shot builds, --yolo fast iteration | OAuth or API key |
| **OpenCode** | Provider-agnostic | Open-source, model flexibility, TUI sessions | Provider env vars |

All three are installed via npm: `npm install -g @anthropic-ai/claude-code @openai/codex opencode-ai`

## Quick Decision: Which Agent?

- **Claude Code (`-p` print mode)**: Preferred default. Best for structured output, one-shots, piped input, JSON schema extraction.
- **Claude Code (interactive via tmux)**: Multi-turn iterative work needing conversation.
- **Codex**: One-shot `codex exec "prompt"`. Fastest path, least ceremony. Needs `pty=true`.
- **OpenCode**: When Claude Code isn't available, or when model flexibility matters. TUI or one-shot `run`.

---

## Claude Code

### Print Mode (`-p`) — Preferred for Automation

Non-interactive one-shot. No PTY, no dialog handling. Cleanest integration.

```bash
# Basic task
claude -p 'Add error handling to all API calls in src/' --allowedTools 'Read,Edit' --max-turns 10

# Piped input analysis
git diff HEAD~3 | claude -p 'Summarize these changes' --max-turns 1

# Structured JSON output
claude -p 'Analyze auth.py for security issues' --output-format json --max-turns 5

# JSON Schema extraction
claude -p 'List all functions in src/' --output-format json \
  --json-schema '{"type":"object","properties":{"functions":{"type":"array","items":{"type":"string"}}}}' --max-turns 5
```

### Interactive Mode (via tmux)

```bash
# Start session
tmux new-session -d -s claude -x 140 -y 40
tmux send-keys -t claude 'cd /project && claude' Enter

# Handle dialogs: workspace trust (Enter), permissions bypass (Down + Enter)
sleep 4 && tmux send-keys -t claude Enter
sleep 3 && tmux send-keys -t claude Down && sleep 0.3 && tmux send-keys -t claude Enter

# Send task
tmux send-keys -t claude 'Refactor the auth module' Enter

# Monitor
tmux capture-pane -t claude -p -S -50

# Cleanup
tmux kill-session -t claude
```

### Key Flags

| Flag | Effect |
|------|--------|
| `-p "prompt"` | Print mode: one-shot, exits when done |
| `--allowedTools "Read,Edit"` | Restrict tool access |
| `--max-turns N` | Limit agentic loops (print mode only) |
| `--max-budget-usd N` | Cap API spend |
| `--output-format json` | Structured result with session_id, cost, usage |
| `--dangerously-skip-permissions` | Auto-approve all tool use |
| `--bare` | Skip hooks/plugins (CI mode, requires API key) |
| `--model sonnet/opus/haiku` | Model selection |
| `-c` / `--continue` | Resume last session |
| `-r <id>` | Resume specific session |
| `--from-pr 42` | Review PR #42 |

### PR Review Pattern

```bash
# Quick review
git diff main...feature-branch | claude -p 'Review this diff for bugs, security, style' --max-turns 1

# Deep review
claude -p 'Review this PR thoroughly' --from-pr 42 --max-turns 10
```

### Pitfalls
- Print mode skips ALL interactive dialogs — preferred for automation
- `--dangerously-skip-permissions` dialog defaults to "No, exit" — must send Down+Enter in tmux
- `--max-turns` is print-mode ONLY; ignored in interactive
- Tmux sessions persist — always cleanup with `tmux kill-session`
- Context degrades above 70% — use `/compact` in interactive mode

---

## Codex CLI

### One-Shot Tasks

```bash
# Requires pty=true in Hermes terminal()
codex exec 'Add dark mode toggle to settings'

# Scratch work (Codex needs a git repo)
cd $(mktemp -d) && git init && codex exec 'Build a snake game in Python'
```

### Key Flags

| Flag | Effect |
|------|--------|
| `exec "prompt"` | One-shot execution, exits when done |
| `--full-auto` | Sandboxed but auto-approves file changes |
| `--yolo` | No sandbox, no approvals (fastest) |

### Parallel Issue Fixing

```bash
git worktree add -b fix/issue-78 /tmp/issue-78 main
git worktree add -b fix/issue-99 /tmp/issue-99 main

# Run in separate terminals
codex --yolo exec 'Fix issue #78'  # in /tmp/issue-78
codex --yolo exec 'Fix issue #99'  # in /tmp/issue-99
```

### Rules
- Always `pty=true` — Codex is interactive
- Git repo required — use `mktemp -d && git init` for scratch
- `--full-auto` for building, `--yolo` for speed
- Background for long tasks

---

## OpenCode CLI

### One-Shot

```bash
opencode run 'Add retry logic to API calls and update tests'
opencode run 'Review this config' -f config.yaml -f .env.example
opencode run 'Debug CI failure' --thinking
opencode run 'Refactor auth' --model openrouter/anthropic/claude-sonnet-4
```

### Interactive (Background + PTY)

```bash
opencode  # Start TUI with background=true, pty=true

# Send prompts via process submit
process(action="submit", session_id="<id>", data="Implement OAuth flow")

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

# Exit: Ctrl+C (write \x03) or kill — NOT /exit (opens agent selector)
process(action="write", session_id="<id>", data="\x03")
```

### Key Flags

| Flag | Use |
|------|-----|
| `run 'prompt'` | One-shot execution |
| `-c` / `--continue` | Continue last session |
| `-s <id>` | Resume specific session |
| `--agent build/plan` | Choose agent mode |
| `--model provider/model` | Force specific model |
| `-f <path>` | Attach files to message |
| `--thinking` | Show model thinking blocks |
| `pr <N>` | Review PR #N |

### Pitfalls
- Interactive TUI needs `pty=true`; `opencode run` does NOT
- `/exit` is NOT valid — opens agent selector. Use Ctrl+C
- PATH mismatch can select wrong binary
- Don't share one workdir across parallel sessions

---

## General Rules

1. **Prefer one-shot modes** (`claude -p`, `codex exec`, `opencode run`) — simpler, no dialog handling
2. **Use tmux for interactive Claude Code** — only reliable way to orchestrate the TUI
3. **Always set `workdir`** to keep agent focused on right project
4. **Set turn/budget limits** — `--max-turns`, `--max-budget-usd` prevent runaway costs
5. **Monitor long tasks** with `tmux capture-pane` or `process(action="poll")`
6. **Clean up sessions** — kill tmux sessions, close PTY processes
7. **Parallel is fine** — run multiple agents in separate workdirs/worktrees
8. **Report outcomes** — summarize what changed, tests run, remaining risks