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 :4096

• Layer 1 — Hermes: the supervisor LLM. It delegates a coding task with opencode_run and decides when the controller reports needs_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 serve process (systemd user service opencode-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.

Prerequisites

• Hermes installed (~/.hermes/config.yaml present)
• python3 >= 3.11 (with PyYAML for the Hermes config patch)
• Network access (OpenCode binary install, mcp package, LLM endpoint)
• systemd user sessions (for the opencode-server service)

Installation (2 commands)

git clone <repo-url> opencode-hermes-mcp && cd opencode-hermes-mcp
scripts/install.sh

scripts/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
openai-compatible	any OpenAI-compatible endpoint (Unsloth, Ollama, vLLM, llama-server, ...) — default	@ai-sdk/openai-compatible
openai	official OpenAI API	@ai-sdk/openai
anthropic	official Anthropic API	@ai-sdk/anthropic

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 --yes

OpenAI (cloud):

OPENCODE_PROVIDER=openai OPENCODE_API_KEY=sk-... OPENCODE_LLM_MODEL=gpt-4o \
scripts/install.sh --yes

Anthropic (cloud):

OPENCODE_PROVIDER=anthropic OPENCODE_API_KEY=sk-ant-... \
OPENCODE_LLM_MODEL=claude-sonnet-4-5 scripts/install.sh --yes

Flags: --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. agent is 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) or opencode_permission (once / always / reject) — both resume the same turn.
• opencode_abort stops a stuck run; opencode_sessions lists sessions for a directory; opencode_inspect is 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: 14400

The 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.jsonl by default, overridable with the OPENCODE_HERMES_MCP_JOURNAL env var.
• ts is epoch milliseconds; state is the run's terminal state; changed_files is 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 NOW

• ocattach opens 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-current reads 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 binary

uninstall.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.30

The controller is validated against OpenCode 1.18.30 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
opencode_hermes_mcp/server.py	FastMCP stdio server (the 6 tools)
opencode_hermes_mcp/controller.py	state machine: submit / wait / resume / classify
opencode_hermes_mcp/client.py	HTTP + SSE client for the OpenCode server
opencode_hermes_mcp/models.py	data helpers for turns / interactions
opencode_hermes_mcp/journal.py	durable delegation journal (append-only JSONL)
opencode_hermes_mcp/smoke_client.py	no-LLM smoke test (tool surface + basic calls)
tests/run_tests.py	full integration suite (live LLM turns)
tests/test_journal.py	journal unit tests (pytest)
opencode_hermes_mcp/installer.py	setup wizard (Python + rich; self-bootstrapping venv)
opencode_hermes_mcp/pin.txt	the OpenCode version pin (single source of truth, one line)
scripts/install.sh / uninstall.sh / upgrade.sh	lifecycle (install.sh is a thin wrapper around the wizard)
scripts/helpers/ocattach / oc-current	TUI attach helpers (installed to ~/.local/bin/)

License

MIT — Copyright (c) 2026 Arthur Hottier.