hermes-action-bridge

<p align="center">
  <img src="https://raw.githubusercontent.com/TheBlueHouse75/hermes-action-bridge/main/assets/logo.png" alt="Hermes Action Bridge" width="128" height="128" />
</p>

# Hermes Action Bridge

[![npm](https://img.shields.io/npm/v/hermes-action-bridge)](https://www.npmjs.com/package/hermes-action-bridge) [![CI](https://github.com/TheBlueHouse75/hermes-action-bridge/actions/workflows/ci.yml/badge.svg)](https://github.com/TheBlueHouse75/hermes-action-bridge/actions/workflows/ci.yml)

A configurable bridge that lets external agents delegate real-world actions to [Hermes Agent](https://hermes-agent.nousresearch.com/docs) 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.

```text
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.
- Complete Codex and Claude Code installer: managed skill plus verified global MCP registration.
- MCP capability discovery, cancellable asynchronous jobs, and one-shot two-phase approvals with a privacy-preserving local audit log.
- Local stdio transport plus an opt-in, authenticated Streamable HTTP transport for Tailscale-restricted hosts.
- 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:

```bash
hermes --version
```

## Installation

Install from npm:

```bash
npm install -g hermes-action-bridge
```

Install the skill and MCP registration for Codex and Claude Code, then verify
the complete setup:

```bash
hermes-action --version
hermes-action install all
hermes-action doctor
```

Global installation is all-or-nothing for the requested agents. If Codex or
Claude Code is unavailable, conflicting, or cannot verify its user-scoped
stdio MCP entry, the command exits non-zero without installing the requested
skills. Use `--project` for an explicit skill-only setup.

### Other distribution channels

Choose the channel that matches the agent surface. Hermes Agent must always be
installed and configured on the same computer as the local bridge.

| Channel | What it configures | Install |
| --- | --- | --- |
| npm installer | Skill and verified user-scoped MCP for Codex CLI/app and Claude Code | `hermes-action install all` |
| Claude Code marketplace | Claude plugin with the Skill and a version-pinned MCP server | `claude plugin marketplace add TheBlueHouse75/hermes-action-bridge`, then `claude plugin install hermes-action@hermes-action-bridge` |
| Claude Desktop | Self-contained MCPB extension for the bridge runtime | From the [latest GitHub Release](https://github.com/TheBlueHouse75/hermes-action-bridge/releases/latest), download `hermes-action-bridge-<version>.mcpb` and open it with Claude Desktop |
| Agent Skills | Portable instructions for supported coding agents | `npx skills add TheBlueHouse75/hermes-action-bridge --skill hermes-action-bridge` |
| Smithery Skill | Public portable instructions in the Smithery Skill catalog | Check the [latest release notes](https://github.com/TheBlueHouse75/hermes-action-bridge/releases/latest) for the verified Skill listing or its pending status |
| Smithery MCPB | The same local MCPB bundle through the Smithery catalog | Check the [latest release notes](https://github.com/TheBlueHouse75/hermes-action-bridge/releases/latest) for the verified MCPB listing or its pending status |

The standalone Agent Skill only teaches an agent when and how to delegate; it
does not register an MCP server. Use the npm installer, Claude marketplace, or
MCPB channel when MCP tools are required.

Maintainers releasing a new version should follow the
[distribution runbook](docs/distribution-runbook.md), which covers the
automated release workflow and the manual directory publication checks.

Codex CLI and the Codex surface in the ChatGPT desktop app share the local
Codex MCP configuration on the same host. A general ChatGPT connector is a
different distribution target: it requires a remotely reachable MCP server
and is not installed by this local stdio bundle.

<details>
<summary>From source (for development)</summary>

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

</details>

## Quick start

Create a config file in your project:

```bash
hermes-action init
```

Ask Hermes for a safe plan:

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

Delegate with a context file:

```bash
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:

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

## Execution modes

- `plan`: Hermes is instructed to return a plan only. Treat it as open-world because configured tools remain available.
- `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 an action without executing it. MCP
  callers should use `hermes_prepare` and then call `hermes_approve` only after
  explicit human approval.

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](#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.

```bash
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.

## Trusted presets (direct execution)

By default every `execute` is downgraded to `request-approval` — the right default when an agent might act unattended. When *you* are the one asking for an action and want it to run without that extra gate, define a **trusted preset**: one whose `require_approval_for` is an empty list. Put it in your **user** config so it is yours alone and available in every project:

```yaml
# ~/.config/hermes-action/config.yaml   (user scope, merged before any project config)
presets:
  act:
    description: Direct execution of an action I explicitly asked for (trusted).
    require_approval_for: []
```

Run actions through it — `execute` stays `execute`, with no downgrade and no `--yolo` needed:

```bash
hermes-action run --preset act --mode execute "post the release note to #general"
```

**Keep it safe:**

- A trusted preset relaxes only the bridge's own gate. The real barrier stays your coding agent's approval prompt, so **do not allowlist `hermes-action run` (`execute`/`yolo`)** (see [Security model](#security-model)).
- Keep it in your **user** config; it never ships in the public package, and the distributed `SKILL.md` stays cautious for everyone else.
- Reserve trusted presets for actions a human explicitly asks for. Leave the conservative default for anything an agent could trigger on its own.

## Configuration

`hermes-action` loads config in this order:

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

User config path:

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

Project config path:

```text
.hermes-action.yaml
```

Example:

```yaml
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: