Coding Agent CLIs

A single umbrella for orchestrating external autonomous coding agent CLIs from inside Hermes. Each agent has the same job — read code, write code, run shell, manage git — but they have different CLIs, different auth, different flags, and different traps. This skill is the class-level guide; per-CLI reference docs live in references/.

Sections:

0. Shared orchestration pattern — PTY, print modes, background processes, parallel work
1. Claude Code (Anthropic) → references/claude-code.md
2. Codex CLI (OpenAI) → references/codex.md
3. OpenCode (provider-agnostic) → references/opencode.md
4. Choosing between them
5. Cross-CLI patterns — parallel batch, worktrees, PR review
6. Shared pitfalls

0. Shared Orchestration Pattern

All three CLIs share the same Hermes integration shape. The differences are in flags, auth, and mode names — the orchestration mechanics are identical.

Two integration modes (universal)

Mode	PTY?	Interactive?	Best for
One-shot / run (Claude: -p, Codex: exec, OpenCode: run)	Not required (add for some)	No	Bounded tasks, CI, structured extraction
Interactive TUI (Claude: bare claude, Codex: bare codex, OpenCode: bare opencode)	Required	Yes	Multi-turn, slash commands, exploration

Hermes terminal/process toolset

• terminal(command=..., pty=true, background=true) — start long interactive session, get a session_id
• process(action="poll"|"log", session_id=...) — monitor progress
• process(action="submit", session_id=..., data="...") — send input when agent asks
• process(action="write", session_id=..., data="\x03") — send Ctrl+C
• process(action="kill", session_id=...) — terminate
• Always set workdir — keep the agent focused on the right project
• For one-shots, prefer print/run mode and skip PTY

Universal rules

1. Git repository required. All three agents refuse to operate outside a git repo. For scratch work: cd $(mktemp -d) && git init && <agent> ....
2. PTY required for interactive TUI, optional for print/run modes.
3. Always scope to a single workdir/worktree — never share working directories across parallel sessions.
4. Use print/run mode for one-shots — cleaner, no dialog handling, exits when done.
5. Use background=true + process tool for long interactive sessions — never block the parent turn on a 30-minute coding task.
6. For parallel work, use git worktree — each agent in its own branch and directory.
7. Look for the prompt indicator (❯ Claude, > Codex/OpenCode) — that means the agent is done or asking for input.
8. Clean up bg sessions — kill them when done to avoid resource leaks.

1. Claude Code (Anthropic)

Install: npm install -g @anthropic-ai/claude-code
Auth: claude (browser OAuth) or ANTHROPIC_API_KEY
One-shot: claude -p "<task>" --allowedTools <tools> --max-turns <n>
Interactive: tmux new-session -d -s cc && tmux send-keys -t cc 'claude' Enter

Why pick it: most mature agent loop, best at multi-file refactors, richest tool ecosystem (MCP, hooks, subagents, CLAUDE.md memory, slash commands, worktrees, agent teams).

Key gotcha: --dangerously-skip-permissions presents a dialog defaulting to "No, exit" — must send Down then Enter. Print mode (-p) skips this entirely.

Full reference: references/claude-code.md — 745 lines covering CLI flags, slash commands, MCP, hooks, subagents, CLAUDE.md, settings, interactive PTY, parallel instances, PR review, cost/performance tips, and 12 specific pitfalls.

2. Codex CLI (OpenAI)

Install: npm install -g @openai/codex
Auth: OPENAI_API_KEY or Codex OAuth (hermes auth add openai-codex for Hermes-managed OAuth) — or no OpenAI account at all: point model_provider at any OpenAI-compatible /v1 endpoint (local hub, LiteLLM, vLLM). See references/codex.md.
One-shot: codex exec "<task>" (or --full-auto for sandboxed auto-approve)
Interactive: codex (with pty=true)

Why pick it: OpenAI's official coding agent, integrates with ChatGPT subscriptions, best for git worktree parallel issue fixing at scale.

Key gotcha: Hermes gateway context breaks the Codex workspace-write sandbox (bubblewrap setting up uid map: Permission denied). In that context, prefer codex exec --sandbox danger-full-access "<task>" and use process boundaries (clean git status, narrow prompts, targeted tests) as the safety layer.

Full reference: references/codex.md — 149 lines covering exec mode, --full-auto / --yolo / --sandbox danger-full-access, gateway/bubblewrap caveat, parallel worktree pattern, batch PR reviews.

3. OpenCode (provider-agnostic)

Install: npm i -g opencode-ai@latest (or brew install anomalyco/tap/opencode)
Auth: opencode auth login or provider env vars (OPENROUTER_API_KEY, etc.)
One-shot: opencode run "<task>" (no PTY needed)
Interactive: opencode (with pty=true)

