Hermes Agent

Hermes Agent は、ターミナル、メッセージングプラットフォーム、IDE で実行するオープンソースの AI エージェントフレームワークです。任意の LLM プロバイダー（OpenRouter、Anthropic、OpenAI、DeepSeek、ローカルモデル、および 15 以上のその他）と互換性があり、Linux、macOS、WSL で実行されます。

Hermes を異なるものにする特徴：

• スキルを通じた自己改善 — Hermes は再利用可能な手順をスキルとして保存することで経験から学びます。複雑な問題を解決したり、ワークフローを発見したり、修正されたりすると、その知識をスキルドキュメントとして永続化でき、将来のセッションにロードされます。スキルは時間とともに蓄積され、エージェントは特定のタスクと環境でより優れたものになります。
• セッション間の永続メモリ — あなたが誰であるか、あなたの好み、環境の詳細、学習した教訓を記憶します。プラグ可能なメモリバックエンド（組み込み、Honcho、Mem0 など）により、メモリの動作方法を選択できます。
• マルチプラットフォームゲートウェイ — 同じエージェントが Telegram、Discord、Slack、WhatsApp、Signal、Matrix、Email、および 10 以上の他のプラットフォームで、チャットだけではなく完全なツールアクセスで実行されます。
• プロバイダー非依存 — ワークフロー中にモデルとプロバイダーを切り替えられます。他のものは何も変わりません。認証情報プールは複数の API キー全体で自動的にローテーションされます。
• プロファイル — 独立した Hermes インスタンスを複数実行でき、各インスタンスは分離された設定、セッション、スキル、メモリを持ちます。
• 拡張可能 — プラグイン、MCP サーバー、カスタムツール、webhook トリガー、cron スケジューリング、および Python エコシステム全体。

Hermes は、ソフトウェア開発、研究、システム管理、データ分析、コンテンツ作成、ホームオートメーション、および永続的なコンテキストと完全なシステムアクセスを備えた AI エージェントから恩恵を受けるその他すべての用途に使用されています。

このスキルは Hermes Agent を効果的に操作するのに役立ちます — セットアップ、機能の設定、追加エージェントインスタンスの起動、問題のトラブルシューティング、適切なコマンドと設定の検索、およびシステムを拡張または貢献する必要がある場合にそのしくみを理解するために。

ドキュメント： https://hermes-agent.nousresearch.com/docs/

クイックスタート

# インストール
curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash

# インタラクティブチャット（デフォルト）
hermes

# 単一クエリ
hermes chat -q "What is the capital of France?"

# セットアップウィザード
hermes setup

# モデル/プロバイダーの変更
hermes model

# ヘルスチェック
hermes doctor

---

CLI リファレンス

グローバルフラグ

hermes [flags] [command]

  --version, -V             バージョンを表示
  --resume, -r SESSION      セッションを ID または名前で再開
  --continue, -c [NAME]     名前で再開、または最新のセッション
  --worktree, -w            分離された git worktree モード（並列エージェント）
  --skills, -s SKILL        スキルをプリロード（カンマ区切りまたは繰り返し）
  --profile, -p NAME        名前付きプロファイルを使用
  --yolo                    危険なコマンドの承認をスキップ
  --pass-session-id         セッション ID をシステムプロンプトに含める

サブコマンドなしの場合、chat がデフォルトです。

チャット

hermes chat [flags]
  -q, --query TEXT          単一クエリ、非インタラクティブ
  -m, --model MODEL         モデル（例：anthropic/claude-sonnet-4）
  -t, --toolsets LIST       カンマ区切りのツールセット
  --provider PROVIDER       プロバイダーを強制（openrouter、anthropic、nous など）
  -v, --verbose             詳細出力
  -Q, --quiet               バナー、スピナー、ツールプレビューを抑制
  --checkpoints             ファイルシステムチェックポイントを有効化（/rollback）
  --source TAG              セッションソースタグ（デフォルト：cli）

設定

