Claude Codeの設定をHermes Agentへ移す前に｜import-agentのdry-runを試す

長く使った Claude Code には、CLAUDE.mdや許可ルールが残っています。Hermes Agent を試すために、それらを手で写すのは面倒です。でも、一括移行をすぐ実行すると、古い指示まで新しい環境へ持ち込むおそれがあります。

2026 年 9 月 12 日、Raspberry Pi 上でhermes import-agent claude-code --dry-runを実行しました。結果は、移行候補が 1 件、skip が 4 件でした。ファイルは変更されていません。

今回は、この 5 件を読み解きます。移行作業より先に、何を残し、何を捨てるか決めるためです。

前回完了時と今回完了後

前回までは、Claude Code と Hermes Agent の設定を別々に管理していました。移行対象の件数や、変換できないルールは未確認でした。

今回完了後は、次の状態になります。

• CLAUDE.mdが Hermes の memory 候補になると分かります
• 許可、拒否、MCP、skill の検出結果を項目別に確認できます
• credential が移行されない境界を確認できます
• 本番へ書き込む前に、採用しない指示を選別できます

この回では本番適用をしません。--dry-runの結果を読むところで止めます。

なぜコピー前の棚卸しが必要なのか

設定移行で怖いのは、ファイルの破損だけではありません。昔の役割や広すぎる権限が、正常な設定としてコピーされることも問題です。

例えば、Claude Code のCLAUDE.mdに「すべて自動承認する」という古い方針が残っていたとします。構文として移行できても、現在の Hermes 運用に合うとは限りません。移行成功と運用上の妥当性は別です。

権限の形式にも差があります。Claude Code のBash(...)ルールは対応先があります。一方、Read(...)やWebFetchは Claude 固有のルールです。Hermes へ機械的に置き換えず、unmapped として確認します。

秘密情報はさらに慎重に扱います。Hermes のimport-agentは credential file を読みません。MCP 設定でも、secret らしい環境変数や header を除外します。移行後の認証は、別の手順で設定します。

全体の流れ

~/.claude
  ├── CLAUDE.md
  ├── settings.json
  ├── MCP servers
  └── skills/
          │
          ▼
hermes import-agent claude-code --dry-run
          │
          ├── would import
          ├── skipped
          ├── unmapped
          └── error
          │
          ▼
人が内容と競合を確認
          │
          └── 今回は適用せず終了

hermes import-agentは、Claude Code や Codex CLI の設定を Hermes 向けに変換するコマンドです。バックアップ zip を復元するhermes importとは別物です。

用語表

用語	この回での意味
import-agent	他のコーディングエージェントの設定をHermesへ移すコマンドです
dry-run	書き込まず、移行予定だけを表示する実行方法です
would import	本番適用時に移行対象となる項目です
skipped	元データがない場合や、競合などで移行しない項目です
unmapped	製品固有で、Hermes向けに自動変換しない項目です
overwrite	名前が競合した既存項目を置き換える指定です
credential	API keyや認証tokenなどの秘密情報です

飛ばせる章

Claude Code の設定がすでにあり、dry-run だけ試す場合は「実機で dry-run する」へ進めます。

結果にmcp-serversやskillsが出た場合は、「5 件の結果を読む」の後も続けてください。秘密情報の扱いだけ確認したい場合は、「credential は別経路で設定する」まで飛ばせます。

対応関係を先に確認する

公式ドキュメントでは、Claude Code からの主な対応関係を次のように示しています。

