Hermes Action Bridge

Hermes Action Bridge

外部エージェントが、Hermes のスキル、ツール、プラットフォーム連携、ブラウザー自動化、cron ジョブ、メッセージングのワークフローを再実装することなく、実際の操作をHermes Agentに委任できる、設定可能なブリッジです。

Claude Code、Codex、Cursor、CI ジョブ、シェルスクリプト、またはその他の MCP 対応クライアントから利用できます。MCP の実行には対話型のフォームによる情報取得が必要で、 非対話型クライアントでは安全のため失敗します。plan、draft、dry-run、直接 CLI によるワークフローは引き続き自動化で利用できます。

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

このブリッジが必要な理由

コーディングエージェントはリポジトリを理解するのが得意です。自動化スタックを重複して実装するべきではありません。

エージェントがローカルのコーディングセッション外で何かを行う必要がある場合（調査、ジョブのスケジュール、ブラウザーのワークフローの開始、メッセージの送信、ソーシャル投稿の準備、Hermes スキルの使用、メッセージングゲートウェイとの連携など）、このブリッジを通じてそのリクエストを Hermes に委任できます。

機能

• 1 回限りの委任を行う汎用コマンド hermes-action run。
• スキル、ツールセット、プロバイダー／モデル、ソース、最大ターン数を設定できるプリセット。
• 決定論的で言語に依存しない安全ポリシー。デフォルトでは execute を request-approval にダウングレードし、プリセットごとに信頼設定を上書きできます。
• ブリッジレベルのポリシーを意図的に無効にする場合に使用する、明示的な --yolo モード。
• ファイルごとの上限と設定可能な合計予算を備えたコンテキストファイルの注入（不明瞭な E2BIG ではなく、明確なエラーを表示）。
• 大きなコンテキストの自動配信。プロンプトが大きすぎる場合は、コマンドラインの上限を超えないよう、安全な一時ファイルを介して Hermes に渡します。
• 実行ごとのタイムアウト（設定可能で、モードごとのデフォルト値あり）。Hermes の子プロセスは必ず終了させます。
• デバッグ用のドライランモード。正確な Hermes コマンド、プロンプト、算出されたプロンプトサイズを確認できます。
• Codex と Claude Code の完全なインストーラー。管理対象のスキルと検証済みのグローバル MCP 登録を含みます。
• MCP の機能検出、キャンセル可能な非同期ジョブ、対話型フォームによる情報取得を必須とする 1 回限りの 2 段階承認に加え、プライバシーを保護するローカル監査ログ。
• ローカルの stdio トランスポートと、Tailscale でアクセスを制限したホスト向けの、オプトインかつ認証付きの Streamable HTTP トランスポート。
• プロジェクト固有の前提はありません。すべての動作は YAML と CLI フラグで設定します。

要件

• Node.js 20 以降。
• hermes として利用可能な Hermes Agent、またはカスタムコマンドパスによる設定。

Hermes を確認します：

hermes --version

インストール

npm からインストールします：

npm install -g hermes-action-bridge

Codex と Claude Code 用のスキルと MCP 登録をインストールし、セットアップ全体を 検証します：

hermes-action --version
hermes-action install all
hermes-action doctor

グローバルインストールでは、指定されたエージェントすべてに対する処理が一括で行われます。Codex または Claude Code が利用できない、競合がある、あるいはユーザー単位の stdio MCP エントリーを検証できない場合、コマンドは 0 以外の終了コードで終了し、要求された スキルはインストールされません。スキルのみを明示的にセットアップするには、--project を使用してください。

その他の配布チャネル

エージェントの利用環境に合ったチャネルを選択してください。Hermes Agent は、必ずローカルブリッジと同じコンピューターにインストールして設定する必要があります。

単体の Agent Skill は、エージェントに委任するタイミングと方法を教えるだけであり、MCP サーバーは登録しません。MCP ツールが必要な場合は、npm インストーラー、Claude マーケットプレイス、または MCPB チャネルを使用してください。

新しいバージョンをリリースするメンテナーは、自動リリースワークフローと手動でのディレクトリ公開チェックを網羅した配布手順書に従ってください。

Codex CLI と ChatGPT デスクトップアプリ内の Codex 環境は、同じホスト上のローカル Codex MCP 設定を共有します。一般的な ChatGPT コネクターは別の配布先です。リモートからアクセス可能な MCP サーバーが必要であり、このローカル stdio バンドルではインストールされません。

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

クイックスタート

プロジェクトに設定ファイルを作成します。

hermes-action init

安全な計画を Hermes に依頼します。

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

コンテキストファイルを使って委任します。

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

ドライランを実行して、Hermes に送信される内容を確認します。

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

実行モード

