点検と修復

ccam doctorはccamの環境を点検します。対象は、Claude Codeのバイナリ、各アカウントのフォルダー、ログイン、共有リンク、共有MCPサーバー、使用量エンドポイント、ショートカットコマンドです。ccam doctor --fixは、データを失わずに修復できるものを修復し、置き換えるファイルは先にバックアップフォルダーに移動します。ccam <name>が共有リンクの問題で停止したとき、ファイルを手動で復元した後、Claude Codeを更新した後に実行してください。

使い方

ccam doctor                  # check everything, change nothing
ccam doctor --fix            # check, then repair what is safe to repair
ccam --dry-run doctor --fix  # report only: what --fix would repair

各結果は記号付きの1行で表示されます。✓は正常、·は情報、!は警告、✗はエラーです。アカウントに関する結果は、アカウント名で始まります。

$ ccam doctor
✓ Claude Code 2.1.302 (Claude Code) (/home/me/.local/bin/claude)
! personal: folder permissions are 755 (should be 0700)
! personal: .credentials.json permissions are 644 (should be 0600)
✓ personal: login valid (me@example.com)
✗ personal: /home/me/.local/share/ccam/profiles/personal/settings.json: set to shared but is a real file, not a link
· personal: unknown entries (Claude Code layout may have changed): newthing
! work: not logged in → `ccam login work`
✓ work: share links OK
! missing shortcuts in /home/me/.local/bin: ccp

`ccam doctor --fix` repairs what it can.

--fixを付けると、修復された結果の末尾に→ fixedが付きます。

$ ccam doctor --fix
✓ Claude Code 2.1.302 (Claude Code) (/home/me/.local/bin/claude)
! personal: folder permissions are 755 (should be 0700) → fixed
! personal: .credentials.json permissions are 644 (should be 0600) → fixed
✓ personal: login valid (me@example.com)
✗ personal: /home/me/.local/share/ccam/profiles/personal/settings.json: set to shared but is a real file, not a link → fixed
· personal: unknown entries (Claude Code layout may have changed): newthing
! work: not logged in → `ccam login work`
✓ work: share links OK
! missing shortcuts in /home/me/.local/bin: ccp → fixed

オプション

ccam doctorは引数を取りません。--dry-runに対応しており、ccam --dry-run doctor --fixはccam doctorと同じ結果を表示し、何も変更しません。

終了コードは、修復されていない✗の結果が1つ以上残っている場合は1、それ以外は0です。警告と情報で失敗することはありません。--fixなしで失敗した場合、ccamは空行と`ccam doctor --fix` repairs what it can.を表示して終わります。設定を読み込めない場合も、ccam:のエラーとともに1で終了します。

しくみ

internal/cli/doctor.goが~/.config/ccam/config.tomlを読み込み、internal/doctor/doctor.goのdoctor.Runを呼び出します。これは決まった順序で点検を実行し、結果を返します。--fixはOptions.Fixとして渡され、ドライランではfalseになります。

中央のブロックはアカウントごとに1回実行されます。各点検と、それぞれに対して--fixが行うことは次のとおりです。