Claude Code	Hermes Agent	判断点
CLAUDE.md	memory entries	古い指示を恒久記憶へ残すか確認します
permissions.allowのBash(...)	command_allowlist	許可範囲が広すぎないか確認します
permissions.denyのBash(...)	approvals.deny	拒否ルールが現在も必要か確認します
MCP servers	mcp_servers	接続先と秘密の再設定方法を確認します
skills/<name>/	skills/claude-code-imports/<name>/	同名skillとの重複を確認します
commands/*.md	自動移行しません	必要ならskillとして作り直します

Bash(npm run test:*)のような prefix rule は、Hermes 側の glob へ変換されます。見た目が似ていても、実行前に変換後の範囲を読みます。

Claude Code のRead(...)やWebFetchは、そのまま Hermes の shell 権限にはなりません。自動変換されない項目を、移行漏れと決めつけないことが大切です。

実機でdry-runする

最初に help を確認します。

hermes import-agent --help

確認した主要部分は次の通りです。

usage: hermes import-agent ... [{claude-code,codex}]

--source SOURCE  Path to the agent's config directory
--dry-run        Preview only
--overwrite      Overwrite existing Hermes items on name conflicts
--yes, -y        Skip confirmation prompts

次に、Claude Code を明示して dry-run します。

hermes import-agent claude-code --dry-run

期待する出力は、移行元、移行先、上書き方針、秘密情報の扱いを含む preview です。今回の実出力では、次の設定を確認できました。

Agent:       claude-code
Source:      ~/.claude
Target:      ~/.hermes
Overwrite:   no (skip conflicts)
Secrets:     never imported

絶対パスには利用者名が含まれるため、ここでは~へ置き換えています。秘密値は表示されませんでした。

5件の結果を読む

今回の summary は次の通りです。

Summary: 1 would import, 4 skipped

移行候補は 1 件でした。

claude-md → ~/.hermes/memories/MEMORY.md

これは、Claude Code のグローバルなCLAUDE.mdを、Hermes の memory entry へ移す予定を表します。ファイルが見つかったことは、内容が現在も正しいことを保証しません。

移行前に、次の内容を探します。

• すでに役目を終えた作業手順
• 特定リポジトリだけで使う規約
• 現在の Hermes 設定と矛盾する指示
• API key や個人情報の書き残し
• 同じ意味を持つ重複した記述

skip は 4 件でした。

command-allowlist  No permissions.allow rules found
command-denylist   No permissions.deny rules found
mcp-servers        No MCP servers found
skills             No skills directory found

この skip はエラーではありません。移行元に該当データがなかったことを示します。0 件の項目を無理に作らないため、今回の環境では自然な結果です。

最後に、書き込みがなかったことを確認しました。

No files were modified. This is a preview of what would happen.

summary の件数だけでなく、この行まで読みます。--dry-runを付け忘れた実行結果と混同しないためです。

結果を4種類に分ける

別の環境では、would import と skipped 以外も現れます。結果は次の 4 種類で整理すると判断しやすくなります。

would import

本番適用時に追加される候補です。内容を読み、移行後の置き場所が適切か確認します。

skipped

元データがない場合や、既存項目との競合で移行しない候補です。既存項目を守る標準動作なので、反射的に--overwriteを足しません。

unmapped

Claude Code 固有の権限など、自動変換しない項目です。Hermes の承認や tool 設定で、同じ目的をどう実現するか個別に決めます。

error

壊れたsettings.jsonやconfig.tomlは、項目単位の error として報告されます。他の正常な項目まで一括で捨てず、エラー箇所を先に直します。

credentialは別経路で設定する

import-agentは、Claude Code の credential file を移行しません。Codex CLI のauth.jsonも対象外です。

MCP server の設定に環境変数や header があっても、名前が*_TOKENや*_API_KEY、Authorizationのように秘密を示す場合は除外されます。接続先の形だけ移り、認証情報は移らない状態を想定します。

Claude Code credentials
  └── import-agentでは読まない

MCP server config
  ├── 接続設定は移行候補
  └── secretらしいenvとheaderは除外

移行後に provider を使う場合は、Hermes 側の setup や secret 管理で認証を設定します。Claude Code の認証ファイルをコピーして穴埋めしません。

この分離には意味があります。設定の移行と秘密の移送を同時に行うと、preview で安全に共有できる情報が減るからです。

--overwrite --yesを急いで付けない

--overwriteは、同名の MCP server や skill があるときに既存項目を置き換えます。--yesは確認を省略します。どちらも自動化には便利ですが、初回の棚卸しには強すぎます。

特に、次の状態では適用を止めます。

• memory へ入る指示の意味を確認していません
• unmapped の権限が残っています
• 同名 skill のどちらを正本にするか決まっていません
• MCP の credential をどこで管理するか決まっていません
• preview の件数が予想と違います

まず--dry-runの出力を保存します。次に移行元の該当ファイルを読み、項目ごとに採否を決めます。本番適用は、その後の別作業です。

よくあるエラー

症状	原因	対応
hermes importのhelpが表示されます	backup復元用の別コマンドを指定しています	hermes import-agent --helpを実行します
移行候補が0件です	移行元が空か、別の場所にあります	--sourceで設定ディレクトリを明示します
permissions.allowがskipされます	Claude Code側に対象のBashルールがありません	エラー扱いせず、元設定を確認します
Read(...)が移行されません	Claude固有の非Bash権限です	unmappedを確認し、Hermes側で個別に設計します
credentialが見つかりません	credentialは意図的に移行対象外です	Hermes側で別途認証を設定します
同名skillがskipされます	既存のHermes skillと競合しています	両方を読み、安易に--overwriteしません
JSONやTOMLのitem errorが出ます	移行元の設定ファイルが壊れています	該当ファイルだけを修正し、dry-runを再実行します
非対話実行がpreviewで止まります	--yesなしではpreview後に適用しません	自動適用前にレビュー工程を作ります

適用前の確認票

本番適用へ進む場合も、次の項目を満たすまでは書き込みません。

• 移行元と移行先が意図したパスです
• would import の各項目を読みました
• skipped の理由を説明できます
• unmapped の代替設計を決めました
• credential が別管理になると理解しています
• 競合時の正本を決めました
• --overwriteが必要な項目を限定しました
• dry-run の件数を記録しました

今回の実機結果では、1 would import, 4 skippedまで確認できました。移行候補のCLAUDE.mdは、人が内容を選別します。そのため、本番適用には進みませんでした。

AI エージェントの設定は、コピーできるほど移行が簡単になります。同時に、古い判断も運びやすくなります。dry-run は失敗を避けるだけの機能ではありません。次のエージェントへ何を覚えさせるか、書き込む前に決めるための境界です。

出典

資料	確認した内容
Hermes Agent公式ドキュメント: Import from Other Agents	対応項目、credential除外、preview、競合、error処理
NousResearch/hermes-agent	Hermes Agentの公式リポジトリ
hermes import-agent --helpの実機出力	対象agentと各flagの説明
hermes import-agent claude-code --dry-runの実機出力	1件の移行候補、4件のskip、未変更の確認