• plan：Hermes に計画のみを返すよう指示します。設定済みのツールは引き続き利用可能なため、オープンワールドとして扱ってください。
• draft：Hermes は成果物のみを作成します。外部への副作用はありません。
• execute：Hermes は許可されたアクションを実行できますが、Hermes 独自の安全規則には引き続き従います。
• request-approval：Hermes はアクションを実行せずに準備します。MCP 呼び出し元はhermes_prepareを使用し、その後hermes_approveを使用してください。後者は 正確なアクションを表示する対話型クライアントフォームを開き、人間が確認した 後にのみ実行します。

ポリシーガードは決定論的で、言語に依存しません。executeモードでは、プリセットが明示的に信頼されている（require_approval_forが空）場合、または--yoloが設定されている場合を除き、ブリッジはデフォルトでrequest-approvalに切り替わります。これはプロンプトの文言や言語にかかわらず適用されます。これとは別に、信頼済みプリセットや YOLO を含め、有効な MCP executeリクエストはすべて、対話型クライアントでの確認が必要です。ブリッジはキーワードからリスクを推測しません。

以下のリスクカテゴリは情報提供のみを目的としています。ブリッジは認識したものをプロンプトエンベロープに表示し、あなたと Hermes の判断を支援しますが、モードの決定には使用しません。（キーワード照合は英語に偏っており、簡単に回避できるため、セキュリティ対策として使用してはいけません。）

• publish_external
• send_message
• send_email
• delete
• payment
• git_push
• credential_change

YOLO モード

YOLO モードはデフォルトでオフです。

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

YOLO はモード降格ポリシーをバイパスします。MCP の対話型確認の障壁、Hermes Agent 独自の安全ルール、プロバイダー／ツールの承認プロンプト、またはプラットフォームの制約をバイパスするものではありません。直接 CLI を使用する方法は、引き続き明示的に信頼されたローカル環境向けの回避手段です。

呼び出し元と環境が信頼できる場合にのみ使用してください。

信頼済みプリセット（直接実行）

デフォルトでは、エージェントが無人で動作する可能性がある場合に適切な設定として、すべての execute が request-approval に降格されます。アクションを依頼するのが あなた自身 で、追加の承認手順なしで実行したい場合は、require_approval_for が空のリストである 信頼済みプリセット を定義します。ユーザー 設定に記述すれば、あなた専用となり、すべてのプロジェクトで利用できます。

# ~/.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: []

このプリセットを使ってアクションを実行します。execute は降格されず、--yolo も不要です。

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

安全に使うために：

• 信頼済みプリセットはモード降格ポリシーを緩和します。実効的な MCP 実行には引き続き対話型確認が必要です。直接 CLI で実行する場合は、オペレーターと環境が信頼できることを前提とします。
• ユーザー 設定に記述してください。公開パッケージに含まれることはなく、配布される SKILL.md は他のユーザー向けに慎重な設定のままです。
• 信頼済みプリセットは、人間が明示的に依頼するアクションに限定してください。エージェントが独自に実行できるアクションには、保守的なデフォルト設定を使用してください。

設定

hermes-action は、次の順序で設定を読み込みます。

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

ユーザー設定のパス：

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

プロジェクト設定のパス：

.hermes-action.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:
    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

制限、タイムアウト、大きなコンテキスト

ブリッジは、1 つのプロンプトエンベロープ（ポリシーヘッダー + リクエスト + すべての <context> ブロック）を構築し、Hermes に渡します。信頼性を保つため、次の 2 つのガードレールが設けられています。

• コンテキストの合計予算（runtime.max_context_bytes、デフォルトは約 768 KiB、さらにファイルごとに固定の上限 250 KiB）。これを超えると、不可解な E2BIG によるプロセス起動エラーではなく、実行可能な対処法を示すメッセージ（Context total N bytes exceeds the limit ... Split your handoff or raise runtime.max_context_bytes.）が表示され、すぐに失敗します。デフォルト設定では、オペレーティングシステムの引数サイズ制限に対する余裕が確保されます。
• 大きなコンテキストの受け渡し。 予算を引き上げ、エンベロープが約 896 KiB を超えると、アダプターはそれを 0600 の一時ファイルに書き込み、そのファイルを読み込むよう Hermes に指示します（この呼び出しに file ツールセットが挿入されます）。これにより、OS の引数サイズ制限を回避できます。注意点が 2 つあります。ツール呼び出しのターンが 1 回追加されること、そして実際の上限がモデルのコンテキストウィンドウになることです。数メガバイトのファイルは一部しか読み込まれない場合があります。一時ファイルは実行後に削除されます。ブリッジプロセス自体を捕捉不能な方法で強制終了した場合に限り、ファイルが残る可能性があります（0600 モードと OS の一時ファイル削除機能によってリスクが軽減されます）。