hermes setup [section]      インタラクティブウィザード（model|terminal|gateway|tools|agent）
hermes model                インタラクティブモデル/プロバイダーピッカー
hermes config               現在の設定を表示
hermes config edit          config.yaml を $EDITOR で開く
hermes config set KEY VAL   設定値を設定
hermes config path          config.yaml パスを表示
hermes config env-path      .env パスを表示
hermes config check         不足または古い設定を確認
hermes config migrate       設定を新しいオプションで更新
hermes login [--provider P] OAuth ログイン（nous、openai-codex）
hermes logout               保存された認証をクリア
hermes doctor [--fix]       依存関係と設定を確認
hermes status [--all]       コンポーネントの状態を表示

ツール & スキル

hermes tools                インタラクティブツール有効/無効化（curses UI）
hermes tools list           すべてのツールとステータスを表示
hermes tools enable NAME    ツールセットを有効化
hermes tools disable NAME   ツールセットを無効化

hermes skills list          インストール済みスキルを一覧表示
hermes skills search QUERY  スキルハブを検索
hermes skills install ID    スキルをインストール
hermes skills inspect ID    インストールせずにプレビュー
hermes skills config        プラットフォームごとのスキル有効/無効化
hermes skills check         アップデートを確認
hermes skills update        古いスキルをアップデート
hermes skills uninstall N   ハブスキルを削除
hermes skills publish PATH  レジストリに公開
hermes skills browse        利用可能なすべてのスキルを参照
hermes skills tap add REPO  GitHub リポジトリをスキルソースとして追加

MCP サーバー

hermes mcp serve            Hermes を MCP サーバーとして実行
hermes mcp add NAME         MCP サーバーを追加（--url または --command）
hermes mcp remove NAME      MCP サーバーを削除
hermes mcp list             設定されたサーバーを一覧表示
hermes mcp test NAME        接続をテスト
hermes mcp configure NAME   ツール選択を切り替え

ゲートウェイ（メッセージングプラットフォーム）

再起動手順（シンプル対フルリビルド）： references/restart-procedure.md

hermes gateway run          ゲートウェイをフォアグラウンドで起動
hermes gateway install      バックグラウンドサービスとしてインストール
hermes gateway start/stop   サービスを制御
hermes gateway restart      サービスを再起動
hermes gateway status       ステータスを確認
hermes gateway setup        プラットフォームを設定

対応プラットフォーム：Telegram、Discord、Slack、WhatsApp、Signal、Email、SMS、Matrix、Mattermost、Home Assistant、DingTalk、Feishu、WeCom、BlueBubbles（iMessage）、Weixin（WeChat）、API Server、Webhooks。Open WebUI は API Server アダプター経由で接続します。

プラットフォームドキュメント：https://hermes-agent.nousresearch.com/docs/user-guide/messaging/

セッション

hermes sessions list        最近のセッションを一覧表示
hermes sessions browse      インタラクティブピッカー
hermes sessions export OUT  JSONL にエクスポート
hermes sessions rename ID T セッションを名前変更
hermes sessions delete ID   セッションを削除
hermes sessions prune       古いセッションをクリーンアップ（--older-than N days）
hermes sessions stats       セッションストア統計

Cron ジョブ

hermes cron list            ジョブを一覧表示（--all で無効化済み）
hermes cron create SCHED    作成：'30m'、'every 2h'、'0 9 * * *'
hermes cron edit ID         スケジュール、プロンプト、配信を編集
hermes cron pause/resume ID ジョブ状態を制御
hermes cron run ID          次のティックで実行をトリガー
hermes cron remove ID       ジョブを削除
hermes cron status          スケジューラー状態

Webhooks

hermes webhook subscribe N  /webhooks/<name> でルートを作成
hermes webhook list         サブスクリプションを一覧表示
hermes webhook remove NAME  サブスクリプションを削除
hermes webhook test NAME    テスト POST を送信

プロファイル

hermes profile list         すべてのプロファイルを一覧表示
hermes profile create NAME  作成（--clone、--clone-all、--clone-from）
hermes profile use NAME     スティッキーデフォルトを設定
hermes profile delete NAME  プロファイルを削除
hermes profile show NAME    詳細を表示
hermes profile alias NAME   ラッパースクリプトを管理
hermes profile rename A B   プロファイルを名前変更
hermes profile export NAME  tar.gz にエクスポート
hermes profile import FILE  アーカイブからインポート

