Add autonomous-ai-agents/ai-coding-agents
This commit is contained in:
@@ -0,0 +1,102 @@
|
||||
---
|
||||
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)
|
||||
```
|
||||
Reference in New Issue
Block a user