external-coding-agents

Files (1)

• SKILL.md

SKILL.md (first lines)

# External AI Coding Agents

Delegate coding work to third-party AI coding agents from within Hermes. These tools (Claude Code, Codex, OpenCode) are autonomous CLI agents that can read files, write code, run shell commands, and manage git workflows — each with its own strengths.

## When to Delegate vs Do It Yourself

| Situation | Approach |
|-----------|----------|
| Bug fix in a known file | Do it yourself with `patch`/`write_file` — faster, no overhead |
| Complex multi-file refactor | Delegate — the external agent has persistent context across files |
| Task needs a fresh perspective | Delegate — the external agent will spot things you might miss |
| CI/CD automation | Delegate — use print mode for clean automation |
| PR review of someone else's code | Delegate — the external agent can see the full diff in context |
| Research/reconnaissance | Delegate — agent can browse and explore independently |
| Simple one-line change | Do it yourself |

## Common Orchestration Patterns

All three coding agents use the same core patterns:

### Print Mode (Non-Interactive — Preferred)
Cleanest integration. No PTY, no dialog handling, structured output:

```
terminal(command="<agent> -p 'Add error handling to all API calls in src/'", workdir="/path/to/project", timeout=120)
```

### PTY Background Mode (Interactive)
For iterative work needing multi-turn conversation. Use `background=true, pty=true` and `process` tool to monitor:

```
terminal(command="<agent>", workdir="~/project", background=true, pty=true)
process(action="submit", session_id="<id>", data="Implement OAuth refresh flow")
process(action="poll", session_id="<id>")
process(action="log", session_id="<id>")
process(action="kill", session_id="<id>")
```

### Get the Diff Back
After delegation completes, always inspect what changed:

```
git diff
git diff --stat
```

## Agent Decision Guide

| Need | Best Agent | Why |
|------|-----------|-----|
| Best overall coding ability | Claude Code | Anthropic's most capable model, v2.2+, rich feature set |
| Cheapest / open-source preference | OpenCode | Provider-agnostic (OpenRouter, Anthropic, OpenAI, local models) |
| OpenAI ecosystem | Codex | OpenAI's autonomous agent, OAuth integration |
| PR review with inline comments | Claude Code | Built-in `--from-pr` flag, formal review workflow |
| Batch multi-issue fixing | Codex or OpenCode | Lightweight, parallel worktree pattern |
| Long-running autonomous session | Any | Use background=true + process tool for monitoring |

## Common Pitfalls

1. **PTY is required for interactive sessions** — all three agents are TUI apps; skip `pty=true` and they hang
2. **Git repo required** — Codex and OpenCode refuse to run outside a git directory. Use `mktemp -d && git init` for scratch work
3. **Always inspect the diff after delegation** — external agents can make surprising decisions. Use `git diff --stat` to verify scope
4. **Keep tasks focused** — narrow prompts produce better results than vague requests
5. **Set timeouts** — external agents can loop indefinitely. Use `--max-turns` (Claude Code) or `timeout` in terminal calls
6. **Cleanup background sessions** — kill tmux sessions and worktree directories when done
7. **Parallel worktrees need isolation** — don't share a single working directory across parallel agents

## Agent-Specific References

Detailed reference docs for each agent:

- **references/claude-code.md** — Full Claude Code orchestration guide (flags, auth, hooks, MCP, slash commands, 745 lines)
- **references/codex.md** — Codex CLI usage (flags, background mode, worktrees)
- **references/opencode.md** — OpenCode CLI usage (binary resolution, parallel patterns, TUI keybindings)

## Getting Started

### Which Agent is Installed?

```
which claude codex opencode 2>/dev/null || echo "check npm list -g"
```

### Quick One-Shot (any agent)

```
# Claude Code
terminal(command="claude -p 'Add input validation to all endpoint handlers' --max-turns 10", workdir="~/project", timeout=120)

# Codex
terminal(command="codex exec 'Add input validation to all endpoint handlers'", workdir="~/project", pty=true)

# OpenCode
terminal(command="opencode run 'Add input validation to all endpoint handlers'", workdir="~/project")
```

From S3YED/appie-kit, MIT.

More from S3YED/appie-kit