{
  "markdown": "<p align=\"center\">\n  <img src=\"https://raw.githubusercontent.com/TheBlueHouse75/hermes-action-bridge/main/assets/logo.png\" alt=\"Hermes Action Bridge\" width=\"128\" height=\"128\" />\n</p>\n\n# Hermes Action Bridge\n\n[![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)\n\nA 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.\n\nUse it from Claude Code, Codex, Cursor, CI jobs, shell scripts, or another\nMCP-capable client. MCP execution requires interactive form elicitation and\nfails closed in non-interactive clients; plan, draft, dry-run, and direct CLI\nworkflows remain available to automation.\n\n```text\nexternal agent -> hermes-action -> Hermes Agent -> skills/tools/integrations\n```\n\n## Why this exists\n\nCoding agents are good at understanding a repository. They should not duplicate your automation stack.\n\nIf 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.\n\n## Features\n\n- Generic `hermes-action run` command for one-shot delegation.\n- Configurable presets for skills, toolsets, provider/model, source, and max turns.\n- Deterministic, language-agnostic safety policy: downgrades `execute` to `request-approval` by default, with per-preset trust overrides.\n- Explicit `--yolo` mode for users who intentionally want to bypass bridge-level policy.\n- Context file injection with a per-file cap and a configurable aggregate budget (clear error instead of a cryptic `E2BIG`).\n- Automatic large-context delivery: an oversized prompt is handed to Hermes through a secure temp file instead of overflowing the command line.\n- Per-run timeouts (configurable, with per-mode defaults) that always reap the Hermes child process.\n- Dry-run mode for debugging the exact Hermes command, prompt, and computed prompt size.\n- Complete Codex and Claude Code installer: managed skill plus verified global MCP registration.\n- MCP capability discovery, cancellable asynchronous jobs, and one-shot two-phase approvals gated on interactive form elicitation, with a privacy-preserving local audit log.\n- Local stdio transport plus an opt-in, authenticated Streamable HTTP transport for Tailscale-restricted hosts.\n- No project-specific assumptions. All behavior is configured through YAML and CLI flags.\n\n## Requirements\n\n- Node.js 20 or newer.\n- Hermes Agent installed and available as `hermes`, or configured with a custom command path.\n\nCheck Hermes:\n\n```bash\nhermes --version\n```\n\n## Installation\n\nInstall from npm:\n\n```bash\nnpm install -g hermes-action-bridge\n```\n\nInstall the skill and MCP registration for Codex and Claude Code, then verify\nthe complete setup:\n\n```bash\nhermes-action --version\nhermes-action install all\nhermes-action doctor\n```\n\nGlobal installation is all-or-nothing for the requested agents. If Codex or\nClaude Code is unavailable, conflicting, or cannot verify its user-scoped\nstdio MCP entry, the command exits non-zero without installing the requested\nskills. Use `--project` for an explicit skill-only setup.\n\n### Other distribution channels\n\nChoose the channel that matches the agent surface. Hermes Agent must always be\ninstalled and configured on the same computer as the local bridge.\n\n| Channel | What it configures | Install |\n| --- | --- | --- |\n| npm installer | Skill and verified user-scoped MCP for Codex CLI/app and Claude Code | `hermes-action install all` |\n| 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` |\n| 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 |\n| Agent Skills | Portable instructions for supported coding agents | `npx skills add TheBlueHouse75/hermes-action-bridge --skill hermes-action-bridge` |\n| 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 |\n| 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 |\n\nThe standalone Agent Skill only teaches an agent when and how to delegate; it\ndoes not register an MCP server. Use the npm installer, Claude marketplace, or\nMCPB channel when MCP tools are required.\n\nMaintainers releasing a new version should follow the\n[distribution runbook](docs/distribution-runbook.md), which covers the\nautomated release workflow and the manual directory publication checks.\n\nCodex CLI and the Codex surface in the ChatGPT desktop app share the local\nCodex MCP configuration on the same host. A general ChatGPT connector is a\ndifferent distribution target: it requires a remotely reachable MCP server\nand is not installed by this local stdio bundle.\n\n<details>\n<summary>From source (for development)</summary>\n\n```bash\ngit clone https://github.com/TheBlueHouse75/hermes-action-bridge.git\ncd hermes-action-bridge\nnpm install\nnpm run build\nnpm link\n```\n\n</details>\n\n## Quick start\n\nCreate a config file in your project:\n\n```bash\nhermes-action init\n```\n\nAsk Hermes for a safe plan:\n\n```bash\nhermes-action run --mode plan \"Find the best next action from this repository context.\"\n```\n\nDelegate with a context file:\n\n```bash\nhermes-action run \\\n  --preset research \\\n  --context ./notes.md \\\n  \"Analyze this and return the next concrete action.\"\n```\n\nRun a dry-run to inspect what will be sent to Hermes:\n\n```bash\nhermes-action run --dry-run --json \"Summarize this project.\"\n```\n\n## Execution modes\n\n- `plan`: Hermes is instructed to return a plan only. Treat it as open-world because configured tools remain available.\n- `draft`: Hermes produces an artifact only. No external side effects.\n- `execute`: Hermes may execute allowed actions, while still following Hermes' own safety rules.\n- `request-approval`: Hermes prepares an action without executing it. MCP\n  callers should use `hermes_prepare` and then `hermes_approve`; the latter\n  opens an interactive client form showing the exact action and executes only\n  after the human confirms it.\n\nThe policy 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. Separately, every effective MCP `execute` request requires interactive client confirmation, including trusted presets and YOLO. The bridge does not try to infer risk from keywords.\n\nRisk 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.)\n\n- `publish_external`\n- `send_message`\n- `send_email`\n- `delete`\n- `payment`\n- `git_push`\n- `credential_change`\n\n## YOLO mode\n\nYOLO mode is off by default.\n\n```bash\nhermes-action run --yolo --mode execute \"Do the task now.\"\n```\n\nYOLO bypasses the mode-downgrade policy. It does not bypass the MCP interactive\nconfirmation barrier, Hermes Agent's own safety rules, provider/tool approval\nprompts, or platform constraints. Direct CLI use remains an explicit trusted-local\nescape hatch.\n\nUse it only when the caller and environment are trusted.\n\n## Trusted presets (direct execution)\n\nBy 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:\n\n```yaml\n# ~/.config/hermes-action/config.yaml   (user scope, merged before any project config)\npresets:\n  act:\n    description: Direct execution of an action I explicitly asked for (trusted).\n    require_approval_for: []\n```\n\nRun actions through it — `execute` stays `execute`, with no downgrade and no `--yolo` needed:\n\n```bash\nhermes-action run --preset act --mode execute \"post the release note to #general\"\n```\n\n**Keep it safe:**\n\n- A trusted preset relaxes the mode-downgrade policy. Effective MCP execution still requires interactive confirmation; direct CLI execution relies on the operator and environment being trusted.\n- Keep it in your **user** config; it never ships in the public package, and the distributed `SKILL.md` stays cautious for everyone else.\n- Reserve trusted presets for actions a human explicitly asks for. Leave the conservative default for anything an agent could trigger on its own.\n\n## Configuration\n\n`hermes-action` loads config in this order:\n\n```text\nCLI flags > project .hermes-action.yaml > user config > built-in defaults\n```\n\nUser config path:\n\n```text\n~/.config/hermes-action/config.yaml\n```\n\nProject config path:\n\n```text\n.hermes-action.yaml\n```\n\nExample:\n\n```yaml\nruntime:\n  adapter: hermes-cli\n  command: hermes\n  # Aggregate budget across all --context files, in bytes (default ~768 KiB).\n  # Raising this above ~896 KiB switches large prompts to temp-file delivery.\n  max_context_bytes: 786432\n  # Optional overall per-run timeout in seconds. When unset, per-mode defaults\n  # apply: 180s for plan/draft, 600s for execute/request-approval.\n  # timeout_seconds: 600\n\ndefaults:\n  mode: plan\n  source: external-agent\n  max_turns: 30\n  preset: default\n\npresets:\n  default:\n    description: No extra skills or toolsets. Uses the active Hermes profile.\n    skills: []\n    toolsets: []\n\n  research:\n    description: General research and synthesis.\n    skills: []\n    toolsets: [web, terminal, file]\n    # Per-preset override: relax approvals for a trusted preset.\n    # An empty list never downgrades execute to request-approval.\n    # require_approval_for: []\n\n  coding:\n    description: Repository inspection and runtime validation.\n    skills: [developer-assurance-and-validation, runtime-debugging]\n    toolsets: [terminal, file]\n\npolicy:\n  yolo: false\n  # Global default; a preset's own require_approval_for takes precedence when set.\n  require_approval_for:\n    - publish_external\n    - send_message\n    - send_email\n    - delete\n    - payment\n    - git_push\n    - credential_change\n```\n\n## Limits, timeouts, and large context\n\nThe bridge builds one prompt envelope (policy header + your request + every `<context>` block) and hands it to Hermes. Two guardrails keep that reliable:\n\n- **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.\n- **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).\n\nEvery 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.\n\n`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`.\n\n## CLI reference\n\n```bash\nhermes-action init [--file .hermes-action.yaml] [--force]\nhermes-action run [options] \"request\"\nhermes-action presets [--json]\nhermes-action status [--json]\nhermes-action mcp\nhermes-action serve [--listen 127.0.0.1] [--port 8765]\nhermes-action install <claude-code|codex|all|mcp> [options]\nhermes-action uninstall <claude-code|codex|all|mcp> [options]\nhermes-action doctor [--json] [--probe]\n```\n\nCommon `run` options:\n\n```bash\n--mode <plan|draft|execute|request-approval>\n--preset <name>\n--context <path...>\n--config <path>\n--provider <name>\n--model <name>\n--max-turns <number>\n--timeout <seconds>\n--source <name>\n--yolo\n--dry-run\n--json\n```\n\n## Native agent skills\n\nInstead of pasting instructions and MCP snippets by hand, run the complete\ninstaller. It installs the open-standard skill and registers the local stdio\nMCP server through each agent's own CLI:\n\n```bash\nhermes-action install all            # skills + global MCP for both agents\nhermes-action doctor                 # verifies skills, registrations, and MCP handshake\nhermes-action install claude-code --print     # preview, write nothing\nhermes-action install codex --project-hint     # also add a marker block to AGENTS.md\nhermes-action uninstall all\n```\n\nInstall behavior is safe by default: it uses a stable absolute bridge path,\ndoes not depend on an interactive `PATH`, never modifies `CLAUDE.md` /\n`AGENTS.md` unless you pass `--project-hint`, and refuses to overwrite either a\nforeign skill or a customized MCP entry. Re-running it is idempotent. Use\n`--project` for a project-local skill only and `--dry-run` to preview\noperations.\n\nThe generated skill is shown in [`examples/claude-code/SKILL.md`](examples/claude-code/SKILL.md). Project-hint usage is documented in [`examples/claude-code/CLAUDE.md`](examples/claude-code/CLAUDE.md) and [`examples/codex/AGENTS.md`](examples/codex/AGENTS.md).\n\n## Codex plugin (one-line install)\n\nCodex users can install the delegation skill and the MCP server together as a plugin:\n\n```bash\ncodex plugin marketplace add TheBlueHouse75/hermes-action-bridge\ncodex plugin add hermes-action@hermes-action-bridge\n```\n\nThis registers the `hermes-action` MCP server and the Hermes delegation skill\nin Codex. Hermes Agent must be installed locally — the plugin runs the\nversion-pinned npm package with `npx`.\n\n> **Faster MCP startup:** `npx` re-resolves the package on every server start.\n> The native installer registers the absolute global launcher instead.\n\n## MCP configuration\n\nRegister the global MCP server for Codex and Claude Code without reinstalling\ntheir skills:\n\n```bash\nhermes-action install mcp\n```\n\nFor other JSON MCP clients, or a Claude Code project-scoped configuration,\nwrite or merge `.mcp.json` directly while preserving other servers:\n\n```bash\nhermes-action install mcp --write\n```\n\nOr configure it by hand:\n\n```json\n{\n  \"mcpServers\": {\n    \"hermes-action\": {\n      \"command\": \"hermes-action\",\n      \"args\": [\"mcp\"]\n    }\n  }\n}\n```\n\n## Direct delegation\n\nYou can always call the bridge directly, without a skill:\n\n```bash\nhermes-action run --mode plan \"Ask Hermes what should happen next.\"\n\nhermes-action run \\\n  --preset coding \\\n  --context ./codex-notes.md \\\n  \"Use Hermes to validate this plan and identify missing runtime checks.\"\n```\n\n## MCP tools\n\nRun:\n\n```bash\nhermes-action mcp\n```\n\nExposed tools:\n\n- `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`. Any effective `execute` request opens an interactive confirmation form first.\n- `hermes_plan`: shortcut for `hermes_run` with `mode=plan`.\n- `hermes_capabilities`: report configured presets, skills, toolsets, runtime, and policy without inventing live integrations.\n- `hermes_presets`: list configured presets.\n- `hermes_status`: check the configured Hermes runtime command.\n- `hermes_submit`, `hermes_job_status`, `hermes_result`, `hermes_cancel`:\n  manage bounded, process-local asynchronous jobs.\n- `hermes_prepare`, `hermes_approve`, `hermes_reject`: create and consume a\n  short-lived one-shot approval. `hermes_approve` asks the MCP client for\n  interactive confirmation before execution.\n\nThe MCP surface delegates to Hermes instead of mirroring every Hermes tool.\nJobs and approvals are intentionally process-local: restarting the MCP server\nclears them. Audit events are written as owner-only JSONL metadata under\n`$XDG_STATE_HOME/hermes-action/audit.jsonl` (or\n`~/.local/state/hermes-action/audit.jsonl`) without prompt, context, token, or\nfull result content.\n\n## Remote MCP over Tailscale\n\nThe HTTP transport is opt-in and loopback-only by default:\n\n```bash\nhermes-action serve --listen 127.0.0.1 --port 8765\n```\n\nPrefer placing Tailscale Serve in front of that loopback endpoint. Forwarded\n`*.ts.net` requests still require a bearer token, so start the loopback server\nwith `--token-env`:\n\n```bash\nexport HERMES_ACTION_HTTP_TOKEN=\"<at-least-32-random-bytes>\"\nhermes-action serve \\\n  --listen 127.0.0.1 \\\n  --port 8765 \\\n  --token-env HERMES_ACTION_HTTP_TOKEN\n```\n\nFor direct tailnet listening, the bridge accepts only an explicit Tailscale\nIPv4 address and requires the same bearer-token setup:\n\n```bash\nhermes-action serve \\\n  --listen 100.64.0.10 \\\n  --port 8765 \\\n  --allow-tailnet \\\n  --token-env HERMES_ACTION_HTTP_TOKEN\n```\n\nThe token is never accepted as a CLI value or stored in bridge configuration.\nPublic/wildcard and non-Tailscale addresses are refused.\n\n## Development\n\n```bash\nnpm install\nnpm run build\nnpm run test\nnpm run check\n```\n\nFunctional tests use a fake Hermes binary to verify command construction, prompt wrapping, risk policy, and YOLO behavior without spending LLM credits.\n\n## Documentation\n\n- [Architecture](docs/ARCHITECTURE.md): module map, config precedence, modes, policy, and MCP design.\n- [Functional testing](docs/FUNCTIONAL-TESTS.md): automated tests and live smoke-test procedures.\n- [Contributing](CONTRIBUTING.md): local setup, development rules, and release checklist.\n- [Changelog](CHANGELOG.md): release history.\n- [Security policy](SECURITY.md): how to report a vulnerability.\n\n## Security model\n\nDirect CLI execution assumes a trusted, supervised operator. MCP execution has\nan additional protocol-enforced gate: every effective `execute` request asks\nthe client for MCP form elicitation, shows the exact action and metadata, and\nruns only when the response is both `accept` and `confirm=true`.\n\nFor side effects, prefer the testable two-phase flow: `hermes_prepare` returns\na local no-tool summary and opaque approval ID, and `hermes_approve` opens the\ninteractive confirmation before consuming the unchanged request exactly once.\nUnsupported clients, CI jobs, shell scripts, cancellations, timeouts, and\ndeclines fail closed without execution. Use plan, draft, dry-run, or the direct\nCLI when an interactive MCP client is unavailable; do not describe the direct\nCLI as providing a distinct human-approval barrier.\n\nThis gate assumes a conforming, trusted MCP client. The\n[MCP specification](https://modelcontextprotocol.io/specification/2025-11-25/client/elicitation#user-interaction-model)\nrequires clients that advertise elicitation to provide UI, identify the\nrequesting server, offer decline/cancel, and let the user review the response.\nA malicious client, or an elicitation hook configured to auto-answer, can forge\n`accept` and `confirm=true`; do not expose the bridge to untrusted MCP clients.\nThe bridge does not claim a human boundary in that deployment model.\n\nThe 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.\n\n- **Do not auto-answer MCP elicitation or install an elicitation hook that\n  accepts execution forms.** Doing so deliberately removes the human boundary.\n- **Do not allowlist `hermes-action run` (`execute`/`yolo`)**. A command-pattern\n  allowlist cannot distinguish a safe plan from an execution with side effects.\n- Do not put secrets in `.hermes-action.yaml`. Keep provider credentials in Hermes Agent, your OS keychain, or the platform's secure store.\n- Treat `--yolo` as a trusted-local escape hatch, not a default.\n\n## Also by the author\n\nBuilt by Cyril Guilleminot, who also makes offline-first voice tools:\n\n- [Weesper Neon Flow](https://weesperneonflow.ai) — speak text into any app at 3× typing speed, fully offline (macOS & Windows).\n- [Weesper Transcribe](https://apps.apple.com/app/id6778776535) — offline transcription on the macOS App Store.\n\n## License\n\nMIT\n",
  "bytes": 21652,
  "sha": "f7b5a9c25543f6f488e6c6df4e649bb2f7f02b81bbd52f1bbc63f13744fce459",
  "repo_slug": "thebluehouse75/hermes-action-bridge",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_thebluehouse75_hermes_action_b_23488f7f/readme"
}