103 lines
6.3 KiB
Markdown
103 lines
6.3 KiB
Markdown
---
|
|
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)
|
|
```
|