diff --git a/skills/autonomous-ai-agents/opencode/SKILL.md b/skills/autonomous-ai-agents/opencode/SKILL.md new file mode 100644 index 000000000..37707dbce --- /dev/null +++ b/skills/autonomous-ai-agents/opencode/SKILL.md @@ -0,0 +1,218 @@ +--- +name: opencode +description: Delegate coding tasks to OpenCode CLI agent for feature implementation, refactoring, PR review, and long-running autonomous sessions. Requires the opencode CLI installed and authenticated. +version: 1.2.0 +author: Hermes Agent +license: MIT +metadata: + hermes: + tags: [Coding-Agent, OpenCode, Autonomous, Refactoring, Code-Review] + related_skills: [claude-code, codex, hermes-agent] +--- + +# OpenCode CLI + +Use [OpenCode](https://opencode.ai) as an autonomous coding worker orchestrated by Hermes terminal/process tools. OpenCode is a provider-agnostic, open-source AI coding agent with a TUI and CLI. + +## When to Use + +- User explicitly asks to use OpenCode +- You want an external coding agent to implement/refactor/review code +- You need long-running coding sessions with progress checks +- You want parallel task execution in isolated workdirs/worktrees + +## Prerequisites + +- OpenCode installed: `npm i -g opencode-ai@latest` or `brew install anomalyco/tap/opencode` +- Auth configured: `opencode auth login` or set provider env vars (OPENROUTER_API_KEY, etc.) +- Verify: `opencode auth list` should show at least one provider +- Git repository for code tasks (recommended) +- `pty=true` for interactive TUI sessions + +## Binary Resolution (Important) + +Shell environments may resolve different OpenCode binaries. If behavior differs between your terminal and Hermes, check: + +``` +terminal(command="which -a opencode") +terminal(command="opencode --version") +``` + +If needed, pin an explicit binary path: + +``` +terminal(command="$HOME/.opencode/bin/opencode run '...'", workdir="~/project", pty=true) +``` + +## One-Shot Tasks + +Use `opencode run` for bounded, non-interactive tasks: + +``` +terminal(command="opencode run 'Add retry logic to API calls and update tests'", workdir="~/project") +``` + +Attach context files with `-f`: + +``` +terminal(command="opencode run 'Review this config for security issues' -f config.yaml -f .env.example", workdir="~/project") +``` + +Show model thinking with `--thinking`: + +``` +terminal(command="opencode run 'Debug why tests fail in CI' --thinking", workdir="~/project") +``` + +Force a specific model: + +``` +terminal(command="opencode run 'Refactor auth module' --model openrouter/anthropic/claude-sonnet-4", workdir="~/project") +``` + +## Interactive Sessions (Background) + +For iterative work requiring multiple exchanges, start the TUI in background: + +``` +terminal(command="opencode", workdir="~/project", background=true, pty=true) +# Returns session_id + +# Send a prompt +process(action="submit", session_id="", data="Implement OAuth refresh flow and add tests") + +# Monitor progress +process(action="poll", session_id="") +process(action="log", session_id="") + +# Send follow-up input +process(action="submit", session_id="", data="Now add error handling for token expiry") + +# Exit cleanly — Ctrl+C +process(action="write", session_id="", data="\x03") +# Or just kill the process +process(action="kill", session_id="") +``` + +**Important:** Do NOT use `/exit` — it is not a valid OpenCode command and will open an agent selector dialog instead. Use Ctrl+C (`\x03`) or `process(action="kill")` to exit. + +### TUI Keybindings + +| Key | Action | +|-----|--------| +| `Enter` | Submit message (press twice if needed) | +| `Tab` | Switch between agents (build/plan) | +| `Ctrl+P` | Open command palette | +| `Ctrl+X L` | Switch session | +| `Ctrl+X M` | Switch model | +| `Ctrl+X N` | New session | +| `Ctrl+X E` | Open editor | +| `Ctrl+C` | Exit OpenCode | + +### Resuming Sessions + +After exiting, OpenCode prints a session ID. Resume with: + +``` +terminal(command="opencode -c", workdir="~/project", background=true, pty=true) # Continue last session +terminal(command="opencode -s ses_abc123", workdir="~/project", background=true, pty=true) # Specific session +``` + +## Common Flags + +| Flag | Use | +|------|-----| +| `run 'prompt'` | One-shot execution and exit | +| `--continue` / `-c` | Continue the last OpenCode session | +| `--session ` / `-s` | Continue a specific session | +| `--agent ` | Choose OpenCode agent (build or plan) | +| `--model provider/model` | Force specific model | +| `--format json` | Machine-readable output/events | +| `--file ` / `-f` | Attach file(s) to the message | +| `--thinking` | Show model thinking blocks | +| `--variant ` | Reasoning effort (high, max, minimal) | +| `--title ` | Name the session | +| `--attach ` | Connect to a running opencode server | + +## Procedure + +1. Verify tool readiness: + - `terminal(command="opencode --version")` + - `terminal(command="opencode auth list")` +2. For bounded tasks, use `opencode run '...'` (no pty needed). +3. For iterative tasks, start `opencode` with `background=true, pty=true`. +4. Monitor long tasks with `process(action="poll"|"log")`. +5. If OpenCode asks for input, respond via `process(action="submit", ...)`. +6. Exit with `process(action="write", data="\x03")` or `process(action="kill")`. +7. Summarize file changes, test results, and next steps back to user. + +## PR Review Workflow + +OpenCode has a built-in PR command: + +``` +terminal(command="opencode pr 42", workdir="~/project", pty=true) +``` + +Or review in a temporary clone for isolation: + +``` +terminal(command="REVIEW=$(mktemp -d) && git clone https://github.com/user/repo.git $REVIEW && cd $REVIEW && opencode run 'Review this PR vs main. Report bugs, security risks, test gaps, and style issues.' -f $(git diff origin/main --name-only | head -20 | tr '\n' ' ')", pty=true) +``` + +## Parallel Work Pattern + +Use separate workdirs/worktrees to avoid collisions: + +``` +terminal(command="opencode run 'Fix issue #101 and commit'", workdir="/tmp/issue-101", background=true, pty=true) +terminal(command="opencode run 'Add parser regression tests and commit'", workdir="/tmp/issue-102", background=true, pty=true) +process(action="list") +``` + +## Session & Cost Management + +List past sessions: + +``` +terminal(command="opencode session list") +``` + +Check token usage and costs: + +``` +terminal(command="opencode stats") +terminal(command="opencode stats --days 7 --models anthropic/claude-sonnet-4") +``` + +## Pitfalls + +- Interactive `opencode` (TUI) sessions require `pty=true`. The `opencode run` command does NOT need pty. +- `/exit` is NOT a valid command — it opens an agent selector. Use Ctrl+C to exit the TUI. +- PATH mismatch can select the wrong OpenCode binary/model config. +- If OpenCode appears stuck, inspect logs before killing: + - `process(action="log", session_id="")` +- Avoid sharing one working directory across parallel OpenCode sessions. +- Enter may need to be pressed twice to submit in the TUI (once to finalize text, once to send). + +## Verification + +Smoke test: + +``` +terminal(command="opencode run 'Respond with exactly: OPENCODE_SMOKE_OK'") +``` + +Success criteria: +- Output includes `OPENCODE_SMOKE_OK` +- Command exits without provider/model errors +- For code tasks: expected files changed and tests pass + +## Rules + +1. Prefer `opencode run` for one-shot automation — it's simpler and doesn't need pty. +2. Use interactive background mode only when iteration is needed. +3. Always scope OpenCode sessions to a single repo/workdir. +4. For long tasks, provide progress updates from `process` logs. +5. Report concrete outcomes (files changed, tests, remaining risks). +6. Exit interactive sessions with Ctrl+C or kill, never `/exit`.