---
name: ai-coding-agents
description: "Delegate coding to external AI agents: Claude Code, OpenAI Codex, OpenCode. Comparison, orchestration patterns, PTY handling, and per-agent CLI reference."
tags: [Coding-Agent, Claude, Codex, OpenCode, autonomous, delegation, PTY]
related_skills: [hermes-agent]
---

# AI Coding Agents — Orchestration Guide

## Overview

Three autonomous coding agent CLIs can be orchestrated from Hermes via terminal/process tools. Each has different strengths:

| Agent | Provider | Best For | Key Flag |
|-------|----------|----------|----------|
| **Claude Code** | Anthropic | Complex multi-step, PR review, MCP integration | `claude -p "task"` |
| **Codex** | OpenAI | Fast one-shot edits, parallel batch work | `codex exec "task"` |
| **OpenCode** | Multi-provider | Provider-agnostic, open-source | `opencode run "task"` |

## Decision Guide

| Need | Use |
|------|-----|
| One-shot coding task | Any agent's print/run mode |
| Multi-turn iterative work | Claude Code (tmux) or OpenCode (background PTY) |
| PR review | Claude Code (`--from-pr`) or Codex (`codex review`) |
| Parallel batch fixes | Codex (worktrees) or Claude Code (parallel tmux) |
| MCP tool integration | Claude Code only |
| Provider flexibility | OpenCode (any LLM provider) |
| Cost control | Claude Code (`--max-budget-usd`) or Codex |

## Two Orchestration Modes (All Agents)

### Mode 1: Print/Run Mode — Non-Interactive (PREFERRED)
One-shot task, returns result, exits. No PTY needed.

```bash
# Claude Code
claude -p "Add error handling to src/" --allowedTools 'Read,Edit' --max-turns 10

# Codex
codex exec --full-auto "Refactor the auth module"

# OpenCode
opencode run "Add retry logic to API calls"
```

### Mode 2: Interactive — Multi-Turn Sessions
Requires PTY (tmux for Claude Code, background+pty for others).

```bash
# Claude Code via tmux
tmux new-session -d -s claude && tmux send-keys -t claude 'claude' Enter

# Codex background
terminal(command="codex exec --full-auto 'task'", background=true, pty=true)

# OpenCode background
terminal(command="opencode", workdir="~/project", background=true, pty=true)
```

## Common Patterns

### Isolated Worktrees (All Agents)
Always use isolated worktrees for untrusted agent output:
```bash
git worktree add -b agent/task-42 /tmp/task-42 main
# Run agent in /tmp/task-42
# Review diff, cherry-pick accepted changes
git worktree remove /tmp/task-42
```

### Monitoring Progress
```bash
# Claude Code (tmux)
tmux capture-pane -t claude -p -S -50

# Codex/OpenCode (process tool)
process(action="poll", session_id="<id>")
process(action="log", session_id="<id>")
```

### Kill Conditions
- No useful output for remaining budget
- Agent requests secrets/credentials
- Agent modifies files outside worktree
- Agent starts unrelated rewrites

## Per-Agent References

| Agent | Reference | Key Details |
|-------|-----------|-------------|
| Claude Code | `references/claude-code.md` | Full CLI flags, PTY dialogs, hooks, MCP, settings, slash commands |
| Codex | `references/codex.md` | Flags, worktree patterns, batch operations |
| OpenCode | `references/opencode.md` | Run command, TUI keybindings, session management |

## Critical Pitfalls (All Agents)

1. **Never trust agent self-reports** — always inspect diff and re-run tests from Hermes
2. **Always isolate in worktrees** — agents can make unexpected changes
3. **Set budget limits** — prevent runaway costs with `--max-turns` / `--max-budget-usd`
4. **Clean up** — kill processes and remove worktrees when done
5. **PTY requirement** — Codex always needs PTY; Claude Code needs tmux for interactive; OpenCode run mode doesn't need PTY