認証情報プール

hermes auth add             インタラクティブ認証情報ウィザード
hermes auth list [PROVIDER] プール済み認証情報を一覧表示
hermes auth remove P INDEX  プロバイダー + インデックスで削除
hermes auth reset PROVIDER  疲弊状態をクリア

その他

hermes insights [--days N]  使用分析
hermes update               最新バージョンにアップデート
hermes pairing list/approve/revoke  DM 認可
hermes plugins list/install/remove  プラグイン管理
hermes honcho setup/status  Honcho メモリ統合（Honcho プラグインが必要）
hermes memory setup/status/off  メモリプロバイダー設定
hermes completion bash|zsh  シェル補完
hermes acp                  ACP サーバー（IDE 統合）
hermes claw migrate         OpenClaw からマイグレーション
hermes uninstall            Hermes をアンインストール

---

スラッシュコマンド（セッション内）

インタラクティブチャットセッション中にこれらを入力します。

セッション制御

/new (/reset)        新しいセッション
/clear               画面をクリア + 新しいセッション（CLI）
/retry               最後のメッセージを再送信
/undo                最後の交換を削除
/title [name]        セッションに名前を付ける
/compress            コンテキストを手動で圧縮
/stop                バックグラウンドプロセスを終了
/rollback [N]        ファイルシステムチェックポイントを復元
/background <prompt> バックグラウンドでプロンプトを実行
/queue <prompt>      次のターンのためにキューに追加
/resume [name]       名前付きセッションを再開

設定

/config              設定を表示（CLI）
/model [name]        モデルを表示または変更
/provider            プロバイダー情報を表示
/personality [name]  パーソナリティを設定
/reasoning [level]   推論を設定（none|minimal|low|medium|high|xhigh|show|hide）
/verbose             サイクル：off → new → all → verbose
/voice [on|off|tts]  音声モード
/yolo                承認バイパスを切り替え
/skin [name]         テーマを変更（CLI）
/statusbar           ステータスバーを切り替え（CLI）

ツール & スキル

/tools               ツールを管理（CLI）
/toolsets            ツールセットを一覧表示（CLI）
/skills              スキルを検索/インストール（CLI）
/skill <name>        スキルをセッションにロード
/cron                Cron ジョブを管理（CLI）
/reload-mcp          MCP サーバーをリロード
/plugins             プラグインを一覧表示（CLI）

ゲートウェイ

/approve             保留中のコマンドを承認（ゲートウェイ）
/deny                保留中のコマンドを拒否（ゲートウェイ）
/restart             ゲートウェイを再起動（ゲートウェイ）
/sethome             現在のチャットをホームチャネルとして設定（ゲートウェイ）
/update              Hermes を最新版にアップデート（ゲートウェイ）
/platforms (/gateway) プラットフォーム接続状態を表示（ゲートウェイ）

ユーティリティ

/branch (/fork)      現在のセッションをブランチ
/btw                 エフェメラルサイドクエスチョン（メインタスクを中断しない）
/fast                優先度/高速処理を切り替え
/browser             CDP ブラウザー接続を開く
/history             会話履歴を表示（CLI）
/save                会話をファイルに保存（CLI）
/paste               クリップボード画像を添付（CLI）
/image               ローカル画像ファイルを添付（CLI）

情報

/help                コマンドを表示
/commands [page]     すべてのコマンドを参照（ゲートウェイ）
/usage               トークン使用状況
/insights [days]     使用分析
/status              セッション情報（ゲートウェイ）
/profile             アクティブなプロファイル情報

終了

/quit (/exit, /q)    CLI を終了

---

キーパスと設定

~/.hermes/config.yaml       メイン設定
~/.hermes/.env              API キーとシークレット
$HERMES_HOME/skills/        インストール済みスキル
~/.hermes/sessions/         セッションのトランスクリプト
~/.hermes/logs/             ゲートウェイとエラーログ
~/.hermes/auth.json         OAuth トークンと認証情報プール
~/.hermes/hermes-agent/     ソースコード（git インストール時）