Why pick it: provider-agnostic (use any model from any provider), built-in opencode pr command, session/cost tracking, --thinking for reasoning traces.

Key gotcha: Do NOT use /exit — it is not a valid OpenCode command and opens an agent selector dialog. Use Ctrl+C (\x03) or process(action="kill") to exit.

Full reference: references/opencode.md — 219 lines covering run mode, -f file context, --thinking, --model provider routing, TUI keybindings, session management, opencode pr, parallel work pattern, and 6 specific pitfalls.

4. Choosing Between Them

Need	Use
Multi-file refactor with rich tool use, MCP, hooks	Claude Code
OpenAI ecosystem, ChatGPT subscription integration	Codex
Provider-agnostic (use Claude/GPT/Gemini/local), session tracking, built-in PR command	OpenCode
Long interactive multi-turn session with slash commands	Claude Code
Bounded one-shot task with structured output	Any — prefer Claude Code for --json-schema, OpenCode for simplicity, Codex for OpenAI alignment
Batch fix N GitHub issues in parallel worktrees	Codex or OpenCode (both have clean parallel worktree patterns)
PR review of an external repo	OpenCode (opencode pr <num>) is simplest; Claude Code's --from-pr is richest
Cheapest model, fastest startup	OpenCode with --model provider/<haiku-or-mini>
CI/CD pipeline, ephemeral, no auth prompts	Claude Code --bare (fastest) or OpenCode run (no PTY)

When in doubt, default to Claude Code — it has the largest feature surface, the most mature tmux orchestration story, and the best docs.

5. Cross-CLI Patterns

These work the same way across all three CLIs.

Parallel worktrees (batch issue fixing)

# Create one worktree per issue
git worktree add -b fix/issue-78 /tmp/issue-78 main
git worktree add -b fix/issue-99 /tmp/issue-99 main

# Launch an agent in each (background)
terminal(command="claude -p 'Fix issue #78: <description>. Commit when done.' --allowedTools 'Read,Edit,Bash' --max-turns 15", workdir="/tmp/issue-78", background=true)
terminal(command="codex --yolo exec 'Fix issue #99: <description>. Commit when done.'", workdir="/tmp/issue-99", background=true, pty=true)
terminal(command="opencode run 'Fix issue #100 and commit'", workdir="/tmp/issue-100", background=true)

# Monitor all
process(action="list")

# After completion, push and create PRs (one per worktree)
for d in /tmp/issue-78 /tmp/issue-99 /tmp/issue-100; do
  (cd $d && git push -u origin $(git branch --show-current))
done

PR review (three styles)

# Claude Code — from a PR number
terminal(command="claude -p 'Review this PR thoroughly' --from-pr 42 --max-turns 10", workdir="/path/to/repo", timeout=120)

# Codex — clone + review
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)

# OpenCode — built-in command
terminal(command="opencode pr 42", workdir="/path/to/repo", pty=true)

Cost management

• All three accept a budget cap (Claude: --max-budget-usd, Codex/OpenCode: track via session stats)
• For cheap tasks, force a smaller model:
  • Claude: --model haiku or --fallback-model haiku
  • OpenCode: --model provider/<haiku-or-mini>
  • Codex: pick the model via OpenAI dashboard
• Use --max-turns (Claude) or session timeouts (Codex/OpenCode) to prevent runaway loops

6. Shared Pitfalls

These traps apply to all three CLIs:

1. PTY required for interactive TUI, optional for print/run modes. Without PTY, the TUI hangs immediately.
2. Git repository required. Agents refuse to operate outside one. Use mktemp -d && git init for scratch.
3. Don't share working directories across parallel sessions — git index, build artifacts, and lock files collide. Use git worktree.
4. Always set workdir — keep the agent focused on the right project directory.
5. Don't kill slow sessions — agents may be doing multi-step work. Check process(action="log", ...) first.
6. Background tmux/process sessions persist — always clean up with process(action="kill", ...) or tmux kill-session -t <name> when done.
7. PATH mismatch can select the wrong binary — use which -a <agent> to debug model/config mismatches.
8. Context degradation above 70% — output quality drops measurably. Start a new session for distinct work.
9. Print/run mode = deterministic exit, no prompts — preferred for any task where you don't need back-and-forth.
10. For long tasks, give the user progress updates from process logs, not just the final result.
11. Report concrete outcomes — files changed, tests, remaining risks. Not "the agent did some work".
12. Check the reference docs for per-CLI gotchas — Claude's permissions dialog, Codex's gateway sandbox failure, OpenCode's /exit trap are not in this list.