1. Claude Codeのバージョン（checkClaude）。起動時と同じ方法でclaudeのバイナリを特定し、claude --versionを実行します。バージョンが、ccamのフォルダー構成を検証したバージョン（doctor.LayoutVersion）である2.1.302で始まらない場合は、· ccam was verified against the folder layout of Claude Code 2.1.302. Any 'unknown entries' below may mean the layout changedを追加します。バイナリがない場合や--versionが失敗する場合はエラーです。修復はありません。
2. 環境変数の認証情報（checkAuthEnv）。CLAUDE_CODE_OAUTH_TOKEN、ANTHROPIC_API_KEY、ANTHROPIC_AUTH_TOKENが設定されている場合に警告します。そのシェルから起動したすべてのアカウントがこれを引き継ぎ、Claude Codeはアカウント自身のログインよりこれを優先します。修復はありません。自分で設定を解除してください。
3. フォルダー（checkProfile）。アカウントのフォルダーがない場合はエラーで、そのアカウントの点検はそこで終わります。グループやその他のユーザーのビットが立っている権限は警告で、--fixはchmod 0700を実行します。
4. ログインファイル（checkCredentials）。.credentials.jsonをlstatで確認します。各アカウントは独自のトークンを持つ必要があるため、シンボリックリンクはエラーで、修復されません。0600以外のモードは警告で、--fixはchmod 0600を実行します。続いてログインを読み取ります（macOSでは先にキーチェーンから）。ログインがない場合は警告で、ccam login <name>を案内します。リフレッシュトークンの期限切れはlogin expiredエラーです。アクセストークンの期限切れは、次の起動時にClaude Codeが更新するため情報にとどまります。いずれも修復されません。
5. 共有リンク（share.Check）。share.Layoutのすべてのパスをアカウントの共有設定と比較します。使うのはlstatとreadlinkだけです。報告するのは4種類で、リンクがない、リンクが別の場所を指している、リンクがあるべき場所に通常のファイルがある、現在はローカルになった項目のリンクが残っている、です。リンクがないものは警告、それ以外はエラーです。
6. 不明な項目（checkUnknownEntries）。アカウントのフォルダーの最上位にある、ccamが知らない名前（share.Known）を一覧表示します。Claude Codeのフォルダー構成が変わった手がかりになります。情報のみです。
7. プラグインのパス（checkPlugins）。プラグインのレジストリ（installed_plugins.json、known_marketplaces.json）は絶対パスを保存します。各グループのplugins/で、特定のアカウントのフォルダーを経由するパスは、そのアカウントを削除または名前変更すると壊れます。--fixはprofile.RewritePluginPathsでそれらをグループのフォルダーに書き換えます。レジストリファイルはアトミックに書き込まれます。
8. MCPサーバー（checkMCP）。各グループのmcp.jsonを1回ずつ読み込みます。読めないファイルはエラー、mcp.Validateに通らないサーバーは警告です。修復はありません。
9. 使用量の応答形式（checkUsageFormat）。キャッシュを使わず、通常の3秒の制限時間で、応答があるまでアカウントを1つずつ使って使用量エンドポイントに問い合わせます。応答が解析できなくなっている場合は、ccam usageがステータスラインのキャッシュにフォールバックすることを警告します。ネットワークを使うのはこの点検だけです。
10. ショートカット（checkShims）。ショートカットを持つアカウントがある場合だけ実行します。~/.local/binにリンクがない場合は警告で、--fixはshim.Installを呼び出します。これは足りないリンクを作成するだけで、ほかのファイルには触れません。binフォルダーがPATHにない場合は警告で、修復されません。

共有リンクの修復

起動時には、足りないリンクはその場で作成されますが、データを失う可能性があるものについては停止し、ここを案内します。

$ ccam work
ccam: stopped because of share link problems:
  /home/me/.local/share/ccam/profiles/work/CLAUDE.md: set to shared but is a real file, not a link
Repair them with `ccam doctor --fix`, then run again

共有リンクの問題に対して、--fixはアカウントの共有設定を現在の状態と目標の状態の両方に指定してshare.Buildを呼び出し、続いてPlan.Applyを呼び出します。Buildはディスク上の状態からすべての手順を導き直します。これはccam shareが使うのと同じ計画なので、修復は共有を有効にするときと同じ規則に従います。

この例ではsettings.jsonが通常のファイルです。グループにはすでに内容の異なるsettings.jsonがあるため、競合はデフォルトの選択であるKeepGroupになり、グループのコピーが残ります。アカウントのファイルはアカウントのフォルダー内の.ccam-backup/<time>/settings.jsonに移動し、os.Symlinkがそのパスをグループにリンクします。ほかのケースは次のとおりです。

• グループにまだコピーがない場合は、アカウントのファイルがグループに移動し、グループの最初の内容になります。
• フォルダーの場合は、グループにないファイルがグループに移動し、残りはバックアップに移動します。
• history.jsonlの場合、デフォルトはmerge by lineです。グループの行の後に、自分の新しい行が続きます。グループの以前のコピーは.ccam-backup/<time>/group/に保存されます。
• 別のグループへのリンクは置き換えられます。ccamの外にあるフォルダーへのリンクはバックアップに移動し、グループが空であれば、その内容がグループの最初の内容になります。
• 現在はローカルになった項目のリンクは削除され、アカウントにはグループの内容のコピーが作られます。

リンクの削除を除き、すべての手順はデータをグループかバックアップフォルダーに移動します。何も削除されません。

安全性と特殊なケース

• 通常のccam doctorは何も変更しません。スクリプトで確実にしたい場合は、--fixと一緒に--dry-runを使ってください。
• doctor --fixは、アカウントが実行中かどうかを確認しません。セッションがそれらのファイルに書き込み続けるため、共有リンクを修復する前に、そのアカウントのClaude Codeを終了してください。
• 共有の修復に失敗した場合、ccamはそのアカウントについてcould not repair share links: <error>と報告し、不明な項目の点検をスキップします。ほかのアカウントの点検は続きます。
• ccam shareが途中で失敗した場合は、先に目標の設定を保存し、ccam doctor --fixで完了するよう案内します。
• シンボリックリンクになった.credentials.json、期限切れのログイン、環境変数の認証情報は、報告されるだけで変更されることはありません。
• プラグインのレジストリの書き換えはアトミックに書き込まれますが、.ccam-backup/にはコピーされません。

関連項目

• MCPサーバー、設定、履歴の共有
• 既存の環境のコピー
• 使用量の上限とアカウントの切り替え
• コマンド