プロファイルは ~/.hermes/profiles/<name>/ を使用し、同じレイアウトです。

設定セクション

hermes config edit または hermes config set section.key value で編集します。

セクション	キーオプション
model	default、provider、base_url、api_key、context_length
agent	max_turns（90）、tool_use_enforcement
terminal	backend（local/docker/ssh/modal）、cwd、timeout（180）
compression	enabled、threshold（0.50）、target_ratio（0.20）
display	skin、tool_progress、show_reasoning、show_cost
stt	enabled、provider（local/groq/openai/mistral）
tts	provider（edge/elevenlabs/openai/minimax/mistral/neutts）
memory	memory_enabled、user_profile_enabled、provider
security	tirith_enabled、website_blocklist
delegation	model、provider、base_url、api_key、max_iterations（50）、reasoning_effort
smart_model_routing	enabled、cheap_model
checkpoints	enabled、max_snapshots（50）

完全な設定リファレンス：https://hermes-agent.nousresearch.com/docs/user-guide/configuration

プロバイダー

20 以上のプロバイダーが対応しています。hermes model または hermes setup で設定します。

プロバイダー	認証	キー環境変数
OpenRouter	API キー	OPENROUTER_API_KEY
Anthropic	API キー	ANTHROPIC_API_KEY
Nous Portal	OAuth	hermes auth
OpenAI Codex	OAuth	hermes auth
GitHub Copilot	トークン	COPILOT_GITHUB_TOKEN
Google Gemini	API キー	GOOGLE_API_KEY または GEMINI_API_KEY
DeepSeek	API キー	DEEPSEEK_API_KEY
xAI / Grok	API キー	XAI_API_KEY
Hugging Face	トークン	HF_TOKEN
Z.AI / GLM	API キー	GLM_API_KEY
MiniMax	API キー	MINIMAX_API_KEY
MiniMax CN	API キー	MINIMAX_CN_API_KEY
Kimi / Moonshot	API キー	KIMI_API_KEY
Alibaba / DashScope	API キー	DASHSCOPE_API_KEY
Xiaomi MiMo	API キー	XIAOMI_API_KEY
Kilo Code	API キー	KILOCODE_API_KEY
AI Gateway（Vercel）	API キー	AI_GATEWAY_API_KEY
OpenCode Zen	API キー	OPENCODE_ZEN_API_KEY
OpenCode Go	API キー	OPENCODE_GO_API_KEY
Qwen OAuth	OAuth	hermes login --provider qwen-oauth
カスタムエンドポイント	設定	model.base_url + model.api_key in config.yaml
GitHub Copilot ACP	外部	COPILOT_CLI_PATH または Copilot CLI

完全なプロバイダードキュメント：https://hermes-agent.nousresearch.com/docs/integrations/providers

ツールセット

hermes tools（インタラクティブ）または hermes tools enable/disable NAME を通じて有効/無効にします。

ツールセット	提供内容
web	Web 検索とコンテンツ抽出
browser	ブラウザーオートメーション（Browserbase、Camofox、またはローカル Chromium）
terminal	シェルコマンドとプロセス管理
file	ファイルの読み取り/書き込み/検索/パッチ
code_execution	サンドボックス化された Python 実行
vision	画像分析
image_gen	AI 画像生成
tts	テキスト音声変換
skills	スキル閲覧と管理
memory	永続的なクロスセッションメモリ
session_search	過去の会話を検索
delegation	サブエージェントタスク委譲
cronjob	スケジュール済みタスク管理
clarify	ユーザーに明確化について質問
messaging	クロスプラットフォームメッセージ送信
search	Web 検索のみ（web のサブセット）
todo	セッション内タスク計画とトラッキング
rl	強化学習ツール（デフォルトで無効）
moa	Mixture of Agents（デフォルトで無効）
homeassistant	スマートホーム制御（デフォルトで無効）

ツールの変更は /reset（新しいセッション）で有効になります。会話中には適用されず、プロンプトキャッシングを保持するためです。

