opencode-hermes-mcp

Детерминированный MCP-контроллер между Hermes (супервизорный LLM) и постояным OpenCode-сервером. Контроллер — это конечный автомат, а не LLM, который блокируется на ходах OpenCode и передаёт вопросы/запросы разрешений Hermes, чтобы супервизорный LLM мог сгеч принять решение и возобновить тот же ход.

Architecture

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

• Слой 1 — Hermes: супервизорный LLM. Он делегирует задачу по кодированию через opencode_run и решает, когда контроллер сообщает needs_agent_input (вопрос / запрос разрешения).

• Слой 2 — этот контроллер (opencode_hermes_mcp/: server.py + controller.py + client.py + models.py): процесс без LLM, порождаемый Hermes через MCP stdio. Он отправляет задачу, следит за SSE и REST, блокируется до завершения / ошибки / необходимости ввода и отправляет решения супервизоra обратно в тот же ход OpenCode (промпт никогда не педт отк повторно).

• Слой 3 — серве OpenCode: постоянный процесс opencode serve (пользовательский сервis systemd opencode-server, loopback :4096, базовая HTTP-аутентификация). Его LLM — это любо́й подjetжива́емый провайдер (OpenAI-совместимый endpoint, OpenAi, ибо Anthropic), занные в ~/.config/opencode/opencode.json.

