Skip to content

hermes.md

Latest commit

 

History

History
111 lines (78 loc) · 3.75 KB

hermes.md

File metadata and controls

111 lines (78 loc) · 3.75 KB
Raw

Ouroboros Runtime Guide: Hermes Agent

This guide covers how to use Ouroboros with the Hermes Agent as an execution runtime.

Installation

To use Hermes with Ouroboros, ensure you have the Hermes CLI installed (v0.8.0 or higher):

# Verify installation
hermes version

Setup

Install the MCP profile with a package-isolated launcher, then select the hermes runtime:

pipx install 'ouroboros-ai[mcp]'         # or: uv tool install 'ouroboros-ai[mcp]'
ouroboros setup --runtime hermes

Setup requires uvx or pipx and registers the MCP 2 server through that isolated process. It never falls back to a direct ouroboros binary or python -m, because those environments may contain the Claude SDK's MCP 1.x dependency or no MCP extra. If neither launcher is available, setup exits non-zero before changing persistent Ouroboros runtime configuration.

This will:

  1. Configure ~/.ouroboros/config.yaml to use the hermes backend.
  2. Install Ouroboros skills into ~/.hermes/skills/autonomous-ai-agents/ouroboros/.
  3. Register the Ouroboros MCP server in ~/.hermes/config.yaml.

With uvx, the generated host entry is:

mcp_servers:
  ouroboros:
    command: uvx
    args: [--isolated, --python, ">=3.12", --from, "ouroboros-ai[mcp]", ouroboros, mcp, serve]
    enabled: true

When only pipx is available, setup writes:

mcp_servers:
  ouroboros:
    command: pipx
    args: [run, --spec, "ouroboros-ai[mcp]", ouroboros, mcp, serve]
    enabled: true

Usage

Once configured, Ouroboros will use Hermes as the orchestrator runtime backend. This does not rewrite llm.backend; interview, ambiguity scoring, and other LLM-only flows continue to use the configured LLM adapter.

Executing Workflows

ouroboros run seed.yaml --runtime hermes

Scripting with Hermes

You can use the ooo command prefix inside a Hermes session to trigger Ouroboros skills:

hermes chat -q "ooo interview 'Build a new CLI tool'"
hermes chat -q "ooo run seed.yaml"

Hermes uses the shared stateless ouroboros.router resolver for exact ooo and /ouroboros: skill dispatch. Adding or changing a command only requires updating the relevant SKILL.md frontmatter; the runtime keeps logging, message assembly, and MCP invocation local. See Shared ooo Skill Dispatch Router.

Configuration

You can customize the Hermes CLI path in ~/.ouroboros/config.yaml:

orchestrator:
  runtime_backend: hermes
  hermes_cli_path: ~/.local/bin/hermes

Technical Details

Session Management

Ouroboros tracks Hermes sessions using the session_id emitted by the Hermes CLI in quiet mode (-Q). This allows Ouroboros to resume conversations using the --resume flag.

Permission mode

Seed execution forces bypassPermissions on both fresh and resumed Hermes turns. The runtime translates that contract to Hermes' native --yolo --accept-hooks flags so dangerous-command approvals and previously unseen shell-hook approvals cannot block a headless run.

Output Parsing

Ouroboros parses the Hermes CLI output to extract the final response and session metadata. It automatically strips reasoning blocks and banners when running in programmatic mode.

Active Conductor and Synapse

The installed Hermes probe emitted a session marker but could not resume that session from its store. Ouroboros therefore advertises no Synapse delivery for Hermes: inform, after_turn, checkpoint redirect, and hard replace fail closed instead of pretending that a CLI flag proves continuity. Ordinary Hermes execution and observer progress still work, and the main host explains the unsupported delivery honestly in the user's conversation language.