Hermes Action Bridge

A configurable bridge that lets external agents delegate real-world actions to Hermes Agent without reimplementing Hermes skills, tools, platform integrations, browser automation, cron jobs, or messaging flows.

Use it from Claude Code, Codex, Cursor, CI jobs, shell scripts, or any MCP-capable client.

external agent -> hermes-action -> Hermes Agent -> skills/tools/integrations

Why this exists

Coding agents are good at understanding a repository. They should not duplicate your automation stack.

If an agent needs to do something outside its local coding session — research, schedule a job, open a browser workflow, send a message, prepare a social post, use a Hermes skill, or coordinate with a messaging gateway — it can delegate that request to Hermes through this bridge.

Features

Generic hermes-action run command for one-shot delegation.
Configurable presets for skills, toolsets, provider/model, source, and max turns.
Deterministic, language-agnostic safety policy: downgrades execute to request-approval by default, with per-preset trust overrides.
Explicit --yolo mode for users who intentionally want to bypass bridge-level policy.
Context file injection with a per-file cap and a configurable aggregate budget (clear error instead of a cryptic E2BIG).
Automatic large-context delivery: an oversized prompt is handed to Hermes through a secure temp file instead of overflowing the command line.
Per-run timeouts (configurable, with per-mode defaults) that always reap the Hermes child process.
Dry-run mode for debugging the exact Hermes command, prompt, and computed prompt size.
Minimal MCP server exposing delegation tools: hermes_run, hermes_plan, hermes_presets, and hermes_status.
No project-specific assumptions. All behavior is configured through YAML and CLI flags.

Requirements

Node.js 20 or newer.
Hermes Agent installed and available as hermes, or configured with a custom command path.

Check Hermes:

hermes --version

Installation

Install from npm:

npm install -g hermes-action-bridge

Then check it works:

hermes-action --version
hermes-action doctor

From source (for development)

git clone https://github.com/TheBlueHouse75/hermes-action-bridge.git
cd hermes-action-bridge
npm install
npm run build
npm link

Quick start

Create a config file in your project:

hermes-action init

Ask Hermes for a safe plan:

hermes-action run --mode plan "Find the best next action from this repository context."

Delegate with a context file:

hermes-action run \
  --preset research \
  --context ./notes.md \
  "Analyze this and return the next concrete action."

Run a dry-run to inspect what will be sent to Hermes:

hermes-action run --dry-run --json "Summarize this project."

Execution modes

plan: Hermes returns a plan only. No side effects.
draft: Hermes produces an artifact only. No external side effects.
execute: Hermes may execute allowed actions, while still following Hermes' own safety rules.
request-approval: Hermes prepares the action and asks the human for approval before irreversible external effects.

The guard is deterministic and language-agnostic: in execute mode the bridge switches to request-approval by default — regardless of the prompt's wording or language — unless the preset is explicitly trusted (empty require_approval_for) or --yolo is set. It does not try to infer risk from keywords. See Security model for why the real barrier is your coding agent's own approval prompt.

Risk categories below are informational only: the bridge surfaces the ones it recognizes in the prompt envelope to help you and Hermes decide, but they never drive the mode. (Keyword matching is English-biased and trivially evaded, so it must not be a security control.)

publish_external
send_message
send_email
delete
payment
git_push
credential_change

YOLO mode

YOLO mode is off by default.

hermes-action run --yolo --mode execute "Do the task now."

YOLO only bypasses the bridge policy. It does not remove Hermes Agent's own safety rules, provider/tool approval prompts, or platform constraints.

Use it only when the caller and environment are trusted.

Configuration

hermes-action loads config in this order:

CLI flags > project .hermes-action.yaml > user config > built-in defaults

User config path:

~/.config/hermes-action/config.yaml

Project config path:

.hermes-action.yaml

Example:

runtime:
  adapter: hermes-cli
  command: hermes
  # Aggregate budget across all --context files, in bytes (default ~768 KiB).
  # Raising this above ~896 KiB switches large prompts to temp-file delivery.
  max_context_bytes: 786432
  # Optional overall per-run timeout in seconds. When unset, per-mode defaults
  # apply: 180s for plan/draft, 600s for execute/request-approval.
  # timeout_seconds: 600

defaults:
  mode: plan
  source: external-agent
  max_turns: 30
  preset: default

presets:
  default:
    description: No extra skills or toolsets. Uses the active Hermes profile.
    skills: []
    toolsets: []

  research:
    description: General research and synthesis.
    skills: []
    toolsets: [web, terminal, file]
    # Per-preset override: relax approvals for a trusted preset.
    # An empty list never downgrades execute to request-approval.
    # require_approval_for: []

  coding:
    description: Repository inspection and runtime validation.
    skills: [developer-assurance-and-validation, runtime-debugging]
    toolsets: [terminal, file]

policy:
  yolo: false
  # Global default; a preset's own require_approval_for takes precedence when set.
  require_approval_for:
    - publish_external
    - send_message
    - send_email
    - delete
    - payment
    - git_push
    - credential_change

Limits, timeouts, and large context

The bridge builds one prompt envelope (policy header + your request + every <context> block) and hands it to Hermes. Two guardrails keep that reliable:

Aggregate context budget (runtime.max_context_bytes, default ~768 KiB, plus a fixed 250 KiB per-file cap). Exceeding it fails fast with an actionable message — Context total N bytes exceeds the limit ... Split your handoff or raise runtime.max_context_bytes. — instead of a cryptic E2BIG spawn crash. The default leaves headroom under the operating system's argument-size limit.
Large-context delivery. If you raise the budget and the envelope grows past ~896 KiB, the adapter writes it to a 0600 temp file and tells Hermes to read that file (injecting a file toolset for the call). This sidesteps the OS argument limit. Two caveats: it adds one tool-calling turn, and the real ceiling becomes the model's context window — a multi-megabyte file may only be partially read. The temp file is removed after the run; only an uncatchable kill of the bridge process itself could leave it behind (mitigated by the 0600 mode and the OS temp reaper).