すべての実行にはタイムアウトが設定されています（デフォルトは plan／draft で 180 秒、execute／request-approval で 600 秒）。実行ごとに --timeout <seconds> で、全体設定として runtime.timeout_seconds で変更できます。タイムアウトになると、Hermes の子プロセスに SIGTERM が送信され、短い猶予期間の後に SIGKILL が送信されます。結果にはタイムアウトとして記録されます。

hermes-action doctor は有効な制限を表示します。また、hermes-action run --dry-run --json は、計算されたプロンプトサイズ（promptBytes、promptChars）と、受け渡しに argv または temp-file のどちらが使われるかを報告します。

CLI リファレンス

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 serve [--listen 127.0.0.1] [--port 8765]
hermes-action install <claude-code|codex|all|mcp> [options]
hermes-action uninstall <claude-code|codex|all|mcp> [options]
hermes-action doctor [--json] [--probe]

run の主なオプション：

--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

ネイティブエージェントスキル

手動で指示や MCP のスニペットを貼り付ける代わりに、完全版のインストーラーを実行してください。オープンスタンダードのスキルをインストールし、各エージェント独自の CLI を通じてローカルの stdio MCP サーバーを登録します。

hermes-action install all            # skills + global MCP for both agents
hermes-action doctor                 # verifies skills, registrations, and MCP handshake
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

インストールはデフォルトで安全に動作します。安定した絶対パスのブリッジを使用し、対話型の PATH に依存せず、--project-hint を指定しない限り CLAUDE.md ／ AGENTS.md を変更せず、外部のスキルやカスタマイズされた MCP エントリを上書きしません。再実行しても冪等です。プロジェクトローカルのスキルのみをインストールするには --project を、操作をプレビューするには --dry-run を使用してください。

生成されるスキルは examples/claude-code/SKILL.md にあります。プロジェクトヒントの使用方法は examples/claude-code/CLAUDE.md と examples/codex/AGENTS.md に記載されています。

Codex プラグイン（ワンラインインストール）

Codex ユーザーは、委任スキルと MCP サーバーをプラグインとしてまとめてインストールできます。

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

これにより、hermes-action MCP サーバーと Hermes 委任スキルが Codex に登録されます。Hermes Agent をローカルにインストールしておく必要があります。プラグインは、バージョンが固定された npm パッケージを npx で実行します。

MCP の起動を高速化： npx はサーバーを起動するたびにパッケージを再解決します。 ネイティブインストーラーは、代わりに絶対パスのグローバルランチャーを登録します。

MCP の設定

スキルを再インストールせずに、Codex と Claude Code 用のグローバル MCP サーバーを登録します。

hermes-action install mcp

その他の JSON MCP クライアント、または Claude Code のプロジェクトスコープの設定では、ほかのサーバーを保持したまま .mcp.json を直接書き込むか、既存の内容にマージします。

hermes-action install mcp --write

または、手動で設定します。

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

直接委任

スキルを使わずに、いつでもブリッジを直接呼び出せます。

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 ツール

次を実行します。

hermes-action mcp

公開されるツール：

• hermes_run：リクエストを Hermes に委任します。任意の上書き項目は mode、preset、contextFiles、yolo、dryRun、および簡単なタスクのコストを速度に振り替えるための model、provider、maxTurns、timeoutSeconds です。有効な execute リクエストでは、最初に対話型の確認フォームが表示されます。
• hermes_plan：mode=plan を指定した hermes_run のショートカットです。
• hermes_capabilities：実際には存在しない連携を捏造せずに、設定済みのプリセット、スキル、ツールセット、ランタイム、ポリシーを報告します。
• hermes_presets：設定済みのプリセットを一覧表示します。
• hermes_status：設定済みの Hermes ランタイムコマンドを確認します。
• hermes_submit、hermes_job_status、hermes_result、hermes_cancel： プロセス内に限定された非同期ジョブを管理します。
• hermes_prepare、hermes_approve、hermes_reject：有効期間の短い、1 回限りの承認を作成して使用します。hermes_approve は、実行前に MCP クライアントへ対話型の確認を求めます。

MCP のインターフェースは、すべての Hermes ツールを再現するのではなく、Hermes に処理を委任します。 ジョブと承認は意図的にプロセス内に限定されています。MCP サーバーを再起動すると消去されます。監査イベントは、プロンプト、コンテキスト、トークン、または結果全体の内容を含めず、所有者のみがアクセスできる JSONL メタデータとして $XDG_STATE_HOME/hermes-action/audit.jsonl（または ~/.local/state/hermes-action/audit.jsonl）に書き込まれます。