Инструменты, доступные Hermes: opencode_run, opencode_answer, opencodeпермission, opencode_abort(only диагностические) andSteps...Actuallyopencode_inspect(диагносстический only),opencode_sessions`.

Related MCP server: cursor-agent-bridge

Prerequisties

• Установлен Hermes (~/.hermes/config.yaml присутствует)

• python3 >= 3,11 (плюсь PyYAML)

• Сетевой доступ (бинарь OpenCode, пакет mcp, LLM endpoint)

• systemd-пользовательские сессии (дляр серверного сервisа opencode-server)

install set (2 оманды)

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

scripts/install.sh — тонкая обёртка над мастером устанвки (opencode_hermes_mcp/installer.py, Python + rich): баннер, нумеровванные шаги, сти идемпonlyонтент, прогресс и summary–панель. Мастер зобутстрапливает сам себяrequests — если venv репозитория отсутствует (или inganim даat не rich / pyyaml / mcp==1.12.4 / пакет in editable режиwe), он соnему safeets itself и завершается, так что голый python3 >= 3.11 — единственный prerequisite.

Устанвка идемпотентна — при повторном запущске тот, что уже установлено, спускается. Она устанвливает закреплённый бинарник OpenCode, venv (пакет opencode_hermes_mcp с закреплённым mcp==1.12.4), конфигурацию провайдера LLM и секрет, учётные данные сервера, дve launchers, пользовательский сервис systemd и модифицирует ~/.hermes/config.yaml (резервная копия сохраняется как .bak). Завершающая проверка — health чек (по curl --max-time 3, показывается последняя ошибка) + python -м opencode_hermes_mcp.smoke_cclient (должен выдат: tool сурфace OK).

LLM-провайдеры

Установщик не привяван к провайдеру. Поддерживаются провайдера:

Интерактивно: выберите провайдера из меню, затем ответьте на запросы — базовый URL + API-ключ + модель для openai-compatible, API-ключ + модель для openai / anthropic — затем скорость LLM (slow для локальной LLM, который добавляет timeout:false / headerTimeout:false / chunkTimeout:120000 в опции провайдера; fast — по у мольанию) и лимиты модли (ctx / output, по у мольанию 128000 / 32000).

Неинтерактив (--yes) — всё берётся из env. Локальный OpenAI-совместимый 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 (облако):

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

Anthropic (облако):

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

Флаги: --yes (неinterавтивный, and use envOPENCODE_PROVIDER / OPENCODED_LLM_BASE_URL / OPENCODE_API_KEY / OPENCODE_LLM_MODEL / OPENCODE_LLM_SPEED / OPEN_CODE_CONTEXT_LIMIT / OPEN_CODE_OUTPUT_LIMIt), --port N (default 4096), --skip-bin, --force-config, --дry-run, --skip-verify (пропустить финальную health + smoke-пров ), — потребно, для sandbox/CI.

UNSLOTH_API_KEY still принихуется as deprecated fallback for OPENCODE_API_KEY (existing scripts keep working).

После установки требуется новая сессия Hermes, когор ая азатся, чтобы tigerзагрузить MCP–сервер.

Интеграция Hermes (вручную)

Инсталлятор сам патчит ~/.hermes/config.yaml, но сознательно не устанвливает навык Hermes (схже набора Hermеs may change). Пакет содержит полной просто:

• docs/hermes-integration.md — язказожность MCP, точная запись конфигурации, вручн ная инт ration, six tools, troubleshooting, uninstall.

• docs/skill.example.md — a rough copy of the skill for easy adaptation в ~/.hermes/skills/.

Use

Hermes делегируется работачерез MCP tools — no hand CLI needed:

• opcompare_run(directory, task, agent) — tasks? Actually "Отправляет задачу". Need preserve no.

"Отправляет задачу; blockificate until the ходом стрелок" etc.

The six tools list in sources.

Need maybe "Each call" etc.

Let's rewrite final coherently.

Let's craft entire final from scratch in Russian, checking all majors.

Final:

Final translation:

Need mention "Хелпер TUI". Ensure code list.

Let's compose carefully:

opencode-hermes-mp

badges

"Детерминированный MCP-контроллер между ..."

I need include badges exactly.

Gaprob:

At left image links. Since Markdown images long. We'll keep them as original (HTML? Actually standard Markdown. The instruction says keep images, badges, links including raw HTML. We preserve them exactly).

So copy lines:

[](#version-pin-opencode-1.16? Actually original "pinned" maybe o.

Let's copy exact from user input.

Then text.

Let's start final answer now. Ensure no code fences or preamble# opencode-hermes-mcp

Детерминированный MCP-контроллер между Hermes (супервизорный LLM) и постоянным OpenCode-сервером. Контроллер — это конечный автомат, а не LLM, — который блокируется на ходах OpenCode и выносит вопросы и запросы разрешений на уровень Hermes, чтобы супервизорный LLM мог решить и возобновить тот же ход.

Архитектура

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

• Слой 1 — Hermes: супервизорный LLM. Он делегирует задачу по кодированию с помощью opencode_run и решает, когда контроллер сообщает needs_agent_input (вопрос / запрос разрешения).

• Слой 2 — этот контроллер (opencode_hermes_mcp/: server.py + controller.py + client.py + models.py): процесс без LLM, запускаемый Hermes через MCP stdio. Он отправляет задачу, следит за SSE и REST, блокируется до завершения / ошибки / необходимости ввода и «о сво. решения супервvisor сже в резус смерт? I'm sorry I мloading, but ensure "sends supervisor's decisions back into the same OpenCode turn ( prompt never re-submitted)." Let's correct:

Он отправляeт задачу, следит за SSE и REST, блокируется, пока ход not завершение / not. error / not. need inout, а затем не.—? Rewrite "posts the supervisor's decisions back into the same OpenCode turn (the prompt is never resubmitted)." => "а затем отправляет решения супервизора backн через в тот же ход OpenCode (промпт ни когда не отпра gets").

Wrong. Let's formulate "а затем передаёт решения супервизора обратно в тот же ход OpenCode (промпт никогда не отправляется повторно)."

Layer 3 as above.

Предварительные требования

• Установленный Hermes (присутствует ~/.hermes/config.yaml)

• python3 >= 3.11 (с PyYAML для заплатки конфигурации Hermes)

• Сетевой доступ (установка бинарника OpenCode, пакет mcp, endpoint LLM)

• Пользовательские сессии systemd (для сервиса opencode-server)

Установка (2 команды)

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

scripts/install.sh — тонкая обёртка над мастером установки (opencode_hermes_mcp/installer.py, Python + rich): баннер, нумерованные шаги, стилизованные подсказки, прогресс и итоговая панель. Мастер бутстрапит сам себя — если venv репозитория отсутствует (или в нём нет rich / pyyaml / mcp==1.12.4 / редактируемого пакета), он создаёт его и перезапускается, так что единственное требование — голый python3 >= 3.11.

Установкаидемпотентн— повторный запуск перескакивает то, что уже сделано. Он устанавливает закреплённый бинарник OpenCode, venv (пакет opencode_hermes_mcp с закреплённым mcp==1.12.4), конфигурацию провайдера LLM и секрет, учётные данные сервера, два лаунч colon "the installer, the server" etc. Need translate.

Let's craf tснова:

"Устанавливает закреплённый бинарник OpenCode, venv (пакет opencode_hermes_mcp, зафиксированный на mcp==1.12.4), конфигурацию LLM-провайдера вместе с секретом, учётные данные сервера, два лаунчера, пользовательский сервис systemd, и патчит ~/.hermes/config.yaml (резервная копия остаётся как .bak). Завершается проверкой работоспособности (ограниченный по времени curl --max-time 3, выводится последняя ошибка) + выполнение python -m opencode_hermes_mcp.smoke_client (он должен напечатать tool surface OK)."

LLM-провайдеры

Installer не привязан к вограмме. Поддерживаются три провайдера:

Таблица as above.

«Интерактивный и неинтерактивный режи»

"Интерактивный режим: выберите провайдера из меню, затем ответе на выдачамется — базовый URL + API-ключ + модель для openai-compatible, API-ключ + модель для openai / anthropic — а затем скорость LLM (slow для локальной LLM, что добавляет timeout:false / headerTimeout:false / chunkTimeout:120000 в опции провайдера; fast — по умолчанию) и лимиты модели (контекст / вывод, по умолчанию 128000 / 32000)."

"Неинтерактивный (--yes), всё из env. Локальный OpenAI-совместимый 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 (облако):" G4

"Anthropic (облако):" G5

Flags: etc.

Интеграция с Hermes (вручную)

The installer патчит ~/. hermmes/config.yamlза вас, но сознательно не устанавливает skill Hermes (расположение skills может измениться). Пакет содержит сами материалы: bы link.

Использование

Hermes делегируетработы через MCP- tool, no not hand CLI:

Tools as above.

at "Когда инструмент возвращает state=needs_agent_input, Hermes решает: opencode_answer (pick точн ые labels) или opencode_permission (once / always / reject) — оба возобновляют тот же ход."

"opencode_abort" stops stuck run; sessions...

"Обвязка стороне Hermes ('scripts/install.shinto~/. hermes/config.yaml`):"

