Claude Code は通常、Bash・Read・Edit などのツールを1回ずつ呼び出し、その結果を読んでから次の手を決めます。Code Mode はこの進め方を変える実験的な機能で、Claude が複数のツール呼び出しをまとめた JavaScript を書き、Claude Code がそのコードをセッション内で実行します。この記事では、公式ドキュメント「Run tool calls from code with Code Mode」をもとに、仕組み、利用条件と制限、有効化の手順、権限チェックの扱い、起動しないときの対処を整理します。Code Mode は既定でオフで、今後のリリースで変更・削除される可能性があります。
Code Mode の仕組みと向いている作業
Code Mode のセッションでも、利用者がやることは変わりません。プロンプトで作業を伝えると、Claude がそれを実行する JavaScript を書きます。1つのコードの中で、コマンドを並列に実行したり、ある呼び出しの結果を次の呼び出しに渡したり、出力のうち Claude が読む必要のある部分だけを返したりできます。
公式ドキュメントの例では、リトライ回数の上限を上げるよう頼むと、Claude は次のようなコードでファイルを探し、編集し、テストを実行します。最終行で、編集したファイルのパスとテスト出力を Claude に返しています。
const files = await $`rg -l "function retryPolicy" src`.text();
const target = files.trim().split("\n")[0];
await edit(target, "maxAttempts: 3", "maxAttempts: 5");
({ edited: target, tests: $`npm test -- retryPolicy`.nothrow() });
会話画面に表示されるのは編集の差分などのツール呼び出しで、コードそのものは表示されません。コードを見るには Ctrl+O でトランスクリプトビューアを開きます。各コードは折りたたまれた Code 行として並び、展開方法のヒントが付いています。
公式ドキュメントが試す対象として挙げているのは、関連するツール呼び出しが多数続く作業です。
- 多数のファイルにまたがって同じ変更を繰り返す
- 検索結果を Claude が読む前に絞り込む必要がある
- 互いに独立した複数のコマンドを同時に実行できる
利用条件と制限
Code Mode を使うには、次の条件をすべて満たす必要があります。
| 項目 | 条件 |
|---|---|
| バージョン | Claude Code v2.1.323 以降(どちらのリリースチャネルでも可) |
| アカウント | Claude のサブスクリプションまたは Console アカウント。ゲートウェイ、Amazon Bedrock、Claude Platform on AWS、Google Cloud の Agent Platform、Microsoft Foundry 経由では使えない |
| 組織 | HIPAA 構成やゼロデータ保持(ZDR)を使っていないこと |
| モデル | Claude Opus 5.5、Sonnet 5.5、Haiku 5.5、Fable 5.2 |
| 利用形態 | ターミナルでの対話型 claude セッションのみ。-p、Agent SDK、VS Code のパネル、デスクトップアプリ、クラウドセッションでは動かない |
| インストール | ネイティブビルドの Claude Code |
| Windows | Git for Windows がインストールされていること |
このほか、API キーヘルパー、エージェントチーム、OpenTelemetry のエクスポート、DISABLE_TELEMETRY などが有効なままでは Code Mode を開始できません(対処は最後の節の表を参照)。
有効にする前に、次の制限を受け入れられるか確認しておきます。
- 再開: Code Mode のセッションを再開できるのはターミナルからだけで、そのときも Code Mode がオンである必要があります。
- auto モード: auto モードの分類器は、ツール呼び出しごとではなくコード単位で審査します。
- 長時間動くコード: バックグラウンド実行できる条件を満たさない限り、終了まで待つことになり、10分で停止します。
- フック:
PreToolUseフックが起動できない・タイムアウトした場合にツール呼び出しが拒否されたり、UserPromptSubmitフックでコードの出力がブロックされたりすることがあります。 - 使えない機能: Remote Control、Claude in Chrome、コンピュータ操作(computer use)。
- セッションの移動: デスクトップアプリへの移動やバックグラウンドセッションへの切り替えはできず、
/forkでバックグラウンドのコピーを始めることもできません。
有効化と無効化の手順
1. バージョンを確認する: claude --version を実行し、v2.1.323 より古ければ claude update で更新します。stable チャネルで v2.1.323 に届かない場合は、追いつくのを待つか latest チャネルに切り替えます。
2. Code Mode をオンにして起動する: 環境変数 CLAUDE_CODE_EXPERIMENTAL_CODE_MODE を 1 にします。試すだけならシェルで、新しいセッションすべてで使うならユーザー設定に書きます。
# macOS / Linux / WSL
CLAUDE_CODE_EXPERIMENTAL_CODE_MODE=1 claude
# Windows PowerShell
$env:CLAUDE_CODE_EXPERIMENTAL_CODE_MODE = "1"
claude
ユーザー設定の場合は ~/.claude/settings.json に次の env ブロックを保存してから claude を起動します。
{
"env": {
"CLAUDE_CODE_EXPERIMENTAL_CODE_MODE": "1"
}
}
この変数はプロジェクトの設定ファイルに書いても無視されます。クローンしたリポジトリが勝手に Code Mode をオンにすることはありません(設定ファイルの種類と優先順位は設定と権限の記事を参照)。
3. 確認に答える: 初回は確認が表示されるので Yes, turn on Code Mode を選びます。Claude Code が再起動し、セッション上部に Code Mode (experimental) is on · this session can be resumed only with Code Mode on と表示されれば有効です。
4. 試す: よく知っているプロジェクトで、「このプロジェクトの Markdown ファイルをすべて読み、存在しないローカルファイルを指しているリンクを一覧にして」のような、ツール呼び出しの多い作業を頼みます。終わったら Ctrl+O で Code 行を展開し、Claude が書いた JavaScript を確認します。もう一度 Ctrl+O を押すと会話に戻ります。
Code Mode のセッションを後で claude --continue や claude --resume で再開するときは、変数を 1 のままにしておく必要があります。オフの状態では再開が拒否されます。逆に、Code Mode なしで始めたセッションは、変数を設定していても Code Mode なしで再開されます。
オフにするには、シェルと ~/.claude/settings.json の両方から変数を削除して新しいセッションを始めます。値を 0 にしてもよく、どちらか一方に 0 があれば、もう一方が 1 でもオフのままです。
組織として禁止したい場合は、マネージド設定の env に "CLAUDE_CODE_EXPERIMENTAL_CODE_MODE": "0" を入れます。すでに Code Mode のセッションにいる利用者は終了・再起動するまでそのままですが、その後は Code Mode なしで起動し、0 がある間は Code Mode のセッションを再開できません。なお、マネージド設定から利用者の Code Mode をオンにすることはできません。
権限チェックと長時間動くコード
Claude のコードが行う各ツール呼び出しは、通常どおり deny・ask の権限ルールと PreToolUse フックを通ります。Bash などのルールやマッチャーを Code Mode 用に書き換える必要はありません。違いが出るのは権限モードごとの扱いです。
- auto モード: 分類器は、ツール呼び出しごとではなく、実行前にコード全体を審査します。検索結果から取り出したパスのような実行時に計算される値は見えないため、確実に制御したい呼び出しにはルールやフックを残しておきます。
- それ以外のモード: コードは審査なしで開始し、そのモードで確認が出るツール呼び出しごとに確認を求められます。
コード自体を検査したい場合は、Claude のコードを実行するツールである REPL にマッチする PreToolUse フックを書き、tool_input.code から JavaScript を読み取ります。また公式ドキュメントは、Bash のルールはコマンド文字列で照合するため、Code Mode の有無にかかわらずルールに一致しない形で拒否対象のコマンドが実行され得ること、コマンド文字列に依存しない制限にはサンドボックスを使うことも注意しています(サンドボックス環境の選び方)。
ビルドやテストのように時間のかかるコードは、次のどちらかで動きます。
| 動き方 | 内容 |
|---|---|
| 待機 | コードが終わってから Claude が応答する。権限確認に費やした時間も含めて10分で停止 |
| バックグラウンド | 実行中も Claude と会話でき、コードは最長2時間動ける |
バックグラウンドで動かすには、セッションを auto モードか bypassPermissions モードで開始します。それでも Claude が待つ場合は次を確認します。
- 途中で別のモードに切り替えた:
Shift+Tabで開始時のモードに戻す - 別のモードで開始した、または
claude --resumeの一覧から選んだ: auto モードが使えるなら、いったん終了し Code Mode をオンにしたままclaude --continue --permission-mode autoで起動し直す --toolsにツール名を渡した: そのフラグを外して auto モードで起動し直す
auto モードで、前のコードが動いている間に新しいコードが始まると、前のコードは分類器の審査を失い、残りの呼び出しのうち審査が必要なものについて利用者に確認が出ます。IDE が接続されていない場合は Claude Code will automatically block this request in 1:59, ... のようなカウントダウン付きで表示され、時間内に答えないとその呼び出しは拒否され、以後カウントダウンの出る呼び出しは確認なしで拒否されます。再び確認を表示させるには Claude にメッセージを送ります。
起動しないときの対処
セッション上部に Code Mode (experimental) isn't available と出た場合は、Code Mode なしで起動しています。同じ行(と /status)に理由が表示されるので、次の表に従って直し、新しいセッションを始めます。
| 理由に含まれる文言 | 対処 |
|---|---|
it isn't open to your account yet | v2.1.323 より古ければ更新。新しいのに出る場合はネットワーク接続を確認して再起動し、それでも出るなら日を改めて試す |
it only works with the Anthropic API | クラウドプロバイダ・ゲートウェイ・独自の ANTHROPIC_BASE_URL へ送る設定を外す |
it doesn't work with an API key helper | apiKeyHelper、ANTHROPIC_AUTH_TOKEN、ANTHROPIC_CUSTOM_HEADERS 内の Authorization・X-Api-Key を外し、サインインするか ANTHROPIC_API_KEY を設定する |
it only works with Opus 5.5, Sonnet 5.5 and later models | --model opus などで対応モデルを指定して起動する |
it doesn't work in background jobs | --remote-control なしでフォアグラウンドで起動する |
it needs settings that Claude Code downloads from Anthropic | 機能フラグの取得を止める変数(DISABLE_TELEMETRY など)を外す |
OpenTelemetry is on | CLAUDE_CODE_ENABLE_TELEMETRY と ENABLE_BETA_TRACING_DETAILED を外す |
it doesn't yet work with an installed mod | ツール呼び出しを検査する mod をオフにする |
it can't be used together with agent teams yet | CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS を外す(エージェントチームと併用不可) |
this launch's tool options | --restricted を外し、--tools に REPL を加え、--disallowedTools と deny ルールから REPL を外す |
couldn't save your answer | ~/.claude.json を書き込み可能にする |
your organization's settings don't allow it | 管理者にマネージド設定を確認する |
Code Mode に関する行がまったく出ない場合は、claude --version でバージョンを確認して必要なら更新し、シェルかユーザー設定で変数が 1 になっていること、そこや --settings ファイルに 0 が残っていないことを確かめます。
Claude がツール呼び出しの拒否を報告した場合は、エラー文を聞きます。the hook failed はフックが起動できない・強制終了された・終了コード 126、127、128超で終わった・HTTP エラーや不正な出力を返したことを、the hook did not finish はフックがタイムアウトしたことを示し、どちらも onFailure が未設定でも呼び出しは拒否されます。フックを直すかタイムアウトを延ばすか、失敗時も続行させたい command・http フックには "onFailure": "continue" を設定します。コードの出力が来るはずの場面でフックのブロック理由が返ってくる場合は、UserPromptSubmit フックが入力の source が poll_event のときにブロックしないよう変更します。
本記事は Claude Code 公式ドキュメント「Run tool calls from code with Code Mode」を元に、「Environment variables」の CLAUDE_CODE_EXPERIMENTAL_CODE_MODE の項で変数の意味を照合した非公式の日本語解説です(確認日 2026-11-15)。Code Mode は実験的機能のため仕様が変わる可能性があります。利用前に公式ドキュメントをご確認ください。