---

音声とトランスクリプション

STT（音声 → テキスト）

メッセージングプラットフォームからの音声メッセージは自動的にトランスクリプトされます。

プロバイダーの優先度（自動検出）：

1. Local faster-whisper — 無料、API キー不要：pip install faster-whisper
2. Groq Whisper — 無料ティア：GROQ_API_KEY を設定
3. OpenAI Whisper — 有料：VOICE_TOOLS_OPENAI_KEY を設定
4. Mistral Voxtral — MISTRAL_API_KEY を設定

設定：

stt:
  enabled: true
  provider: local        # local、groq、openai、mistral
  local:
    model: base          # tiny、base、small、medium、large-v3

TTS（テキスト → 音声）

プロバイダー	環境変数	無料？
Edge TTS	なし	はい（デフォルト）
ElevenLabs	ELEVENLABS_API_KEY	無料ティア
OpenAI	VOICE_TOOLS_OPENAI_KEY	有料
MiniMax	MINIMAX_API_KEY	有料
Mistral（Voxtral）	MISTRAL_API_KEY	有料
NeuTTS（ローカル）	なし（pip install neutts[all] + espeak-ng）	無料

音声コマンド：/voice on（音声対音声）、/voice tts（常に音声）、/voice off。

---

追加の Hermes インスタンスの起動

完全に独立したサブプロセスとして追加の Hermes プロセスを実行します — 個別のセッション、ツール、環境があります。

これとの比較対象 delegate_task

	delegate_task	Hermes プロセス起動
分離	個別の会話、共有プロセス	完全に独立したプロセス
期間	数分（親ループに制限）	数時間/日
ツールアクセス	親のツールのサブセット	完全なツールアクセス
インタラクティブ	いいえ	はい（PTY モード）
ユースケース	高速並列サブタスク	長期自律ミッション

ワンショットモード

terminal(command="hermes chat -q 'Research GRPO papers and write summary to ~/research/grpo.md'", timeout=300)

# 長時間タスク用のバックグラウンド：
terminal(command="hermes chat -q 'Set up CI/CD for ~/myapp'", background=true)

インタラクティブ PTY モード（tmux 経由）

Hermes は prompt_toolkit を使用し、実際のターミナルが必要です。インタラクティブ起動には tmux を使用します：

# 開始
terminal(command="tmux new-session -d -s agent1 -x 120 -y 40 'hermes'", timeout=10)

# スタートアップを待ってからメッセージを送信
terminal(command="sleep 8 && tmux send-keys -t agent1 'Build a FastAPI auth service' Enter", timeout=15)

# 出力を読む
terminal(command="sleep 20 && tmux capture-pane -t agent1 -p", timeout=5)

# フォローアップを送信
terminal(command="tmux send-keys -t agent1 'Add rate limiting middleware' Enter", timeout=5)

# 終了
terminal(command="tmux send-keys -t agent1 '/exit' Enter && sleep 2 && tmux kill-session -t agent1", timeout=10)

マルチエージェント調整

# エージェント A：バックエンド
terminal(command="tmux new-session -d -s backend -x 120 -y 40 'hermes -w'", timeout=10)
terminal(command="sleep 8 && tmux send-keys -t backend 'Build REST API for user management' Enter", timeout=15)

# エージェント B：フロントエンド
terminal(command="tmux new-session -d -s frontend -x 120 -y 40 'hermes -w'", timeout=10)
terminal(command="sleep 8 && tmux send-keys -t frontend 'Build React dashboard for user management' Enter", timeout=15)

# 進行状況を確認し、コンテキストを相互に中継
terminal(command="tmux capture-pane -t backend -p | tail -30", timeout=5)
terminal(command="tmux send-keys -t frontend 'Here is the API schema from the backend agent: ...' Enter", timeout=5)

セッション再開

# 最近のセッションを再開
terminal(command="tmux new-session -d -s resumed 'hermes --continue'", timeout=10)

# 特定のセッションを再開
terminal(command="tmux new-session -d -s resumed 'hermes --resume 20260225_143052_a1b2c3'", timeout=10)

