---
name: ai-coding-agents
description: "AI coding agent integrations: OpenAI Codex CLI, Anthropic Claude Code, and OpenCode CLI for delegating coding tasks."
version: 2.0.0
author: Hermes Agent
license: MIT
platforms: [linux, macos, windows]
metadata:
  hermes:
    tags: [codex, claude-code, opencode, ai-agent, coding, delegation]
    related_skills: [development-workflow, kanban-workflow]
---

# AI Coding Agent Integrations

Three AI coding agent CLIs for delegating implementation work. All three follow a similar pattern: launch the agent in a workspace, provide context via prompt, monitor execution, and verify output.

## Section 1: OpenAI Codex CLI

Delegate coding tasks to OpenAI's Codex CLI agent. Supports `codex exec` for bounded one-shot edits and `/goal` mode for multi-step work.

**When to use:** Bounded coding tasks (features, bug fixes, refactors) where an autonomous coding agent can work independently.
**Key pattern:** Always run in an isolated git worktree/branch; Codex output is untrusted until reviewed.
**Prerequisite:** Verify your provider supports `/v1/responses` before attempting — see `references/codex-custom-provider.md` for endpoint probe commands. Most third-party endpoints (DeepSeek, 智谱, OneAPI) lack this endpoint.
**Auth:** `codex login --device-auth` (browser-based OpenID OAuth, needs PTY in terminal) or `OPENAI_API_KEY` env var. On this headless server, device-auth is the only path — Hermes starts it as a background PTY process and relays the one-time code to the user.
**See:** `references/codex.md` for workflows, `references/codex-custom-provider.md` for custom endpoint config and readiness diagnostic.

## Section 2: Anthropic Claude Code

Delegate coding tasks to Anthropic's Claude Code CLI. Interactive coding agent with tool use capabilities.

**When to use:** Complex coding tasks requiring reasoning, refactoring, or multi-file changes via Claude.

**Working models:** `claude-sonnet-4-5-20250929` (daily driver) and `claude-opus-4-20250514` (heavy lifting — architecture review, complex bugs). Both tested working 2026-06-14.

**Pitfall — stale model config:** Claude Code reads its default model from `~/.claude/settings.json`. If this file references a model that no longer exists (we hit `claude-fable-5[1m]` on 2026-06-14), `claude -p` will fail silently — the agent gets an error string instead of a tool result. Fix: `claude config set model claude-opus-4-20250514` or directly edit `~/.claude/settings.json`. Always verify with `claude -p "what model are you" --output-format text --max-turns 1 --dangerously-skip-permissions` after changing models.

**Hermes integration — the only working path:** Use `terminal(background=true, notify_on_complete=true)` with `claude -p`.
The `agent.subagent.provider: claude-code` config and ACP transport (`--acp --stdio`)
are **non-functional** — Claude Code v2.x does not support them. Do not use
`delegate_task(acp_command='claude')`.

```bash
# Run Claude Code review via Hermes terminal
terminal(command="cd /path/to/repo && claude -p '<prompt>' --output-format text --max-turns 6",
         background=true, notify_on_complete=true, timeout=600)
```

**Parallel reviews:** Launch multiple `terminal(background=true)` calls simultaneously — each Claude Code instance runs independently and notifies on completion. For the full AtomK three-repo review + spec + re-review workflow, see `references/atomk-parallel-review-workflow.md`.

**Scope for large repos:** Always provide an explicit file list in the prompt (e.g., `读 src/main/index.ts, src/main/auth.ts...`) rather than broad directories like `src/main/`. Large repos easily exhaust `--max-turns` on file discovery. Start with 8-10 files; if max turns hit, progressively narrow to 5-8 core files. Always include `--dangerously-skip-permissions` to avoid wasting turns on dialogs. Start with `--max-turns 8` and increase to 12+ only for narrow scopes.

**See:** `references/claude-code.md`. For the full comparison of both working Hermes subagent
paths (built-in `delegate_task` vs external `claude -p`), see
`references/hermes-subagent-comparison.md`.

## Section 3: OpenCode CLI

Delegate coding tasks via the OpenCode CLI. An alternative coding agent for features and PR review.

**When to use:** When the user prefers OpenCode as their coding agent, or for PR review workflows.
**See:** `references/opencode.md`.

## Shared Principles

1. **Isolate workspace** — always use git worktrees or branches, never run in a dirty main checkout
2. **Agent output is untrusted** — Hermes reviews, reconciles, and verifies before accepting
3. **Hermes owns lifecycle** — Hermes starts, monitors, and decides to accept/reject agent output
4. **Don't let agents own durable state** — Hermes writes kanban state, not the coding agent
5. **Verify with canonical tests** — run tests from Hermes, not just rely on agent self-report

## Section 4: Collaborative Multi-Agent Setup

All three tools (Hermes, Codex, Claude Code) can coexist on the same machine — CLI
entry points and install paths are independent. Note: Codex CLI requires a provider
with `/v1/responses` endpoint support (real OpenAI or OpenRouter); on our infrastructure
(DeepSeek/智譜/OneAPI/Google) it is **not viable**. See `references/collaborative-setup.md`.

**See:** `references/collaborative-setup.md` for full guide.

### Division of labor

| Agent | Status | Best for | Avoid |
|-------|--------|----------|-------|
| **Hermes Agent** | ✅ | Orchestration, task decomposition, progress tracking | Hands-on code edits (delegate those) |
| **Claude Code** (Sonnet 4.5) | ✅ | Deep reasoning, complex bug hunting, code review, heavy refactors | Batch/bulk repetitive work |
| **Claude Code** (Opus 4) | ✅ | Architecture review, hardest bugs, large-scale refactors | Routine tasks (use Sonnet instead) |
| **Codex CLI** | ❌ | — | Unavailable on this system (no `/v1/responses` endpoint) |

### Quick setup

```bash
mkdir -p /workspace/my-project && cd /workspace/my-project
touch CHANGES.log CLAUDE.md AGENTS.md
```

Claude Code is invoked via `terminal(background=true)` in Hermes:
```bash
# The real working path — NOT agent.subagent.provider (dead config)
terminal(command="claude -p '<prompt>' --output-format text --max-turns 6 --dangerously-skip-permissions",
         background=true, notify_on_complete=true, timeout=600)
```