Tailscale 経由のリモート MCP

HTTP トランスポートはオプトイン方式で、デフォルトではループバックのみで待ち受けます。

hermes-action serve --listen 127.0.0.1 --port 8765

このループバックエンドポイントの前段には、Tailscale Serve を配置することをおすすめします。転送された *.ts.net リクエストにもベアラートークンが必要です。そのため、ループバックサーバーは --token-env を付けて起動してください。

export HERMES_ACTION_HTTP_TOKEN="<at-least-32-random-bytes>"
hermes-action serve \
  --listen 127.0.0.1 \
  --port 8765 \
  --token-env HERMES_ACTION_HTTP_TOKEN

テールネットを直接リッスンする場合、ブリッジが受け付けるのは明示的に指定された Tailscale IPv4 アドレスのみです。また、同じベアラートークンの設定が必要です。

hermes-action serve \
  --listen 100.64.0.10 \
  --port 8765 \
  --allow-tailnet \
  --token-env HERMES_ACTION_HTTP_TOKEN

トークンを CLI の値として受け付けたり、ブリッジの設定に保存したりすることはありません。パブリックアドレス、ワイルドカードアドレス、Tailscale 以外のアドレスは拒否されます。

開発

npm install
npm run build
npm run test
npm run check

機能テストでは偽の Hermes バイナリを使って、LLM クレジットを消費せずにコマンドの構築、プロンプトのラッピング、リスクポリシー、YOLO の動作を検証します。

ドキュメント

• アーキテクチャ：モジュールマップ、設定の優先順位、モード、ポリシー、MCP の設計。
• 機能テスト：自動テストと、実環境でのスモークテスト手順。
• コントリビューション：ローカル環境のセットアップ、開発ルール、リリースチェックリスト。
• 変更履歴：リリース履歴。
• セキュリティポリシー：脆弱性の報告方法。

セキュリティモデル

CLI を直接実行する場合、オペレーターが信頼でき、監督下にあることを前提とします。MCP 経由での実行には、プロトコルによって強制されるゲートが追加されます。すべての有効な execute リクエストでクライアントに MCP 形式の入力要求を行い、アクションとメタデータを正確に表示したうえで、応答が accept かつ confirm=true の場合にのみ実行します。

副作用を伴う処理には、テスト可能な二段階のフローを推奨します。hermes_prepare は、ツールを使わずにローカルで要約を返し、不透明な承認 ID を発行します。続いて hermes_approve が対話形式の確認を開き、変更されていないリクエストを一度だけ消費します。未対応のクライアント、CI ジョブ、シェルスクリプト、キャンセル、タイムアウト、拒否の場合は、実行せず安全側に倒します。対話型 MCP クライアントを利用できない場合は、plan、draft、dry-run、または CLI の直接実行を使用してください。CLI の直接実行に、独立した人間による承認の境界があるとは説明しないでください。

このゲートは、仕様に準拠した信頼できる MCP クライアントを前提としています。MCP 仕様では、入力要求機能を提供すると表明したクライアントに対して、UI の提供、リクエスト元サーバーの明示、拒否／キャンセルの選択肢の提供、ユーザーによる応答の確認が求められています。悪意のあるクライアントや、自動応答するよう設定された入力要求フックは、accept と confirm=true を偽装できます。信頼できない MCP クライアントにブリッジを公開しないでください。そのような導入形態では、ブリッジは人間による境界を保証しません。

ブリッジ独自のガードは二次的な防御策です。プリセットが信頼されている（require_approval_for が空）場合、または --yolo が設定されている場合を除き、デフォルトでは execute を request-approval に格下げします。ブリッジが独自に --yolo やバイパスフラグを挿入することはありません。

• MCP の入力要求に自動応答したり、実行フォームを承認する入力要求フックをインストールしたりしないでください。 そうすると、人間による境界が意図的に取り除かれます。
• hermes-action run（execute／yolo）を許可リストに追加しないでください。 コマンドパターンの許可リストでは、安全なプランと副作用を伴う実行を区別できません。
• .hermes-action.yaml にシークレットを記載しないでください。プロバイダーの認証情報は Hermes Agent、OS のキーチェーン、またはプラットフォームのセキュアストアに保管してください。
• --yolo は信頼できるローカル環境でのみ使うための回避策として扱い、デフォルトにはしないでください。

著者によるその他のプロジェクト

Cyril Guilleminot が開発。オフライン優先の音声ツールも制作しています。

• Weesper Neon Flow — テキストを話して任意のアプリに入力できます。タイピングの 3 倍の速度で、完全オフラインに対応しています（macOS および Windows）。
• Weesper Transcribe — macOS App Store で提供されている、オフライン文字起こしツールです。

ライセンス

MIT