OpenCode Skill for Hermes Agent: Delegate Coding to an External Agent

OpenCode is a provider-agnostic, open-source AI coding agent with both a TUI and a CLI. The OpenCode skill in Hermes Agent lets you hand coding work to that agent from inside a Hermes session: one-shot tasks, long interactive sessions, PR reviews, and parallel jobs in separate worktrees. Reach for it when you want an external coding worker to implement, refactor, or review code while Hermes orchestrates the run.

What it does

The skill wraps OpenCode's command-line surface in Hermes terminal and process tools. You can fire a bounded task with opencode run, start the interactive TUI in the background for multi-turn work, poll and log its progress, and send follow-up input without leaving the Hermes session. It also covers the operational edges: resolving the right binary, resuming sessions, checking token usage, and exiting cleanly.

This is useful when the user explicitly asks for OpenCode, when you want an external agent to implement or refactor code, when a coding session will run long enough to need progress checks, or when you want parallel tasks isolated in separate workdirs or worktrees.

Before you start

You need OpenCode installed. The source gives two install paths: npm i -g opencode-ai@latest or brew install anomalyco/tap/opencode.

You also need authentication configured. Run opencode auth login, or set provider environment variables such as OPENROUTER_API_KEY. Verify with opencode auth list; it should show at least one provider.

For code tasks, a Git repository is recommended. Interactive TUI sessions require pty=true.

Binary resolution

Shell environments can resolve different OpenCode binaries. If behavior differs between your terminal and Hermes, check which binaries are on the path and what version is being picked up:

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 in the 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 / -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="~/.hermes/cache/scratch/issue-101", background=true, pty=true)
terminal(command="opencode run 'Add parser regression tests and commit'", workdir="~/.hermes/cache/scratch/issue-102", background=true, pty=true)
process(action="list")

Session and 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")

When not to use it

The source does not list explicit exclusions, but the rules point to a clear preference: use opencode run for one-shot automation because it is simpler and does not need pty. Reserve interactive background mode for cases where iteration is actually needed. If you do not need an external coding agent, the related skills (claude-code, codex, hermes-agent) are the alternatives to consider.

Limits and gotchas

• 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.

What pairs with this

The source lists three related skills: claude-code, codex, and hermes-agent. Use them when you want a different external coding agent or when the task belongs to Hermes itself rather than an external worker.