Then G6.

"The launcher director" ...

"Лаунчер читает учётные данные OpenCode-сервера из ~/.config/hermes/opencode-server.json и выполняет python -m opencode_hermes_mcp.server в venv репозитория — config.yaml остаётся без секретов."

Помощники подключения к TUI (наблюдение за OpenCode вживую)

"install.sh также кладёт два хелпера в ~/.local/bin/ (исходники: 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 открывает TUI OpenCode (opencode attach) для постоянного сервера :4096 — tmux не нужен. Без идентификатора сессии он открывает последнюю сессию или даёт выбрать.

• oc-current читает самый свежий ~/.local/state/opencode-hermes-mcp/turn_*.json (текущее состояние хода контроллера) и подключается к этой сессии — используйте его, пока Hermes управляет OpenCode, чтобы смотреть на рассуждения вживую.

Both читает учё кред from the same. Не нажимайте Esc/Ctrl+C в TUI при активном хо — это прервёт текущему ход through OpenCode.

Обновление / удаление

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 не трогает клонированный репо, конфигурацию провайдера OpenCode, секрет API-люча or the bin (если толькоп флаги очистки не говят сеть).

Пинверсии: OpenCode 1.18.21

Контроллер валидıрован только по против OpenCode 1.18.21 ( его контракт endpoint провверен по против hit this buarry's at /doc, а не веб-докцentation). Пин is единственный сточник истин in opencode_hermes_mcp/pin.txt (одна строка, без v-prefix): installer.py and scripts/upgrade.sh read it, орымfall back к встроenнный константе при отсутствующем файле (например, при pip устанавливаются, где file не кладядтся рядом с кодом). install.sh фиксирует бинарь на эту версиять; upgrade.sh не обновляется бинарь by default за.

scripts/upgrade.sh --binary (without string) ставит закреплённую верси и идемпотент (no-op if binary already zipped). --billnary latest is explicit opt-in to the "последем край"; --bullet X.Y.Z ставит по arrowную верси. Для anything отлиный по вину, script warns you and you MUST рre-valid пже перед:

.venv/bin/python tests/run_tests.py

(all checks must pass; suite drowns the controller over MCP stdio против living server). If not, go back to pin: upge.sh --binaries.

Таймауты

Три не за виси мыуты ограничивають тракт: controller run timeout (DEFAULT_RUN_TIMEOUT = 3600 с — одиныйguous single opencode_run /opencode_anwer/opencode_permission call gives up hour), MCP сserver timeout in ~/. hermes/config.yaml (mcp_servers.opencode.timeout = 14400 с, connect_timeout = 30 с), and **Hermes toolss timeouts (timeouts.tools.st /конcurrent_type= 144 µс?) Actuallytim.` We'll preserve.

"три неза висимых таймаута ог раничивают просто: таймаут контроллера (DEFAULT_RUN_TIMEOUT = 3600 с — вызов ... сдается within an hour), MCP-сервер таймout in ... , and Hermes tools timeouts (timeouts.tools.sequential_call / concurrent_batch = 14400 с) — the two outer modes are in 4x vs controller so a long but healthy turn never gets killed by superру level".

"## Development" and "## Files" Table as above.

"## License" - "## Лицензия" probably.

Need now produce final message. We must not include any utter wrap. Ensure no markdown fence.

Let's assemble final exactly. Need carefully correct all typos. We'll provide Russian translation. Let's write final.# кр. "ты государству"?

Now I'll write. Keep every tag, tokens.

Need not include ````. Final answer should be raw markdown.

Let's proceed.# opencode-hermes-mcp

Детерминированный MCP-контроллер между Hermes (супервизорный LLM) и постоянным OpenCode-сервером. Контроллер — это конечный автомат, а не LLM, — on sharp on OpenCode turns the name? Let's produce:

"он блокирует на ходах OpenCode и вывод;/ит" Good.

Here is final.# opencode-hermes-mcp

Дерминированный MCP-контроллер между Hermes (супервизорный LLM) и постоянным OpenCode-сервером. Контроллер — конечный автомат, а не LLM, — блокируется на ходах OpenCode и выводит вопросы и запросы разрешений на уровень Hermes, чтобы супервизорный LLM мог принять решение и возобновить тот же ход.

Architecture

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

• Слой 1 — Hermes: супервизорный LLM. Он делегирует задачу по кодированию с помощью opencode_run и решает, когда контроллер сообщает needs_agent_input (вопрос / запрос разрешения).

• Слой 2 — этот контроллер (opencode_hermes_mcp/: server.py + controller.py + client.py + models.py): процесс без LLM, запускаемый Hermes через MCP stdio. Он отправляет задачу, следит за SSE и REST, блокируется до завершения / ошибки / необходимости ввода и передаёт решения супервизора обратно в тот же ход OpenCode (промпт никогда не отправляется повторно).

• Слой 3 — сервер OpenCode: постоянный процесс opencode serve (пользовательский сервис systemd opencode-server, loopback :4096, базовая HTTP-аутентификация). Его LLM — любой поддерживаемый провайдер (OpenAI-совместимый endpoint, OpenAI или Anthropic), настроенный в ~/.config/opencode/opencode.json.

Инструменты, доступные Hermes: opencode_run, opencode_answer, opencode_permission, opencode_abort, opencode_inspect (только для диагностики), opencode_sessions.

Предварительные требования

• Установлен Hermes (присутствует ~/.hermes/config.yaml)

• python3 >= 3.11 (с PyYAML для изменения конфигурации Hermes)

• Сетевой доступ (установка бинарника OpenCode, пакет mcp, endpoint LLM)

• Пользовательские сессии systemd (для сервиса opencode-server)

Установка (2 команды)

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

scripts/install.sh — тонкая обёртка над мастером установки (opencode_hermes_mcp/installer.py, Python + rich): баннер, нумерованные шаги, стилизованные подсказки, прогресс и итоговая панель. Мастер бутcтрапит сам себя — если venv репозитория отсутствует (или в нём нет rich / pyyaml / mcp==1.12.4 / редактируемого пакета), он создаёт его и перезапускается, так что голый python3 >= 3.11 — единственное требование.

Установка идемпотентна: при повторном запуске уже готовое пропускается. Она устанавливает закреплённый бинарник OpenCode, venv (пакет opencode_hermes_mcp с закреплённым mcp==1.12.4), конфигурацию LLM-провайдера и секрет, учётные данные сервера, два лаунчера, пользовательский сервис systemd и прописывает изменения в ~/.hermes/config.yaml (резервная копия сохраняется как .bak). Завершается она проверкой работоспособности (ограниченный curl --max-time 3, показывается последняя ошибка) + python -m opencode_hermes_mcp.smoke_client (должен напечатать tool surface OK).

LLM-провайдеры

Установщик не привязан к конкретному провайдеру. Поддерживаются три провайдера:

Интерактивно: выберите провайдера из меню, затем ответьте на подсказки — base URL + API-ключ + модель для openai-compatible; API-ключ + модель для openai / anthropic — затем скорость LLM (slow для локальной LLM, что добавляет timeout:false / headerTimeout:false / chunkTimeout:120000 к опциям провайдера; fast — вариант по умолчанию) и лимиты модели (контекст, причём по умолчанию 128000 / 32000).

Неинтерактивный режим (--yes) — всё берётся из env. Локальный OpenAI-совместимый 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 (облако):

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

Anthropic (облако):

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

Флаги: --yes (неинтерактивный режим, использует env OPENCODE_PROVIDER / OPENCODE_LLM_BASE_URL / OPENCODE_API_KEY / OPENCODE_LLM_MODEL / OPENCODE_LLM_SPEED / OPENCODE_CONTEXT_LIMIT / OPENCODE_OUTPUT_LIMIT), --port N (по умолчанию 4096), --skip-binary, --force-config, --dry-run, --skip-verify (пропустить финальную health- и smoke‑проверку — удобно для sandbox/CI).

UNSLOTH_API_KEY по‑прежнему принимается как устаревший вариант для OPENCODE_API_KEY (существующие скрипты продолжат работать).

После установки нужно заново запустить Hermes, чтобы загрузить MCP—сервер.

Интеграция Hermes (вручную)

Установщик сам прописывает изменения в ~/.hermes/config.yaml, но он намеренно не устанавливает стиль Hermes (схема навыков Hermes может измениться). Пакет содержит полное руководство вместо этого:

• docs/hermes-integration.md — назначение MCP, точная запись конфигурации, ручная интеграция, шесть инструментов, диагностика, удаление.

• docs/skill.example.md — готовый к переписыванию скилл Hermes (протокол делепirования), который можно положить в ~/.hermes/skills/ и адаптировать.

Использование

Hermes делегирует работутеработа через MCP—инструменты — ручной CLIไม่ треб为一个:

• opencode_run(directory, task, agent) — отправляет задачу; блокируется до завершения, ошибки или необходимости ввода. agent обязателен для новой сессии (основной агент проекта, например build, plan или агент, специфичный для проекта).

• Когда инструмент возвращает state=needs_agent_input, Hermes решает: opencode_answer(выбрать точные метки ответов) или opencode_permission (once / always / reject) — оба возобновляют тот же ход.

  • opencode_abort останавливает зависший запуск; opencode_sessions перечисляет сессии для каталога; opencode_inspect — только для экстренной диагностики (не опрашивайте работающую задачу).

Обвязка на стороне Hermes (записывается scripts/install.sh в ~/.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

Лаунчер читает учётные данные сервера OpenCode из ~/.config/hermes/opencode-server.json и выполняет python -m opencode_hermes_mcp.server в venv репозитория — сам config.yaml не хранит секретов.

Хелперы для подключения TUI (смотреть OpenCode вживую)

install.sh также кладёт два хелпера в ~/.local/bin/ (исходники: 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 от见到了? Need "открывает" — write: "открывает TUI OpenCode (opencode attach) adпостоянного15899. " Выпол хорош.

Let's finalize.

Let's produce final nowДетерминированный MCP-контроллер между Hermes (супервизорный LLM) и постоянным OpenCode-сервером. Контроллер — конечный автомат, а не LLM, — блокируется на ходах OpenCode и выносит вопросы и запросы разрешений на уровень Hermes, чтобы супервизорный LLM мог решить и возобновить тот же ход.

Архитектура

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

• Слой 1 — Hermes: супервизорный LLM. Он делегирует задачу по кодированию через opencode_run и решает, когда контроллер сообщает needs_agent_input (вопрос / запрос разрешения).

• Слой 2 — этот контроллер (opencode_hermes_mcp/: server.py + controller.py + client.py + models.py): процесс без LLM, запускаемый Hermes по MCP stdio. Он отправляет задачу, следит за SSE и REST, блокируется до завершения / ошибки / необходимости ввода и передаёт решения супервизора обратно в тот же ход OpenCode (промпт никогда не переотправляется).

• Слой 3 — сервер OpenCode: постоянный процесс opencode serve (пользовательский сервис systemd opencode-server, loopback :4096, базовый HTTP auth). Его LLM — любой поддерживаемый провайдер (OpenAI-совместимый endpoint, OpenAI или Anthropic), настроенный в ~/.config/opencode/opencode.json.

Инструменты, доступные Hermes: opencode_run, opencode_answer, opencode_permission, opencode_abort, opencode_inspect (только диагностика), opencode_sessions.

Предпосылки

• установлен Hermes (присутствует ~/.hermes/config.yaml)

• python3 >= 3.11 (с PyYAML для патча конфигурации Hermes)

• сетевой доступ (установка бинарного файла OpenCode, пакет mcp, LLM-endpoint)

• пользовательские сессии systemd (для сервиса opencode-server)

Установка (2 команды)

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

scripts/install.sh — тонкая обёртка над мастером установки (opencode_hermes_mcp/installer.py, Python + rich): баннер, нумерованные шаги, стилизованные подсказки, прогресс и итоговая панель. Мастер самонастраивается — если венв репозитория отсутствует (или не хватает rich / pyyaml / mcp==1.12.4 / редактируемого пакета), он создаёт его и перезапускается, так что единственный предпосылка — голый python3 >= 3.11.

Установка идемпотентна — повторный запуск пропускает уже готовое. Она устанавливает закреплённый бинарник OpenCode, виртуальное окружение (пакет opencode_hermes_mcp с закреплённым mcp==1.12.4), конфигурацию LLM-провайдера и секреты, учётные данные сервера, два лаунчера, системный пользовательский сервис и прописывает изменения в ~/.hermes/config.yaml (резервная копия остаётся как .bak). В конце выполняются проверка (ограниченный curl --max-time 3, при ошибке показывается последняя) + python -m opencode_hermes_mcp.smoke_client (должен вывести tool surface OK).

LLM-провайдеры

Установщик агностичен к провайдеру. Поддерживаются три провайдера:

Интерактивный режим: выбираем провайдера из меню, затем отвечаем на вопросы — базовый URL + API-ключ + модель для openai-compatible, API-ключ + модель для openai / anthropic — затем скорость LLM (slow для локальной LLM, что добавляет timeout:false / headerTimeout:false / chunkTimeout:120000 к опциям провайдера; fast — по умолчанию) и лимиты модели (контекст / вывод, по умолчанию 128000 / 32000).

Неинтерактивный режим (--yes) — всё из окружения. Локальный OpenAI-совместимый 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 (облако):

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

Anthropic (облако):

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

Флаги: --yes (неинтерактивный режим, использует env OPENCODE_PROVIDER / OPENCODE_LLM_BASE_URL / OPENCODE_API_KEY / OPENCODE_LLM_MODEL / OPENCODE_LLM_SPEED / OPENCODE_CONTEXT_LIMIT / OPENCODE_OUTPUT_LIMIT), --port N (по умолчанию 4096), --skip-binary, --force-config, --dry-run, --skip-verify (пропустить финальную проверку — удобно для песочниц и CI).

UNSLOTH_API_KEY по-прежнему принимается как старый fallback для OPENCODE_API_KEY (существующие скрипты работают без изменений).

После установки потребуется перезапуск Hermes, чтобы MCP-сервер подLoader.

Интеграция Hermes (вручную)

Установщик вносит изменения в ~/.hermes/config.yaml сам, но намеренно не ставит навык Hermes (структура навыков Hermes может измениться). Вместо этого пакет содержит подробное руководство:

• docs/hermes-integration.md — зачем нужен этот MCP, какая именно запись в config, ручная интеграция, шесть инструментов, устранение неполадок, удаление.

• docs/skill.example.md — готовый к реплицированию навык Hermes (протокол делегирования), который можно опустить в ~/.hermes/skills/ и изменить под себя.

Использование

Hermes делегирует работу через MCP-инструменты — ручной CLI не нужен:

• opencode_run(directory, task, agent) — отправляет задачу; блокируется, пока ход не завершился, не случилась ошибка или не потребуется ввод. agent обязателен для новой сессии (основной агент проекта, напр, build, plan или специфический агент проекта).

• Когда инструмент возвращает state=needs_agent_input, Hermes решает: opencode_answer (выбирает конкретные ярлыки опций) или opencode_permission (once / always / reject) — оба варианта возобновляют тот же ход.

• opencode_abort останавливает зависший запуск; opencode_sessions перечисляет сессии для каталога; opencode_inspect — только для исключительных диагностических нужд (не опрашивайте работающую задачу).

Подключение на стороне Hermes (записывается scripts/install.sh в ~/.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

Лаунчер читает учётные данные сервера OpenCode из ~/.config/hermes/opencode-server.json и выполняет python -m opencode_hermes_mcp.server в виртуальном окружении репозитория — при этом config.yaml не содержит секретов.

Служебные приставки для TUI (смотреть OpenCode вживую)

install.sh при этом кладёт два хелперора в ~/.local/bin/ (исходники: 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 открывает TUI OpenCode (opencode attach) для постоянного сервера :4096 — tmux не необходим. Без ID сессия открывает последнюю сессию либо просит выбрать.

• oc-current читает самый свежий ~/.local/state/opencode-hermes-mcp/turn_*.json (текущее состояние хода контроллера) и прицепляется к этой сессии — применяйте, идите, когда Hermes ведёт OpenCode, и вы хотите наблюдать за ходом мысли в прямом эфире.

Обе читают учётные данные сервера из ~/.config/hermes/opencode-server.json (тот же источник, что и контроллер). Не жмите Esc/Ctrl+C в TUI, пока активен ход — это прервёт выполняемый ход на стороне OpenCode.

Обновление / удаление

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 никогда не трогает git-клон, конфиг провайдера OpenCode, секрет API-ключа и бинарник (если только специальные purge-флаги not скажут обратного).

Закрепление версии: OpenCode 1.18.21

Контроллер валидирован только против OpenCode 1.18.21 (его контракт endpoint был проверен по живому /doc этого бинарника, а do docsия not) Let's refine.

Пуת: "Контроллер валидирован только на OpenCode 1.18.21 (контракт этой версии проверялся по его живому /doc, а не по веб-документации). Пин — единый источник правды в opencode_hermes_mcp/pin.txt (одна строка, без префикса v): installer.py and scripts/upgrade.sh read this file, if missing/empty uses built-in (for pip installs where file не рядом). install.sh применfixes binary to pin; upgrade.sh никогда не обновляет binary by default.

scripts/upgrade.sh --binary (без версии) устанавливает закреплённую и идемпотентно (ничего не делае, если уже налеёт). --binary latest — явный opt-in на самый передний край; --binary X.Y.Z ставит запрошенную верси. For любого другого than pin, скрипт предупредит, и вы ДОЛЖНЫ повторно проверить контроллер before using:

.venv/bin/python tests/run_tests.py

(все проверки должны пройти; набор гоняет контроллер через MCP stdio против живого сервера). Если не прошло, откатывай пин: scripts/upgrade.sh --binary.

Таймауаты

Three независимых timeouts ограничивают pipeline: контроллер run timeout (DEFAULT_RUN_TIMEOUT = 3600 с — одинoчный opencode_run/opencode_answer/opencode_permission вызов loses after hour), MCP server timeout в ~/.hermes/config.yaml (mcp_servers.opencode.timeout = 14400 s, connect_timeout = 30 s), и Hermes tools timeouts (timeouts.tools.sequential_call / concurrent_batch = 14400 s) — двое внешних установлены в 4 раза выше контроллерских, поэтому длинный, но здоровый ход никогда не срубается супервизорным слоем.

Development

See CONTRIBUTING.md: настройка env, how to run smoke test and integration suite, notes on contribution.

Файлы

Лицен

MIT — Copyright (c) 2026 Arthur Hottier.