ヒント

• 高速なサブタスクには delegate_task を優先 — フルプロセス起動よりもオーバーヘッドが少ない
• コードを編集するエージェント起動時には -w（worktree モード）を使用 — git コンフリクトを防ぐ
• ワンショットモードのタイムアウトを設定 — 複雑なタスクは 5 ～ 10 分かかる可能性がある
• 火のセットアンドフォーゲット型には hermes chat -q を使用 — PTY が不要
• インタラクティブセッションには tmux を使用 — 生 PTY モードは prompt_toolkit に \r 対 \n の問題がある
• スケジュール済みタスクの場合、起動する代わりに cronjob ツールを使用 — 配信と再試行を処理します

---

トラブルシューティング

音声が機能しない

1. config.yaml で stt.enabled: true を確認
2. プロバイダーを確認：pip install faster-whisper または API キーを設定
3. ゲートウェイで：/restart。CLI では：終了して再起動。

ツールが利用できない

1. hermes tools — プラットフォーム用にツールセットが有効になっているか確認
2. 一部のツールは環境変数が必要です（.env を確認）
3. ツール有効化後に /reset

モデル/プロバイダーの問題

1. hermes doctor — 設定と依存関係を確認
2. hermes login — OAuth プロバイダーを再認証
3. .env に正しい API キーがあるか確認
4. Copilot 403：gh auth login トークンは Copilot API に対して機能しません。hermes model → GitHub Copilot 経由で Copilot 固有の OAuth デバイスコードフローを使用する必要があります。
5. OpenRouter 無料モデルが /models に表示されない：モデルピッカーはキュレーションされたリストを使用します — すべての無料 OpenRouter モデルが表示されるわけではありません。リストの外のモデルは /model <id> または hermes config set model.default_model "<id>" を通じて直接使用できます。欠落している無料モデルの完全なリストと API プローブコマンドについては、references/openrouter-models.md を参照してください。

変更が反映されない

• ツール/スキル： /reset で更新されたツールセットで新しいセッションを開始
• 設定の変更： ゲートウェイで：/restart。CLI では：終了して再起動。
• コード変更： CLI またはゲートウェイプロセスを再起動

スキルが表示されない

1. hermes skills list — インストール確認
2. hermes skills config — プラットフォーム有効化を確認
3. 明示的にロード：/skill name または hermes -s name

ゲートウェイの問題

最初にログを確認：

grep -i "failed to send\|error" ~/.hermes/logs/gateway.log | tail -20

一般的なゲートウェイの問題：

• SSH ログアウト時にゲートウェイが停止：Linger を有効化：sudo loginctl enable-linger $USER
• WSL2 クローズ時にゲートウェイが停止：WSL2 には systemd サービス動作用に /etc/wsl.conf で systemd=true が必要です。なければ、ゲートウェイは nohup にフォールバック（セッションクローズで停止）。
• ゲートウェイクラッシュループ：失敗状態をリセット：systemctl --user reset-failed hermes-gateway

プラットフォーム固有の問題

• Discord ボット沈黙：Bot → Privileged Gateway Intents で Message Content Intent を有効化する必要があります。
• Slack ボットが DM のみで機能：message.channels イベントにサブスクライブする必要があります。なければ、ボットは公開チャネルを無視します。
• Windows HTTP 400 "No models provided"：設定ファイルエンコーディング問題（BOM）。config.yaml が BOM なしの UTF-8 として保存されていることを確認します。

補助モデルが機能しない

auxiliary タスク（vision、compression、session_search）が無音で失敗する場合、auto プロバイダーがバックエンドを見つけられません。OPENROUTER_API_KEY または GOOGLE_API_KEY を設定するか、各補助タスクのプロバイダーを明示的に設定します：

hermes config set auxiliary.vision.provider <your_provider>
hermes config set auxiliary.vision.model <model_name>

---

何かを探している場所

探しているもの...	場所
設定オプション	hermes config edit または 設定ドキュメント
利用可能なツール	hermes tools list または ツールリファレンス
スラッシュコマンド	セッション内の /help または スラッシュコマンドリファレンス
スキルカタログ	hermes skills browse または スキルカタログ
プロバイダーセットアップ	hermes model または プロバイダーガイド
プラットフォームセットアップ	hermes gateway setup または メッセージングドキュメント
MCP サーバー	hermes mcp list または MCP ガイド
プロファイル	hermes profile list または プロファイルドキュメント
Cron ジョブ	hermes cron list または Cron ドキュメント
メモリ	hermes memory status または メモリドキュメント
環境変数	hermes config env-path または 環境変数リファレンス
CLI コマンド	hermes --help または CLI リファレンス
ゲートウェイログ	~/.hermes/logs/gateway.log
セッションファイル	~/.hermes/sessions/ または hermes sessions browse
ソースコード	~/.hermes/hermes-agent/

---

貢献者向けクイックリファレンス

オケージョナルな貢献者と PR 作成者向け。完全な開発者ドキュメント：https://hermes-agent.nousresearch.com/docs/developer-guide/

プロジェクトレイアウト

hermes-agent/
├── run_agent.py          # AIAgent — コア会話ループ
├── model_tools.py        # ツール検出とディスパッチ
├── toolsets.py           # ツールセット定義
├── cli.py                # インタラクティブ CLI（HermesCLI）
├── hermes_state.py       # SQLite セッションストア
├── agent/                # プロンプトビルダー、コンテキスト圧縮、メモリ、モデルルーティング、認証情報プーリング、スキルディスパッチ
├── hermes_cli/           # CLI サブコマンド、設定、セットアップ、コマンド
│   ├── commands.py       # スラッシュコマンドレジストリ（CommandDef）
│   ├── config.py         # DEFAULT_CONFIG、環境変数定義
│   └── main.py           # CLI エントリーポイントと argparse
├── tools/                # ツールごとに 1 ファイル
│   └── registry.py       # 中央ツールレジストリ
├── gateway/              # メッセージングゲートウェイ
│   └── platforms/        # プラットフォームアダプター（telegram、discord など）
├── cron/                 # ジョブスケジューラー
├── tests/                # 約 3000 個の pytest テスト
└── website/              # Docusaurus ドキュメントサイト

設定：~/.hermes/config.yaml（設定）、~/.hermes/.env（API キー）。

ツールの追加（3 ファイル）

1. tools/your_tool.py を作成：

import json, os
from tools.registry import registry

def check_requirements() -> bool:
    return bool(os.getenv("EXAMPLE_API_KEY"))

def example_tool(param: str, task_id: str = None) -> str:
    return json.dumps({"success": True, "data": "..."})

registry.register(
    name="example_tool",
    toolset="example",
    schema={"name": "example_tool", "description": "...", "parameters": {...}},
    handler=lambda args, **kw: example_tool(
        param=args.get("param", ""), task_id=kw.get("task_id")),
    check_fn=check_requirements,
    requires_env=["EXAMPLE_API_KEY"],
)

2. toolsets.py に追加 → _HERMES_CORE_TOOLS リスト。