Every run is bounded by a timeout (default 180s for plan/draft, 600s for execute/request-approval). Override per run with --timeout <seconds> or globally with runtime.timeout_seconds. On expiry the Hermes child is sent SIGTERM, then SIGKILL after a short grace, and the result is marked as timed out.

hermes-action doctor prints the effective limits, and hermes-action run --dry-run --json reports the computed prompt size (promptBytes, promptChars) and whether delivery would use argv or a temp-file.

CLI reference

hermes-action init [--file .hermes-action.yaml] [--force]
hermes-action run [options] "request"
hermes-action presets [--json]
hermes-action status [--json]
hermes-action mcp
hermes-action install <claude-code|codex|all|mcp> [options]
hermes-action uninstall <claude-code|codex|all|mcp> [options]
hermes-action doctor [--json] [--probe]

Common run options:

--mode <plan|draft|execute|request-approval>
--preset <name>
--context <path...>
--config <path>
--provider <name>
--model <name>
--max-turns <number>
--timeout <seconds>
--source <name>
--yolo
--dry-run
--json

Native agent skills

Instead of pasting instructions by hand, install a native skill so Claude Code and Codex know when to delegate to Hermes. The skill is the same open-standard SKILL.md for both agents; the CLI stays the deterministic execution layer.

hermes-action doctor                 # check Node, Hermes, agents, and installed skills
hermes-action install all            # ~/.claude/skills and ~/.codex/skills
hermes-action install claude-code --print     # preview, write nothing
hermes-action install codex --project-hint     # also add a marker block to AGENTS.md
hermes-action uninstall all

Install behavior is safe by default: it never modifies CLAUDE.md / AGENTS.md unless you pass --project-hint, refuses to overwrite a file it did not generate, and is idempotent. Use --project for a project-local skill and --dry-run to preview operations.

The generated skill is shown in examples/claude-code/SKILL.md. Project-hint usage is documented in examples/claude-code/CLAUDE.md and examples/codex/AGENTS.md.

Codex plugin (one-line install)

Codex users can install the delegation skill and the MCP server together as a plugin:

codex plugin marketplace add TheBlueHouse75/hermes-action-bridge
codex plugin add hermes-action@hermes-action-bridge

This registers the hermes-action MCP server and the Hermes delegation skill in Codex. Hermes Agent must be installed locally — the plugin runs npx -y hermes-action-bridge mcp.

Faster MCP startup: npx re-resolves the package on every server start (~200 ms overhead, more on a cold cache). If you install the package globally (npm install -g hermes-action-bridge), point the MCP config at the binary — command: "hermes-action", args: ["mcp"] — which is what hermes-action install mcp generates.

MCP configuration

Print the config snippet for your client (Claude Code / Cursor / VS Code use JSON; Codex uses TOML):

hermes-action install mcp

For Claude Code, write or merge the project .mcp.json directly (preserving other servers):

hermes-action install mcp --write

Or configure it by hand:

{
  "mcpServers": {
    "hermes-action": {
      "command": "hermes-action",
      "args": ["mcp"]
    }
  }
}

Direct delegation

You can always call the bridge directly, without a skill:

hermes-action run --mode plan "Ask Hermes what should happen next."

hermes-action run \
  --preset coding \
  --context ./codex-notes.md \
  "Use Hermes to validate this plan and identify missing runtime checks."

MCP tools

Run:

hermes-action mcp

Exposed tools:

hermes_run: delegate a request to Hermes. Optional overrides: mode, preset, contextFiles, yolo, dryRun, and — to trade cost for speed on simple tasks — model, provider, maxTurns, timeoutSeconds.
hermes_plan: shortcut for hermes_run with mode=plan.
hermes_presets: list configured presets.
hermes_status: check the configured Hermes runtime command.

The MCP surface is intentionally small. The bridge delegates to Hermes instead of exposing every Hermes tool one by one.

Development

npm install
npm run build
npm run test
npm run check

Functional tests use a fake Hermes binary to verify command construction, prompt wrapping, risk policy, and YOLO behavior without spending LLM credits.

Documentation

Architecture: module map, config precedence, modes, policy, and MCP design.
Functional testing: automated tests and live smoke-test procedures.
Contributing: local setup, development rules, and release checklist.
Changelog: release history.
Security policy: how to report a vulnerability.

Security model

The bridge assumes a supervised host agent: Claude Code / Codex ask you to approve each hermes-action command (or hermes_run tool call) before it runs. That host approval — not the keyword detection — is the real, deterministic, language-agnostic barrier, and it is what makes a French, German, or paraphrased request as safe as an English one.

The bridge's own guard is a secondary net: execute is downgraded to request-approval by default unless a preset is trusted (empty require_approval_for) or --yolo is set. The bridge never injects --yolo or a bypass flag on its own.

Do not allowlist / auto-approve hermes-action run (especially --mode execute or --yolo) in your coding agent. A command-pattern allowlist cannot tell run --mode plan (safe) from run --mode execute (side effects); at most, status, presets, and --dry-run are safe to auto-approve.
Do not put secrets in .hermes-action.yaml. Keep provider credentials in Hermes Agent, your OS keychain, or the platform's secure store.
Treat --yolo as a trusted-local escape hatch, not a default.

Also by the author

Built by Cyril Guilleminot, who also makes offline-first voice tools:

Weesper Neon Flow — speak text into any app at 3× typing speed, fully offline (macOS & Windows).
Weesper Transcribe — offline transcription on the macOS App Store.

License

MIT