CLAUDE_CODE_DISABLE_EXPLORE_PLAN_AGENTSでExploreとPlanを無効にする

CLAUDE_CODE_DISABLE_EXPLORE_PLAN_AGENTS は、Claude Codeに組み込まれたExploreとPlanの2つのサブエージェントだけを外す環境変数です。値は 1 で、Claude Code v2.1.198以降が必要です。

無効にすると、Claudeは検索ツールか汎用(general-purpose)サブエージェントでコードベースを調べます。プランモードでも、ExploreやPlanに任せず、ファイルを直接読みます。同名の自作サブエージェントは影響を受けません。

設定すると何が変わるのか

組み込みのExploreは読み取り専用の高速な検索役、Planはプランモードで計画の前に調査をする役です。どちらもWriteとEditが拒否されます。

この2つを外した後の動きは次のとおりです。

• 探索は検索ツールか汎用サブエージェントが担う
• プランモードはExploreとPlanを起動せず、ファイルを直接読む
• Explore または Plan という名前の自作サブエージェントは、そのまま使える

Exploreは呼び出されるたびに、探索の深さを3段階から選びます。

• quick: 狙った箇所を引くだけの検索
• medium: ほどほどの範囲を調べる探索
• very thorough: コードベース全体を見渡す網羅的な分析

無効にすると、この深さの使い分けごとなくなります。広く読ませたいときも、浅く済ませたいときも、メイン会話の検索ツールか汎用サブエージェントに指示する形になります。

設定の書き方

シェルで一時的に試すなら、起動前に変数を付けます。

CLAUDE_CODE_DISABLE_EXPLORE_PLAN_AGENTS=1 claude

常用するなら、設定ファイルの env キーに書きます。Claude Codeがファイルから直接読むので、どの経路で claude を起動しても効きます。

{
  "env": {
    "CLAUDE_CODE_DISABLE_EXPLORE_PLAN_AGENTS": "1"
  }
}

書き込み先で適用範囲が決まります。

実行中のセッションは、ファイルを保存した時点で新しい値を環境に反映します。変数を消した場合は、実行中のセッションでは解除されず、次に claude を起動したときに効きます。

古いバージョンでは変数が認識されない可能性があるため、先にバージョンを見ておきます。

claude --version

影響しないものと、同じ名前の自作サブエージェント

この変数が外すのは、組み込みのExploreとPlanだけです。汎用サブエージェントは残り、Claudeはそちらへ探索を回せます。

残る汎用サブエージェントは、Exploreと違って読み取り専用ではありません。サブエージェントが使えるツールをすべて持ち、探索と変更の両方が要る複雑な作業や、結果の解釈に推論が要る作業、依存する手順が続く作業を引き受けます。Exploreの代わりに探索を任せると、読み取り専用の制約が外れる点が違いです。モデルもExploreとは決まり方が異なり、CLAUDE_CODE_SUBAGENT_MODEL を設定していて、ほかに割り当てがなければその値になります。設定がなければメイン会話のモデルです。なお、組み込みにはほかにも、/statusline の設定を手伝うstatusline-setupや、Claude Codeの機能に答えるclaude-code-guideといった補助のエージェントがあります。この変数で外れるのはExploreとPlanの2つだけなので、これらは残ります。

.claude/agents/ に置いた Explore という名前の自作サブエージェントは影響を受けません。組み込みを外したうえで、自分用の探索役を同じ名前で置く構成も成り立ちます。ユーザーまたはプロジェクトのサブエージェントが Explore という名前なら組み込みを上書きし、自身の model フィールドを保ちます。model: haiku を付けた Explore を置けば、探索だけを低コストのモデルで動かせます。

Plan という名前の自作サブエージェントも、環境変数の説明では影響を受けないと書かれています。ただし、組み込みのPlanを上書きする挙動の記述があるのはExploreについてだけです。Plan で同じことを期待する場合は、先に小さなプロジェクトで動きを確かめておくと安全です。

他の止め方との違い

サブエージェントを止める手段は複数あり、効く範囲が違います。

Exploreだけを止めたい場合は、権限ルールでも書けます。

{
  "permissions": {
    "deny": ["Agent(Explore)"]
  }
}

--disallowedTools は同じ指定を起動時の引数で渡す方法で、設定ファイルを触らずに今回のセッションだけ止めたいときに向きます。どちらも名前で1つずつ止めるものです。ExploreとPlanをまとめて外す目的なら、環境変数のほうが1行で済みます。逆に、Agent(Explore) を拒否しても、Plan は別に拒否しない限り残ります。

