Coding Agent Guide
Hermes Agent + OpenCode: Handing Coding Jobs to the Open-Source Coding Agent
OpenCode is an open-source coding agent for the terminal. Hermes Agent is an always-on agent that lives in your chat apps. Hermes ships a skill that lets it start OpenCode, give it a coding task, watch it work and report back. This guide covers what that skill does, what you need installed, and how it differs from putting an OpenCode Go key into Hermes.
What OpenCode is
OpenCode is an MIT-licensed coding agent with a terminal UI and a scriptable CLI. It reads and edits files, runs commands, checks out pull requests, and keeps named sessions you can resume. It is provider-agnostic: you log in to whichever model providers you use with opencode auth login, or set their API keys as environment variables, and switch models per task. It has two primary agents: build, which can change your code, and plan, which by default asks before editing files or running commands.
Hermes Agent does a different job. It runs as a long-lived gateway on Telegram, Discord, Slack and other platforms, with memory, skills and scheduled tasks. Pairing them lets you send a coding request from your phone and have a real coding agent carry it out where the repo lives.
Not looking for the coding agent? If you want an OpenCode Go key as Hermes’s model, or a comparison of OpenCode with a managed agent platform, those have their own pages.
How Hermes delegates to OpenCode
Upstream Hermes bundles an opencode skill in skills/autonomous-ai-agents/, the same folder as its claude-code and codex skills. There is no special integration layer: the skill tells Hermes which OpenCode commands to run through its terminal tool and how to supervise them with its process tool. Hermes can pick the skill up when a request matches it, and like every installed Hermes skill it is also a slash command, so /opencode add retry logic to the API client loads it explicitly.
Those commands run in Hermes’s terminal backend. That is your local machine by default, but Hermes can also be configured to run its terminal in Docker, over SSH or in a cloud sandbox, and OpenCode has to be installed wherever that is.
One-shot tasks with opencode run
For a bounded task, Hermes runs a single non-interactive command in the project folder. It needs no PTY and exits when done. This is how the skill writes the Hermes tool call:
terminal(command="opencode run 'Add retry logic to API calls and update tests'", workdir="~/project")The command inside it is plain OpenCode, so the same variations work in any shell:
# attach files, force a model, or show thinking
opencode run 'Review this config for security issues' -f config.yaml
opencode run 'Refactor the auth module' --model openrouter/anthropic/claude-sonnet-4
opencode run 'Debug why tests fail in CI' --thinkingOther flags the skill documents: --agent plan for planning and analysis, --format json for machine-readable events, --variant for reasoning effort, -c or -s <id> to continue a session, and --attach <url> to reuse a running OpenCode server.
Long sessions in the background
For work that needs back-and-forth, Hermes starts the TUI with background=true, pty=true, sends prompts with process(action="submit"), and checks progress with poll or log. The skill notes that Enter sometimes has to be pressed twice to submit, and it has Hermes end the session by sending Ctrl+C or killing the process rather than typing a slash command into the TUI.
PR review and parallel work
opencode pr 42 fetches and checks out that pull request’s branch, then starts OpenCode on it; you still ask for the review, and the checkout changes the working copy you ran it in. The safer pattern is a throwaway clone: clone the repo into a temporary folder, check out the PR branch there (for example with gh pr checkout 42), then run opencode run 'Review this branch against main…' in that folder. For several tasks at once, Hermes gives each OpenCode run its own directory or git worktree, since two sessions sharing a folder will trip over each other’s edits. When a run finishes, the skill has Hermes summarise the files changed, the test results and what is left, so the reply in your chat is a report rather than a raw log. opencode stats shows token use and cost afterwards.
Setup prerequisites
- Install OpenCode in Hermes’s terminal backend.
npm i -g opencode-ai@latestorbrew install anomalyco/tap/opencode. The skill assumes the binary is already there. - Give OpenCode a provider in that same environment. Run
opencode auth login, or set a key such asOPENROUTER_API_KEYwhere Hermes’s terminal can see it; a key exported only in your own shell may not reach a gateway or container.opencode auth listshould show at least one provider. - Check which binary Hermes sees. Ask Hermes itself to run
which -a opencodeandopencode --version, and pin a full path such as~/.opencode/bin/opencodeif it resolves a different install than you expect. - Work inside a git repo. Changes are easy to review and revert, and worktrees keep parallel runs apart.
- Smoke test, then a real task.
opencode run 'Respond with exactly: OPENCODE_SMOKE_OK'proves the binary and the model login work. It does not prove repo access, so follow it with a small change in a scratch repo and confirm the expected file changed and the tests still pass.
OpenCode edits files and runs commands on its own, so point it at a checkout you can afford to throw away, not a directory with secrets or your only copy of the work.
OpenCode vs OpenCode Go: which one you are setting up
| Question | OpenCode Go | OpenCode (this page) |
|---|---|---|
| What it is | A model subscription with one API key | A coding agent program |
| Role in Hermes | Hermes’s own LLM backend | A worker Hermes launches for repo tasks |
| What you set up | Add the key as a provider | Install the opencode binary and log it in |
| Who pays for tokens | Your OpenCode Go plan | Whatever provider OpenCode is logged in to |
| Guide | OpenCode Go on Hermes | You are here |
They can work together: OpenCode itself can be logged in to OpenCode Go, which is the client Go is built for. Using the same plan for Hermes’s chat is a different matter. OpenCode’s Go docs ask clients to send coding-agent traffic with a session header, list Hermes as validated only in builds that include the fix for it, and share one set of usage limits across everything that uses your key.
How it compares with Hermes + Codex and Claude Code
The three delegation skills share a shape: a CLI run through terminal, long jobs supervised with process, one workdir per task. The difference is the tool behind them. Codex is built around OpenAI models and a ChatGPT or API login, and Claude Code around Anthropic’s models. OpenCode treats the provider as a setting, which makes it the natural pick when you want to switch models per task or already pay for a provider the other two do not default to. Hermes has no bundled skill for Gemini CLI, though it can still drive it through terminal.
The OpenClaw equivalent
OpenClaw rolls all three into one bundled coding-agent skill. It becomes available when any of claude, codex or opencode is installed, and in current upstream source it also has to be switched on with skills.entries.coding-agent.enabled. For OpenCode it runs opencode run with pty:true background:true in an isolated git worktree it prepares first. Before launching, it captures the chat route the request came from and writes it into the worker’s prompt; the worker then reports with openclaw message send instead of relying on a heartbeat. If no trustworthy route can be captured, there is no automatic completion message. For OpenCode Go models as OpenClaw’s own brain, see OpenClaw + OpenCode Go.
On OpenClaw Launch
A hosted bot on OpenClaw Launch runs in our cloud, so its terminal cannot see the repos on your laptop. For most people the practical split is simpler: keep OpenCode on your own machine for coding, and let the hosted bot handle the always-on part, which means Telegram, Discord, memory and schedules without a server to keep alive. If you want the hosted bot itself to think with an OpenCode Go model, add the key on the API Keys page.
Hermes + OpenCode FAQ
Does Hermes Agent support OpenCode out of the box?
Yes. Upstream Hermes ships an opencode skill under skills/autonomous-ai-agents/, next to its claude-code and codex skills. It teaches Hermes to run the OpenCode CLI through its terminal and process tools, and you can call it directly with /opencode. The skill assumes OpenCode is already installed and logged in to at least one provider; it does not set that up for you.
Is this the same as using an OpenCode Go key in Hermes?
No. An OpenCode Go key makes a model subscription Hermes’s own LLM backend, so Hermes itself thinks with models such as DeepSeek or Kimi. That is covered in OpenCode Go on Hermes Agent. This page is about OpenCode the coding agent: a separate program Hermes starts to do repo work. You can use either one, or both.
Which model does OpenCode use when Hermes calls it?
Whatever OpenCode is configured with, not Hermes’s model. OpenCode is provider-agnostic: opencode auth login or provider environment variables decide what it can reach, and opencode run … --model provider/model forces a specific one for a single task. So a Hermes bot can chat on one model while OpenCode codes on another.
Why can’t Hermes find OpenCode, or why does it fail to log in?
Hermes runs commands in its own terminal backend, which is not necessarily your shell. The default backend is local, but it can also be Docker, SSH or a cloud sandbox, each with its own PATH and environment. Ask Hermes to run which -a opencode, opencode --version and opencode auth list itself. If the binary is missing, install it there; if a key you exported in your own terminal is missing, put it where that backend can see it, or use opencode auth login in that environment.
Can OpenClaw use OpenCode too?
Yes. OpenClaw bundles a coding-agent skill that delegates to Claude Code, Codex or OpenCode. It needs one of those binaries installed and, in current upstream source, skills.entries.coding-agent.enabled switched on. For OpenCode it launches opencode run in the background with a PTY inside an isolated worktree, and the worker reports back with openclaw message send to the chat route captured when the job started.