自動検出：トップレベルの registry.register() 呼び出しがある tools/*.py ファイルは自動的にインポートされます — 手動リストは不要です。

すべてのハンドラーは JSON 文字列を返す必要があります。パスには get_hermes_home() を使用し、決して ~/.hermes をハードコードしないでください。

スラッシュコマンドの追加

1. hermes_cli/commands.py の COMMAND_REGISTRY に CommandDef を追加
2. cli.py → process_command() にハンドラーを追加
3. （オプション）gateway/run.py にゲートウェイハンドラーを追加

すべてのコンシューマー（ヘルプテキスト、オートコンプリート、Telegram メニュー、Slack マッピング）は中央レジストリから自動的に派生します。

エージェントループ（高レベル）

run_conversation():
  1. システムプロンプトをビルド
  2. iterations < max の間ループ：
     a. LLM を呼び出し（OpenAI 形式メッセージ + ツールスキーマ）
     b. tool_calls の場合 → handle_function_call() を通じて各々をディスパッチ → 結果を追加 → 続行
     c. テキストレスポンスの場合 → 返す
  3. コンテキスト圧縮はトークン制限近くで自動的にトリガー

テスト

python -m pytest tests/ -o 'addopts=' -q   # フルスイート
python -m pytest tests/tools/ -q            # 特定エリア

• テストは HERMES_HOME を自動的に一時ディレクトリにリダイレクト — 実際の ~/.hermes/ に触れることはありません
• 変更をプッシュする前にフルスイートを実行
• -o 'addopts=' を使用してベイクインされた pytest フラグをクリア

コミット規約

type: 簡潔なサブジェクト行

オプショナルボディ。

タイプ：fix:、feat:、refactor:、docs:、chore:

主要なルール

• プロンプトキャッシングを決して破らない — 会話中にコンテキスト、ツール、またはシステムプロンプトを変更しない
• メッセージロール交代 — 連続した 2 つのアシスタントメッセージまたは 2 つのユーザーメッセージを決して使用しない
• hermes_constants から get_hermes_home() をすべてのパスに使用（プロファイル対応）
• 設定値は config.yaml に、シークレットは .env に
• 新しいツールには check_fn が必要です。ので、要件が満たされたときにのみ表示されます

---

外部ツールからの AIAgent の統合

問題

外部ツール（AionUI、別のエージェントプラットフォーム、カスタムブリッジ）が プログラムで Hermes AIAgent を呼び出す必要がある場合、hermes-agent ソースツリー内の from run_agent import AIAgent は sys.path 操作でも失敗します。Python は外部コンテキストからそのパスを確実にインポートできません。

信頼できるパターン：venv Python でのサブプロセス

import subprocess, json, sys

HERMES_VENV_PYTHON = "/home/alvarobiano/.hermes/hermes-agent/venv/bin/python"
RUN_AGENT_PATH = "/home/alvarobiano/.hermes/hermes-agent/run_agent.py"

request = {
    "model": "MiniMax-M2.7",
    "provider": "minimax",
    "messages": [{"role": "user", "content": "pergunta"}],
    "system": "You are Bianinho.",
}
result = subprocess.run(
    [HERMES_VENV_PYTHON, RUN_AGENT_PATH],
    input=json.dumps(request),
    capture_output=True, timeout=60
)
response = json.loads(result.stdout)

重要な洞察：run_agent.py をモジュールとしてインポートしようとするのではなく、venv Python バイナリを直接起動します。venv Python には、すべての依存関係（httpx、chatlas など）が正しく解決されています。

venv Python を検索：

find ~/.hermes/hermes-agent -name "python" -type f 2>/dev/null | grep venv

プロトコルブリッジング：Hermes ↔ AionUI（aionrs）

Hermes は JSON-RPC（LSP のような）を使用します。AionUI は aionrs JSON Stream Protocol を stdin/stdout 経由で使用します — 異なるイベントスキーマです。ブリッジが必要です：

外部ツール（aionrs） → ブリッジ（Python） → Hermes AIAgent → ブリッジ → 外部ツール

ブリッジの責務：

1. stdin から aionrs message イベントを解析
2. Hermes AIAgent.chat() リクエスト形式に翻訳
3. AIAgent を呼び出し（上記のサブプロセス）
4. ストリーミングレスポンスを aionrs text_delta / stream_end イベントに戻す
5. aionrs JSON Lines を stdout に書き込み

aionrs イベントタイプ： ready、message、message_end、stream_start、text_delta、stream_end、error、ping、pong

完全なブリッジ実装：aionui-hermes-ten リポジトリの scripts/aionrs-bridge/aionrs_bridge.py。

ACP プロトコル：ネイティブエージェントとしての Hermes

Hermes は POTENTIAL_ACP_CLIS（PATH の hermes を検索）を通じて AionUI により自動検出されます。ACP プロトコルは stdin/stdout を通じて aionrs イベントを使用します。Hermes が検出されると、AionUI はそれを ACP CLI として起動し、aionrs を通じて通信します — これがブリッジが必要な理由です。

参照：aionui-hermes-ten リポジトリの docs/INTEGRATION.md で完全なプロトコル詳細。