mirror of
https://github.com/NousResearch/hermes-agent.git
synced 2026-05-12 03:42:08 +00:00
98db898c0b
Completes the Windows-gating coverage for the built-in skills/ tree. Every
bundled SKILL.md now carries an explicit platforms: declaration so the
loader (agent.skill_utils.skill_matches_platform) can skip-load skills
that don't fit the current OS.
74 skills declared cross-platform (platforms: [linux, macos, windows]):
Creative (16): ascii-art, ascii-video, architecture-diagram, baoyu-comic,
baoyu-infographic, claude-design, creative-ideation, design-md,
excalidraw, humanizer, manim-video, p5js, pixel-art,
popular-web-designs, pretext, sketch, songwriting-and-ai-music,
touchdesigner-mcp
Autonomous agents: claude-code, codex, hermes-agent, opencode
Data/devops: jupyter-live-kernel, kanban-orchestrator, kanban-worker,
webhook-subscriptions, dogfood, codebase-inspection
GitHub: github-auth, github-code-review, github-issues,
github-pr-workflow, github-repo-management
Media: gif-search, heartmula, songsee, spotify, youtube-content
MCP / email / gaming / notes / smart-home: native-mcp, himalaya,
pokemon-player, obsidian, openhue
mlops (non-broken): weights-and-biases, huggingface-hub, llama-cpp,
outlines, segment-anything-model, dspy, trl-fine-tuning
Productivity: airtable, google-workspace, linear, maps, nano-pdf,
notion, ocr-and-documents, powerpoint
Red-teaming / research: godmode, arxiv, blogwatcher, llm-wiki,
polymarket
Software-dev: debugging-hermes-tui-commands, hermes-agent-skill-authoring,
node-inspect-debugger, plan, requesting-code-review, spike,
subagent-driven-development, systematic-debugging,
test-driven-development, writing-plans
Misc: yuanbao
5 skills gated from Windows (platforms: [linux, macos]):
mlops/inference/vllm (serving-llms-vllm)
vLLM is officially Linux-only; Windows requires WSL.
mlops/training/axolotl
Axolotl's flash-attn + deepspeed + bitsandbytes stack is Linux-first.
mlops/training/unsloth
Requires Triton + xformers + flash-attn — Linux only in practice.
mlops/models/audiocraft (audiocraft-audio-generation)
torchaudio ffmpeg backend + encodec dependencies are Linux-first.
mlops/inference/obliteratus
Research abliteration workflow; relies on Linux-focused pytorch
kernels and MLX — no first-class Windows path.
Same strict-over-lenient policy as the optional-skills sweep: when the
underlying tool's Windows support is rough, missing, or WSL-only, gate the
skill. Easier to un-gate after verified Windows support lands than to leak
partial support that manifests as mid-task failures.
Combined with prior commits in this branch, every bundled SKILL.md
(skills/ + optional-skills/) now has a platforms: declaration.
219 lines
7.1 KiB
Markdown
219 lines
7.1 KiB
Markdown
---
|
|
name: opencode
|
|
description: "Delegate coding to OpenCode CLI (features, PR review)."
|
|
version: 1.2.0
|
|
author: Hermes Agent
|
|
license: MIT
|
|
platforms: [linux, macos, windows]
|
|
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="<id>", data="Implement OAuth refresh flow and add tests")
|
|
|
|
# Monitor progress
|
|
process(action="poll", session_id="<id>")
|
|
process(action="log", session_id="<id>")
|
|
|
|
# Send follow-up input
|
|
process(action="submit", session_id="<id>", data="Now add error handling for token expiry")
|
|
|
|
# Exit cleanly — Ctrl+C
|
|
process(action="write", session_id="<id>", data="\x03")
|
|
# Or just kill the process
|
|
process(action="kill", session_id="<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 <id>` / `-s` | Continue a specific session |
|
|
| `--agent <name>` | Choose OpenCode agent (build or plan) |
|
|
| `--model provider/model` | Force specific model |
|
|
| `--format json` | Machine-readable output/events |
|
|
| `--file <path>` / `-f` | Attach file(s) to the message |
|
|
| `--thinking` | Show model thinking blocks |
|
|
| `--variant <level>` | Reasoning effort (high, max, minimal) |
|
|
| `--title <name>` | Name the session |
|
|
| `--attach <url>` | 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="<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`.
|