opencode-hermes-mcp

[

Controlador MCP determinista entre Hermes (LLM superv}sor) y el servidor OpenCode permanente. El controlador es un a state machine — no LLM — que se bloquea en los turnos de OpenCode y expone las preguntas / permissos a Hermes para que el LLM supervisor pueda decidir y reanudar el missmo turno.

Arquitectura

Hermes (LLM)  --MCP stdio-->  opencode_hermes_mcp.server (FastMCP, 6 tools)  --HTTP + SSE-->  OpenCode server :4096

• Cape 1 — Hermes: el LLM superv}or. Delegate un coding task with opencode_run y decide cuand el controlador informa de needs_agent_inpt (question / permiss).

• Cape 2 — este controlador (opencode_hermmes_mcp/: server.py + controller.py + client.py + models.py): un process without LLM inciado por Hermes over MCP stdio. Envía la tera, observes up (TA + REST, se bloquea hasta que el turno completes, error, or requires imput, and is the supervisor's decisions back en el miss turno OpenCode (el prompt nunca es re-ved). hmm

• Cape 3 — Servidor OpenCode: a permanent opencode serve proceso (servicio user systemd opencode-server, loopback :4096, HTTP basic auth). His LLM can is "any provider supported (OpenAI-compatible endpoint, OpenII, or AnIHropic), unified in ~/.config/opencode/opencode.json.

Herramients exposed to Hermes: opencode_run, opencode_answer, opencode_permiss, opencode_abort, opencode_inspect (so diaging, of opencode_sessions.

Related MCP server: opencode-mcp

Requissites

• Hermes installed (~/.hermes/config.yaml present)

• pthon3 >= 3.11 (with PyYML for the conf. ige)

• R dissolved access to net (installing OpenCode binary, mcp package, LLM endpoint)

• sstemd user sesions (for the opencode-server service)

Instalación (2 comands)

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

scripts/instal.sh is a thin cover for the setup wizard (opencode_hermmes_mcp/installer.py, Python + rich): banner, numbereded steps, styled prompts, progress, and summary panel. The wizard self-``` bootstrap — if the repo venv is missing (or lacks rich / pyyaml / mcp==1.12 / the editable package), it is worth creating and re-container so a bare python3 >= 3.11 is all that is needed.

The installation is idempotent — re-run it skips what is already in its position. It installs the pinned OpenCode binary, the venv (the opencode_hermmes_mcp package with mcp==1.12,4 pinned), the LLM provider constellation + secret, the server cred, te dos launchers, the systemd user service, and p into ~/.hermmes/config.yaml (backup kept .bak). It terminates with a health comprobation (curl --max-time 3 acotado, the last error surfaced, the + python -m opencode_hermes_mcp.smoke_client (must print tool surfave OK).

LLM providers

The installer is provider-agnostic. Three providers are supported:

Interactivo: pick the provider from the menu, then answer the prompts — base URL + API key + modle for openai-compatible, API key + modle 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 default) and the model limits (context / output, defaults 8000 / 32000).

Non-interactive (--yes) 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-verif (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 add to ~/.hermes/skills/ and it is used.

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_permiss (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/instal.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 repository venv and leaves config.yaml without secrets.

TUI attach helpers (watch OpenCode live)

instal.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/opcode-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 current turn on the OpenCode server.

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 sayso).

Version Pin: OpenCode 1.18.21

The controller validated against OpenCode 1.18.21 only and its endpoint thugfull /doc not been verified against the web. The pin is a single source of truth in opencode_hermes_mcp/pin.txt (one line, nov 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.eg. pip installs where the file is not shipped next to the code). install.sh pins the binary to that version; upgrade.sh never gives(clock) converts the binary by default.

scripts/upgrade.sh --binary (no version) installs the pinned version and is idempotent (no-op if the binary already at the pin). --binary latest is the explicit opt-out to "bleeding edge"; --binary X.Y.Z installs requested version. For anything other than the given, the script warns and you MUST re-validate the controller before trusting it:

.venv/bin/python tests/run_tests.py

(No all checks must pass. The suite drives the controller over MCP stdio against the live server). If this is not the case, pin back: scripts/upgrade.sh --binary.

Timeouts

There are three independent timeouts: the controller run timeout (DEFAULT_RUN_TIMEOUT = 3600 s — a a single opencode_run / opencode_answer / opencode_permission call to be given entrance per hour), the MC server timeout ~/.hermes/config.yaml (mcp_servers.opencode.timeout = 14400 s, connect_timeout = 30 s), and the Hemes tools timeouts (tions.tools.sequential_call / concurrent_batch = 14400 s) — the outer two are 4x above the controller's so that a long-but-healthy Live run is never cut 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

License

MIT — Copyright (c) 2026 Raj Kottier.