SDKや非対話モードで全部外すときの落とし穴

Agent SDKや -p フラグの非対話モードで、組み込みのサブエージェントを全部外したいときは、別の変数 CLAUDE_AGENT_SDK_DISABLE_BUILTIN_AGENTS を使います。1 を設定すると、ExploreやPlanを含む組み込みの型がすべて無効になります。SDK利用者が白紙の状態から自作のサブエージェントだけを使う用途です。

ここで見落としやすいのが、この変数は汎用サブエージェントも消すことです。Agentツールの呼び出しで subagent_type を省くと、Claude Codeは汎用サブエージェントを起動する仕様ですが、それが無いので呼び出しが失敗します。出るエラーは次のとおりです。

subagent_type is required: the general-purpose agent is not available in this session. Available agents: ...

エラーの解説ページには、このエラーが出る条件が2つ挙がっています。

• 非対話モードで CLAUDE_AGENT_SDK_DISABLE_BUILTIN_AGENTS=1 を設定している
• メインスレッドのエージェントに tools: Agent(...) の許可リストがあり、そこに general-purpose が含まれていない

したがって、CLAUDE_CODE_DISABLE_EXPLORE_PLAN_AGENTS は汎用サブエージェントを残すので、このエラーの原因にはなりません。「ExploreとPlanだけ外したい」のか「組み込みを全部外して自作だけにしたい」のかで、使う変数を分けます。

無効にする前に考えておきたいこと

無効化する理由は、運用の癖と合うかで決まります。いくつかの観点を挙げます。

探索の出力がメイン会話に載る

Exploreに委譲すると、探索の結果はメイン会話のコンテキストの外に留まります。無効にすれば、この分離は働かなくなります。検索ツールでメイン会話が直接調べる場合、調査で読んだ内容はメイン会話側に積まれます。大きなリポジトリで広く読ませる場面では、コンテキストの消費が変わりうる点です。コンテキストの扱い全般はClaude Codeのコンテキスト管理にまとめています。

CLAUDE.mdとgit statusの扱い

ExploreとPlanは、CLAUDE.mdとgit statusのスナップショットを読み込まない設計です。調査を速く安く保つためです。メイン会話はCLAUDE.mdを読んでいるので、直接調べる場合はプロジェクトの規約を踏まえた探索になります。一方、汎用サブエージェントに探索を回す場合は、CLAUDE.mdを読み込むかどうかが変わります。サブエージェントごとの扱いはomitClaudeMdの記事で詳しく扱っています。

後から続けられるかどうか

組み込みのExploreとPlanは一度きりの実行で、エージェントIDを返さないため、Claudeは再開できません。続きの作業が要るなら、汎用サブエージェントか自作のサブエージェントを使います。探索の続きを同じエージェントに頼みたい運用では、そもそもExploreに頼らない構成が合います。

モデルの割り当て

Exploreのモデルは、メイン会話のモデルを引き継ぐのが基本です。メイン会話がFableのときは接続方法で変わり、Claudeのサブスクリプション、Anthropic Console、ANTHROPIC_BASE_URL 経由のLLMゲートウェイでは、opus エイリアスが指すOpusで動きます。Exploreを外すと、この割り当ては関係なくなり、探索は検索ツールか汎用サブエージェントのモデル選択に従います。サブエージェント全体のモデルを固定する方法はCLAUDE_CODE_SUBAGENT_MODELの記事にあります。ただし、CLAUDE_CODE_SUBAGENT_MODEL だけでは、組み込みのExploreとPlanのモデルは変わりません。

プランモードとの関係

プランモードは、Claudeが調査して計画を提案し、承認されるまでソースを編集しない動作モードです。通常はプランモードで調査が必要になると、Planサブエージェントに調査を任せ、メイン会話は読み取り専用のまま保たれます。

CLAUDE_CODE_DISABLE_EXPLORE_PLAN_AGENTS=1 を設定すると、この委譲が起きず、Claudeがファイルを直接読みます。プランモードの使い方はPlanモード完全ガイドを参照してください。サブエージェント全般の設計はSub-agents完全ガイドにあります。

使い分けの目安

探索を直接読ませるかどうかは、リポジトリの大きさと、コンテキストをどこで消費したいかの問題です。まず小さく試し、メイン会話のコンテキストの伸び方が変わるかを見るのが現実的です。