opencode
Delegate coding to OpenCode CLI (features, PR review).
- License 许可
- MIT
- 最近更新
- 2026-08-31
- Stars
- ★ 0
- Forks
- 0
01 前言 Front Matter
- name
- opencode
- author
- Hermes Agent
- license
- MIT
- version
- 1.2.0
- metadata
- { "hermes": { "tags": [ "Coding-Agent", "OpenCode", "Autonomous", "Refactoring", "Code-Review" ], "related_skills": [ "claude-code", "codex", "hermes-agent" ] } }
- platforms
- [ "linux", "macos", "windows" ]
- description
- Delegate coding to OpenCode CLI (features, PR review).
03 SKILL.md 正文
OpenCode CLI
Use OpenCode 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@latestorbrew install anomalyco/tap/opencode - Auth configured:
opencode auth loginor set provider env vars (OPENROUTER_API_KEY, etc.) - Verify:
opencode auth listshould show at least one provider - Git repository for code tasks (recommended)
pty=truefor 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
- Verify tool readiness:
terminal(command="opencode --version")terminal(command="opencode auth list")
- For bounded tasks, use
opencode run '...'(no pty needed). - For iterative tasks, start
opencodewithbackground=true, pty=true. - Monitor long tasks with
process(action="poll"|"log"). - If OpenCode asks for input, respond via
process(action="submit", ...). - Exit with
process(action="write", data="\x03")orprocess(action="kill"). - 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 requirepty=true. Theopencode runcommand does NOT need pty. /exitis 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
- Prefer
opencode runfor one-shot automation — it's simpler and doesn't need pty. - Use interactive background mode only when iteration is needed.
- Always scope OpenCode sessions to a single repo/workdir.
- For long tasks, provide progress updates from
processlogs. - Report concrete outcomes (files changed, tests, remaining risks).
- Exit interactive sessions with Ctrl+C or kill, never
/exit.
04 同仓库更多 Skills
skill-installer
Install Codex skills into $CODEX_HOME/skills from a curated list or a GitHub repo path. Use when a user asks to list installable skills, install a curated skill, or install a skill from another repo (including private repos).
skill-creator
Guide for creating effective skills. This skill should be used when users want to create a new skill (or update an existing skill) that extends Codex's capabilities with specialized knowledge, workflows, or tool integrations.
openai-docs
Use for Codex models/pricing, scheduled tasks, skills, settings, setup, troubleshooting, customization, automations, and self-knowledge—including 'you,' 'your,' 'this app,' or 'this coding agent' when they refer to Codex—and for OpenAI APIs/products and ChatGPT Work. Also use for model choice/migration, prompting, SDKs, Responses, Realtime, agents, evals, and Chat/Work/Codex comparisons. Do not use for generic app/software tasks that merely mention Codex.
imagegen
Generate or edit raster images when the task benefits from AI-created bitmap visuals such as photos, illustrations, textures, sprites, mockups, or transparent-background cutouts. Use when Codex should create a brand-new image, transform an existing image, or derive visual variants from references, and the output should be a bitmap asset rather than repo-native code or vector. Do not use when the task is better handled by editing existing SVG/vector/code-native assets, extending an established icon or logo system, or building the visual directly in HTML/CSS/canvas.
skill-creator-cc
Create new skills, modify and improve existing skills, and measure skill performance. Use when users want to create a skill from scratch, update or optimize an existing skill, run evals to test a skill, benchmark skill performance with variance analysis, or optimize a skill's description for better triggering accuracy.
prd-writing-guide
Write complete, unambiguous PRDs that development teams can implement without guesswork. Includes requirement discovery framework, structured documentation methodology, completeness checklists, and common pitfall avoidance. Use when: writing new PRDs, reviewing PRD drafts, validating requirement completeness, preparing for engineering handoff. Triggers: 'write PRD', '写PRD', '产品需求文档', '需求文档', '需求规格', '需求评审', '完善需求', 'create requirements doc', 'product requirements', 'feature spec', 'requirements document'. Anti-triggers: 'technical design doc', 'architecture design', 'implementation plan', 'API design', '架构设计', '技术方案', '实现方案', '接口设计'.