Skip to content

connect-hermes.md

Latest commit

 

History

History
76 lines (57 loc) · 4.11 KB

connect-hermes.md

File metadata and controls

76 lines (57 loc) · 4.11 KB
Raw

Connect Hermes (alpha)

Guide (informative) · For: operators · Prereqs: Quickstart

Hermes (Nous Research) joins a Cotal mesh as a lateral peer, with the same shared cotal_* tool surface and delivery model as the other connectors. The hermes connector ships in the cotal-ai package, so no extra install of the connector itself.

Alpha means it runs today (spawn it, it joins the mesh and takes turns) but with real constraints, all verified below: it is Unix-only, needs an external Python toolchain you provide (uv + hermes-agent on a pinned version line), is not offered in the cotal setup picker, is not bundled in the container image (so no containerized Hermes, see Deploy), and does not support session resume.

Prerequisites

  • Unix (macOS or Linux). Windows is unsupported; the connector throws at launch (it uses an AF_UNIX socket bridge and a Python sidecar).
  • uv on your PATH. The launcher runs uv run --project <connector> hermes gateway run, so uv provisions the Python environment that provides the hermes CLI.
  • hermes-agent on the pinned 0.16 line. The launcher asserts the installed version at startup and fails loudly on a mismatch (no silent degrade), because a different major.minor can move the plugin/platform/hook API this connector targets.

Spawn it

cotal spawn --agent hermes            # foreground in this terminal
COTAL_DEFAULT_AGENT=hermes cotal spawn # make it the default harness (an explicit --agent wins)

Or set agent: hermes in a team manifest. Persona and role come from the agent file like any connector (see agent-files.md).

Hermes is not in the cotal setup picker (setup wires only Claude Code and OpenCode), so it is spawn-only: there is no setup step for it beyond having the toolchain above.

Choose a model

Hermes is model-agnostic; set any one provider's key in your environment. Model precedence matches the other connectors: the --model flag, else the agent file's model:, else an ambient HERMES_MODEL. Hermes exposes no cotal models catalog (unlike OpenCode).

How it binds

Unlike Claude Code or OpenCode (where the harness is the process), Hermes runs as a long-lived gateway daemon that spins up a fresh agent per inbound message. So the mesh connection can't live inside a per-turn process; the connector's command is a small launcher/supervisor that owns the mesh endpoint for the gateway's whole life and runs hermes gateway run as its child.

  • The launcher bridges to an in-gateway Python plugin (the platform adapter, presence hooks, and the cotal_* tools) over local AF_UNIX sockets.
  • It runs the gateway in an isolated HERMES_HOME profile (a temp dir), so your own ~/.hermes is never touched, with approvals off (a supervised agent has no human at the TUI to approve).
  • The persona is written as Hermes' SOUL.md (its system-prompt file), the one place a system prompt can be set.
  • Quiet-channel ambient is skipped by the automatic bridge pump, even when an older quiet item is ahead of a DM. cotal_inbox explicitly surfaces and clears quiet ambient without consuming the connector-owned automatic queue; quiet @mentions remain automatic.

The shared tool surface and inbound-message model are documented once, for all connectors: see mcp-tools.md and connect-claude.md.

Limits

  • Unix-only (no Windows).
  • No session resume: cotal spawn --resume throws.
  • Not containerized: the deploy image bundles only Claude Code and OpenCode (no uv/hermes-agent), so there is no containerized Hermes today.
  • Brings its own toolchain: you supply uv and a hermes-agent on the pinned line.

See also