opencode-hermes-mcp
The server is an MCP controller that lets a supervisor LLM delegate coding tasks to a persistent OpenCode server and supervise them interactively.
Start coding tasks:
opencode_runsubmits a task (with directory, task, and agent) and blocks until completion, error, or input is needed.Resume turns: Continue an existing session/turn without resubmitting the prompt; resume after restarts or when input is required.
Answer questions:
opencode_answerresponds to OpenCode questions with exact option labels or custom answers and keeps blocking.Handle permissions:
opencode_permissiondecidesonce,always, orrejectfor pending permission requests.Abort runs:
opencode_abortstops a stuck or active session.Inspect sessions:
opencode_inspectgives a one-shot diagnostic snapshot of a session (not for polling).List sessions:
opencode_sessionslists OpenCode sessions for a directory so you can reuse a session.
Provides tools for the Hermes supervisor LLM to delegate coding tasks to an OpenCode server, including running tasks, answering questions, granting permissions, aborting runs, and inspecting sessions.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@opencode-hermes-mcp Refactor the login flow to use async/await and add unit tests."
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
opencode-hermes-mcp
Deterministic MCP controller between Hermes (supervisor LLM) and the permanent OpenCode server. The controller is a state machine — no LLM — that blocks on OpenCode turns and surfaces questions/permissions to Hermes so the supervisor LLM can decide and resume the same turn.
Architecture
Hermes (LLM) --MCP stdio--> opencode_hermes_mcp.server (FastMCP, 6 tools) --HTTP + SSE--> OpenCode server :4096Layer 1 — Hermes: the supervisor LLM. It delegates a coding task with
opencode_runand decides when the controller reportsneeds_agent_input(question / permission).Layer 2 — this controller (
opencode_hermes_mcp/:server.py+controller.py+client.py+models.py): a NO-LLM process spawned by Hermes over MCP stdio. It submits the task, watches SSE + REST, blocks until the turn completes / errors / needs input, and posts the supervisor's decisions back into the same OpenCode turn (the prompt is never resubmitted).Layer 3 — OpenCode server: a permanent
opencode serveprocess (systemd user serviceopencode-server, loopback :4096, HTTP basic auth). Its LLM is any supported provider (OpenAI-compatible endpoint, OpenAI, or Anthropic), configured in~/.config/opencode/opencode.json.
Tools exposed to Hermes: opencode_run, opencode_answer,
opencode_permission, opencode_abort, opencode_inspect (diagnostic
only), opencode_sessions.
Related MCP server: opencode-mcp
Prerequisites
Hermes installed (
~/.hermes/config.yamlpresent)python3>= 3.11 (with PyYAML for the Hermes config patch)Network access (OpenCode binary install,
mcppackage, LLM endpoint)systemduser sessions (for theopencode-serverservice)
Installation (2 commands)
git clone <repo-url> opencode-hermes-mcp && cd opencode-hermes-mcp
scripts/install.shscripts/install.sh is a thin wrapper around the setup wizard
(opencode_hermes_mcp/installer.py, Python + rich): banner, numbered
steps, styled prompts, progress, and a summary panel. The wizard bootstraps
itself — if the repo venv is missing (or lacks rich / pyyaml /
mcp==1.12.4 / the editable package), it creates it and re-execs, so a bare
python3 >= 3.11 is the only prerequisite.
The install is idempotent — re-running it skips what is already in place.
It installs the pinned OpenCode binary, the venv (the opencode_hermes_mcp
package with mcp==1.12.4 pinned), the LLM provider config + secret, the
server credentials, the two launchers, the systemd user service, and patches
~/.hermes/config.yaml (backup kept as .bak). It finishes with a health
check (bounded curl --max-time 3, last error surfaced) +
python -m opencode_hermes_mcp.smoke_client (must print
tool surface OK).
LLM providers
The installer is provider-agnostic. Three providers are supported:
Provider | Use | npm package |
| any OpenAI-compatible endpoint (Unsloth, Ollama, vLLM, llama-server, ...) — default |
|
| official OpenAI API |
|
| official Anthropic API |
|
Interactive: pick the provider from the menu, then answer the prompts —
base URL + API key + model for openai-compatible, API key + model for
openai / anthropic — then the LLM speed (slow for a local LLM, which
adds timeout:false / headerTimeout:false / chunkTimeout:120000 to the
provider options; fast is the default) and the model limits (context /
output, defaults 128000 / 32000).
Non-interactive (--yes), everything comes from env. Local
OpenAI-compatible endpoint (Ollama / vLLM / Unsloth / ...):
OPENCODE_PROVIDER=openai-compatible \
OPENCODE_LLM_BASE_URL=http://127.0.0.1:11434/v1 \
OPENCODE_API_KEY=... \
OPENCODE_LLM_MODEL=qwen3.8-27b \
OPENCODE_LLM_SPEED=slow \
scripts/install.sh --yesOpenAI (cloud):
OPENCODE_PROVIDER=openai OPENCODE_API_KEY=sk-... OPENCODE_LLM_MODEL=gpt-4o \
scripts/install.sh --yesAnthropic (cloud):
OPENCODE_PROVIDER=anthropic OPENCODE_API_KEY=sk-ant-... \
OPENCODE_LLM_MODEL=claude-sonnet-4-5 scripts/install.sh --yesFlags: --yes (non-interactive, uses env OPENCODE_PROVIDER /
OPENCODE_LLM_BASE_URL / OPENCODE_API_KEY / OPENCODE_LLM_MODEL /
OPENCODE_LLM_SPEED / OPENCODE_CONTEXT_LIMIT / OPENCODE_OUTPUT_LIMIT),
--port N (default 4096), --skip-binary, --force-config, --dry-run,
--skip-verify (skip the final health + smoke verification — useful for
sandbox/CI).
UNSLOTH_API_KEY is still accepted as a deprecated fallback for
OPENCODE_API_KEY (existing scripts keep working).
A new Hermes session is required after installation to load the MCP server.
Hermes integration (manual)
The installer patches ~/.hermes/config.yaml for you, but it does not
install a Hermes skill on purpose (Hermes's skill layout may change). The
package ships the full manual instead:
docs/hermes-integration.md— what the MCP is for, the exact config entry written, manual integration (by hand), the six tools, troubleshooting, uninstall.docs/skill.example.md— a ready-to-copy Hermes skill (the delegation protocol) to drop into~/.hermes/skills/and adapt.
Usage
Hermes delegates work through the MCP tools — no manual CLI needed:
opencode_run(directory, task, agent)— submit a task; blocks until the turn completes, errors, or needs input.agentis required for a new session (a primary agent of the project, e.g.build,plan, or a project-specific agent).When a tool returns
state=needs_agent_input, Hermes decides:opencode_answer(pick exact option labels) oropencode_permission(once/always/reject) — both resume the same turn.opencode_abortstops a stuck run;opencode_sessionslists sessions for a directory;opencode_inspectis for exceptional diagnostics only (never poll a running task).
The Hermes-side wiring (written by scripts/install.sh into
~/.hermes/config.yaml):
mcp_servers:
opencode:
command: ~/.local/bin/opencode-mcp-launch.sh
enabled: true
timeout: 14400
connect_timeout: 30
supports_parallel_tool_calls: false
timeouts:
tools:
sequential_call: 14400
concurrent_batch: 14400The launcher reads the OpenCode server credentials from
~/.config/hermes/opencode-server.json and execs
python -m opencode_hermes_mcp.server in the repo venv — config.yaml stays
secret-free.
Delegation journal
Every opencode_run is recorded in a durable, append-only JSONL journal so
the delegation history survives sessions (the per-turn state file
turn_<sid>.json is cleared on completion). One line per record:
{"ts": 1787750000123, "kind": "start", "session_id": "ses_...", "directory": "/abs/repo", "agent": "build", "task": "...(truncated to 500 chars)"}
{"ts": 1787750100456, "kind": "end", "session_id": "ses_...", "directory": "/abs/repo", "state": "completed|error|aborted|timeout", "elapsed_ms": 100333, "files": 12, "additions": 1209, "deletions": 18, "changed_files": ["a.py", "..."]}Path:
~/.local/state/opencode-hermes-mcp/delegations.jsonlby default, overridable with theOPENCODE_HERMES_MCP_JOURNALenv var.tsis epoch milliseconds;stateis the run's terminal state;changed_filesis truncated to 50 entries.The journal is best-effort: a write failure (disk full, permissions) is logged and swallowed — it never fails a run.
Read-only access for consumers:
opencode_hermes_mcp.journal.read_journal().
TUI attach helpers (watch OpenCode live)
install.sh also drops two helpers into ~/.local/bin/ (sources:
scripts/helpers/):
ocattach <repo-abs> [ses_...] # open the OpenCode TUI on a repo / session
oc-current # attach to the session Hermes is supervising NOWocattachopens the OpenCode TUI (opencode attach) against the permanent server:4096— no tmux needed. Without a session id it opens the latest session / lets you pick one.oc-currentreads the newest~/.local/state/opencode-hermes-mcp/turn_*.json(the controller's in-flight turn state) and attaches to that session — use it while Hermes is driving OpenCode, to watch the reasoning live.
Both read the server credentials from ~/.config/hermes/opencode-server.json
(same source as the controller launcher). Do not press Esc/Ctrl+C in the TUI
while a turn is active — that aborts the in-flight turn on the OpenCode side.
Upgrade / uninstall
scripts/upgrade.sh # controller only: git pull + venv deps + restart + smoke
scripts/upgrade.sh --binary # install the PINNED OpenCode binary (idempotent) — see "Version pin" below
scripts/uninstall.sh # service, launchers, venv, hermes entry, credentials
scripts/uninstall.sh --purge # + OpenCode provider config + API key secret
scripts/uninstall.sh --purge-binary # + the OpenCode binaryuninstall.sh never touches the git clone, the OpenCode provider config, the
API key secret, or the binary (unless the purge flags say so).
Version pin: OpenCode 1.18.31
The controller is validated against OpenCode 1.18.31 only (its endpoint
contract was verified against that binary's live /doc, not the web docs).
The pin is a single source of truth in opencode_hermes_mcp/pin.txt
(one line, no v prefix): installer.py and scripts/upgrade.sh both read
it, falling back to the built-in constant when the file is missing or empty
(e.g. pip installs where the file is not shipped next to the code). install.sh pins
the binary to that version; upgrade.sh never upgrades the binary by
default.
scripts/upgrade.sh --binary (no version) installs the pinned version and is
idempotent (no-op if the binary is already at the pin). --binary latest is
the explicit opt-in to the bleeding edge; --binary X.Y.Z installs the
requested version. For anything other than the pin, the script warns you and
you MUST re-validate the controller before trusting it:
.venv/bin/python tests/run_tests.py(all checks must pass; the suite drives the controller over MCP stdio against
the live server). If it fails, pin back: scripts/upgrade.sh --binary.
Timeouts
Three independent timeouts bound the pipeline: the controller run timeout
(DEFAULT_RUN_TIMEOUT = 3600 s — a single opencode_run/opencode_answer/
opencode_permission call gives up after an hour), the MCP server
timeout in ~/.hermes/config.yaml (mcp_servers.opencode.timeout = 14400 s,
connect_timeout = 30 s), and the Hermes tools timeouts
(timeouts.tools.sequential_call / concurrent_batch = 14400 s) — the outer
two are set 4x above the controller's so a long-but-healthy turn is never
killed by the supervisor layer.
Development
See CONTRIBUTING.md for the dev setup, how to run the smoke test and the integration suite, and the contribution conventions.
Files
File | Role |
| FastMCP stdio server (the 6 tools) |
| state machine: submit / wait / resume / classify |
| HTTP + SSE client for the OpenCode server |
| data helpers for turns / interactions |
| durable delegation journal (append-only JSONL) |
| no-LLM smoke test (tool surface + basic calls) |
| full integration suite (live LLM turns) |
| journal unit tests (pytest) |
| setup wizard (Python + rich; self-bootstrapping venv) |
| the OpenCode version pin (single source of truth, one line) |
| lifecycle ( |
| TUI attach helpers (installed to |
License
MIT — Copyright (c) 2026 Arthur Hottier.
Available Tools
6 toolsopencode_abortA
Abort the active OpenCode session (or a specific one). Does not require the run lock, so it can stop a stuck run.
Inputs: session_id. Returns: object
opencode_answerA
Answer a pending OpenCode question (state=needs_agent_input, kind=question) and keep blocking until the turn completes, errors, or needs input again.
answers: ONE entry per sub-question, in order. Each entry is a string or a list of strings. When a sub-question offers options and does not allow custom answers, each value MUST be an exact option label (the server rejects anything else — this tool validates before posting).The answer is posted to OpenCode and the SAME turn resumes (the prompt is never resubmitted).
If the question is no longer pending (already answered/consumed), an error is returned; the turn may have moved on.
Inputs: answers (required), directory (required), session_id (required), question_id (required), +1 more. Returns: object
opencode_inspectA
DIAGNOSTIC ONLY: one-shot snapshot of a session (status, tree, pending permissions/questions, last assistant text). NEVER use this to poll or monitor a running task — opencode_run / opencode_answer / opencode_permission block until the turn ends; polling wastes tokens and is forbidden. Use only for exceptional diagnostics (after a timeout, or to inspect a session you did not start).
Inputs: session_id. Returns: object
opencode_permissionA
Decide a pending OpenCode permission (state=needs_agent_input, kind=permission) and keep blocking until the turn completes, errors, or needs input again.
reply: exactly one of 'once' (allow this call), 'always' (allow this pattern for the session), 'reject'. Decide as supervisor: allow normal actions necessary for the delegated task; reject destructive or out-of-scope requests.The decision is posted to OpenCode and the SAME turn resumes (the prompt is never resubmitted).
If the permission is no longer pending, an error is returned.
Inputs: reply (required), directory (required), session_id (required), permission_id (required), +1 more. Returns: object
opencode_runA
Delegate a coding task to OpenCode and block until it completes, errors, or needs input (a question or a permission).
New task: pass
directory+task+agent(a new session is created).agentis REQUIRED for a new session.Continuation / resume: pass
session_id(+taskfor a NEW turn on that session, ortaskis ignored when the turn is still in flight).agentis not needed to resume an in-flight turn (it is taken from the turn's durable state); pass it only when starting a fresh turn on an existing session.agent: the OpenCode agent to run as root. Free string, validated dynamically against the project's live agent list (GET /agent). It MUST be a primary agent of that directory (project-specific primary agents are preferred when they fit the task;buildis the generic implementation agent;planis read-only). Subagents are rejected as root. Do not rely on the server's default_agent: always choose explicitly for a new session.model: optional 'provider/model' override.
RESUME: if session_id is given and that session still has a turn in
flight (busy/retry) — e.g. the controller restarted mid-turn — the prompt
is NOT resubmitted: the wait loop simply resumes on the SAME turn
(task and agent are ignored in that case).
The call blocks until the turn ends. While OpenCode works, NOTHING is polled — the controller watches SSE + REST internally. If OpenCode asks a question or requests a permission, the call returns state='needs_agent_input' (kind='question' or 'permission') with everything needed to decide; answer with opencode_answer / opencode_permission, which resume the SAME turn. Returns the final assistant text + diff on completion.
Inputs: task (required), directory (required), agent, model, +2 more. Returns: object
opencode_sessionsB
List OpenCode sessions for a directory (to pick a session_id to reuse).
Inputs: directory (required). Returns: object
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 6 tools
Each tool targets a distinct phase of the OpenCode lifecycle: running/resuming tasks, answering questions, deciding permissions, aborting, inspecting, and listing sessions. The two input-resolution tools are clearly separated by kind (question vs permission). No meaningful overlap exists.
All tools share the opencode_ prefix, which helps, but the second element mixes verbs (run, answer, abort, inspect) with nouns (permission, sessions). There is no consistent verb_noun pattern, though the names remain readable and predictable enough within the server.
Six tools cover the delegated-agent interaction loop without redundancy. Each tool earns its place, and the set is neither bloated nor too thin for the server's purpose.
The core lifecycle is well covered: start/resume tasks, respond to questions, grant or reject permissions, abort, inspect, and list sessions. The main gap is that agents cannot discover the available agent list through a tool, though generic agents like build/plan provide a usable fallback.
Maintenance
Related MCP Connectors
A paid remote MCP for OpenAI Codex agent coordination MCP, built to return verdicts, receipts, usage
Persistent memory and cross-session learning for AI coding assistants (hosted remote MCP).
Sync coding-agent sessions and resume them in any other agent: Claude Code, Codex, Cursor, more.
Adaptive plan/build/review cycles for AI coding assistants, persisted across sessions.
Related MCP Servers
- AlicenseNot gradedqualityBmaintenanceEnables external AI supervisors to oversee and steer native Codex through MCP, including thread and turn management, observation, interruption, approval responses, runtime status, and checkpointing.MIT
- AlicenseNot gradedqualityAmaintenanceEnables MCP clients such as Claude, Cursor, and VS Code to delegate coding tasks to an OpenCode server, including asking questions, running background jobs, monitoring progress, responding to input/permissions, and reviewing changes across projects.22,181 npmMIT
- AlicenseNot gradedqualityAmaintenanceConnects MCP clients such as Claude, Cursor, and VS Code to an OpenCode server's headless API so coding work can be delegated, answered, and monitored. It supports asking questions, launching foreground or background jobs, supplying required input and permissions, and reviewing resulting changes across projects.22,181 npmMIT
- AlicenseNot gradedqualityAmaintenanceEnables MCP clients to delegate coding work to a running OpenCode server, including asking questions, implementing features, monitoring background jobs, responding to permissions and questions, and reviewing changes across projects.22,181 npmMIT