6.3 KiB
name, description, version, author, license, platforms, metadata
| name | description | version | author | license | platforms | metadata | |||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| ai-coding-agents | AI coding agent integrations: OpenAI Codex CLI, Anthropic Claude Code, and OpenCode CLI for delegating coding tasks. | 2.0.0 | Hermes Agent | MIT |
|
|
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').
# 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
- Isolate workspace — always use git worktrees or branches, never run in a dirty main checkout
- Agent output is untrusted — Hermes reviews, reconciles, and verifies before accepting
- Hermes owns lifecycle — Hermes starts, monitors, and decides to accept/reject agent output
- Don't let agents own durable state — Hermes writes kanban state, not the coding agent
- 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
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:
# 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)