はじめに
Claude Code 2.1.323 の CHANGELOG に、Code Mode という実験機能が加わりました。Claude が JavaScript を書き、1 回のコード実行で複数のツール呼び出しをまとめて行う仕組みです。公式ドキュメントは、既定でオフで、将来のリリースで変更や削除があり得ると明記しています。
この記事は、Claude Code を日常的に使っている日本の開発者向けです。公式ドキュメントと CHANGELOG をもとに、何ができるか、どう有効化するか、どこで使えないか、権限まわりで何を残すべきかを整理します。
この記事で解決できること
- Code Mode が従来のツール呼び出しと何が違うかを把握できます
- 有効化と無効化の手順、組織で禁止する方法がわかります
- 自分の環境で動くかどうかを、要件の一覧から判断できます
- auto モードで統制を失わないために、ルールとフックで何を残すかがわかります
前提条件と調べた範囲
- 調べたのは 2026-11-14 JST 時点の公式ドキュメント（code-mode、hooks、setup、env-vars、settings-reference）と、Claude Code の CHANGELOG、npm レジストリの記録です
- 公式ドキュメントの記述に加えて、2026-11-15 JST に Claude Code 2.1.325 で実機検証しました。結果は「実機検証」の節にまとめています。有効になる条件と無効になる条件の切り分けと、有効時のツール一覧の変化、3 ファイルの並列読み取りまでは確認しました。コスト削減効果、カスタム
ANTHROPIC_BASE_URL、apiKeyHelper、OpenTelemetry、--restrictedの挙動は確認していません - 実機検証の節以外の動作の記述は、公式ドキュメントに基づく二次情報です
- Cloudflare が提唱した同名の Code Mode は別の仕組みです。違いは後半の 1 節で整理します
TL;DR
- Code Mode は、Claude が JavaScript を書いて Claude Code が実行し、その中で複数のツール呼び出しをまとめて行う実験機能です。有効化は環境変数
CLAUDE_CODE_EXPERIMENTAL_CODE_MODE=1です - 対話の
claude（ターミナル）でしか使えません。-p、Agent SDK、VS Code、Desktop、クラウドセッション、Bedrock などのクラウド経由、agent teams や OpenTelemetry との併用は不可です - ルールとフックは Code Mode でも各ツール呼び出しに効きます。ただし auto モードの分類器が見るのはコード全体で、実行時に決まる値は見えません。統制したい呼び出しにはルールかフックを残します
- 実機検証では、
-pでは有効にならず、対話のclaudeでもクラウドセッション由来の環境変数が残っていると無効でした。agent teams の環境変数があるときも専用のメッセージで無効になりました。詳しくは「実機検証」の節にあります - 本稿執筆時点の npm では、latest は 2.1.325 で、stable は 2.1.311 のままです。stable チャネルの利用者は、そのままでは使えません
Code Mode とは何か
通常の Claude Code は、Bash、Read、Edit といったツール呼び出しを 1 つずつ要求し、結果を読んでから次の手を決めます。Code Mode では、Claude が JavaScript を書き、Claude Code がそれをセッション内で実行します。1 つのコードの中で、コマンドの並列実行、前の結果を次の呼び出しに使う処理、必要な部分だけを Claude に返す処理を行えます。
公式ドキュメントの例は、リトライ上限を引き上げる依頼です。ファイルを探し、編集し、テストを走らせるところまでを 1 つのコードで書いています。
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() });
$ に続くバッククォートでコマンドを実行し、edit() でファイルを編集しています。最後の式の値が、ファイルのパスとテスト出力として Claude に返ります。会話画面に見えるのは編集の差分などのツール呼び出しで、コードそのものは出ません。コードを読むには Ctrl+O でトランスクリプトビューを開き、折りたたまれた Code 行を展開します。
通常の流れとの違いは、結果を逐一 Claude が読んで次を決めるのではなく、判断の一部をコードに寄せている点です。途中経過が Claude の文脈に積まれにくくなる一方、会話画面から見える情報は減ります。
向いている用途
公式ドキュメントが挙げる用途は 3 つです。
| 用途 | 例 |
|---|---|
| 多数のファイルに同じ変更を繰り返す | 設定値の一括置換 |
| 読む前にフィルタが要る検索 | 検索結果を絞ってから読む |
| 同時に走らせられる独立したコマンド | 複数のテストの並列実行 |
逆に、1 回か 2 回のツール呼び出しで終わる作業では、Code Mode にする利点は公式からは読み取れません。
有効化の手順
1. バージョンを確認する
claude --version で 2.1.323 以上かを確認し、古ければ claude update を実行します。2.1.323 が npm に公開されたのは、レジストリの記録では 2026-11-13 05:29 JST です。
npm view @anthropic-ai/claude-code dist-tags
npm view @anthropic-ai/claude-code time --json | grep -E '"2\.1\.32[3-5]"'
2026-11-14 10:38 JST に取得した結果は次のとおりです。
{ stable: '2.1.311', latest: '2.1.325', next: '2.1.325' }
"2.1.323": "2026-11-12T20:29:28.626Z",
"2.1.324": "2026-11-13T18:42:36.300Z",
"2.1.325": "2026-11-13T20:07:25.823Z"
時刻は UTC なので、JST にするには 9 時間足します。stable チャネルは「約 1 週間遅れで、大きな不具合のあるリリースを飛ばす」と公式の setup ページに書かれています。stable のまま更新しても 2.1.323 に届かない間は、公式ドキュメントの案内どおり stable が追いつくのを待つか、latest チャネルに切り替えます。
2. 環境変数を 1 にして起動する
CLAUDE_CODE_EXPERIMENTAL_CODE_MODE を 1 にします。試すだけならシェルで、常用するなら ~/.claude/settings.json の env に書きます。
CLAUDE_CODE_EXPERIMENTAL_CODE_MODE=1 claude
{
"env": {
"CLAUDE_CODE_EXPERIMENTAL_CODE_MODE": "1"
}
}
Windows の PowerShell では $env:CLAUDE_CODE_EXPERIMENTAL_CODE_MODE = "1" を設定してから claude を起動します。
この変数が有効になる場所には制限があります。公式の settings リファレンスによれば、有効にできるのはシェル、ユーザー設定、--settings で渡すファイルの 3 つで、managed、プロジェクト、ローカルの設定ファイルでは効きません。リポジトリを clone しただけで 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. 試すプロンプトを送り、コードを読む
公式ドキュメントが挙げる試し方は、多数のファイルを読む作業です。
Read every Markdown file in this project and list the links that point to local files that don't exist.
実行後に Ctrl+O を押して Code 行を展開すると、Claude が書いた JavaScript が読めます。もう一度 Ctrl+O で会話画面に戻ります。
無効化と組織での禁止
個人で切るには、シェルとユーザー設定から変数を消して新しいセッションを始めます。値を 0 にする方法もあり、どこか 1 か所でも 0 があれば、別の場所が 1 でも Code Mode は有効になりません。
組織で禁止するときは、managed settings の env に値 0 で入れます。
{
"env": {
"CLAUDE_CODE_EXPERIMENTAL_CODE_MODE": "0"
}
}
managed settings で有効化を強制することはできません。managed settings に 1 が入っている場合でも、利用者は自分のユーザー設定に 1 を書く必要があり、シェルの 1 は無視されます。
使えない条件を先に確認する
要件は多く、満たさないと Code Mode なしで起動します。
| 項目 | 条件 |
|---|---|
| バージョン | Claude Code 2.1.323 以降（リリースチャネルは問わないとドキュメントにありますが、stable は未到達） |
| アカウント | Claude のサブスクリプションか Console アカウント。ゲートウェイ、Amazon Bedrock、Google Cloud、Microsoft Foundry 経由は不可 |
| 組織 | HIPAA 構成とゼロデータ保持のどちらも使っていないこと |
| モデル | Claude Opus 5.5、Sonnet 5.5、Haiku 5.5、Fable 5.2 |
| 実行面 | ターミナルの対話 claude のみ。-p、Agent SDK、VS Code パネル、Desktop アプリ、クラウドセッションは不可 |
| インストール | ネイティブビルド |
| Windows | Git for Windows が必要 |
さらに、API キーヘルパー、agent teams、OpenTelemetry のエクスポート、DISABLE_TELEMETRY といった設定が有効だと起動できません。Code Mode のセッションでは次の機能も使えません。
- Remote Control、Claude in Chrome、computer use
- セッションの Desktop アプリへの移動とバックグラウンドセッション化（
/forkでのバックグラウンドコピーを含む）
起動しないときの原因
Code Mode が起動しないと、画面上部に Code Mode (experimental) isn't available と理由が出ます。/status でも確認できます。公式の対応表から、よくあるものを抜き出します。
| 理由に含まれる文言 | 対処 |
|---|---|
it isn't open to your account yet |
2.1.323 より古ければ更新。そうでなければ通信を確認して再起動。それでも出れば日を改めて試す |
it only works with the Anthropic API |
クラウドプロバイダ、ゲートウェイ、独自の ANTHROPIC_BASE_URL の設定を外す |
it doesn't work with an API key helper |
apiKeyHelper などを外し、ログインか ANTHROPIC_API_KEY を使う |
OpenTelemetry is on |
CLAUDE_CODE_ENABLE_TELEMETRY などを外す |
it can't be used together with agent teams yet |
CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS を外す |
this launch's tool options |
--restricted を外し、REPL を --tools に加え、--disallowedTools と deny ルールから外す |
運用の面で効くのは、既存のトークンやテレメトリ設定との衝突です。チームで共通の設定を配っている場合は、Code Mode を試す前に衝突する項目がないかを確認する必要があります。
セッションの再開に条件がある
Code Mode で始めたセッションは、Code Mode をオンにしたときだけ再開できます。claude --continue や claude --resume を実行するときも、CLAUDE_CODE_EXPERIMENTAL_CODE_MODE を 1 にしておく必要があります。オフだと Claude Code は再開を拒否します。逆に、Code Mode なしで始めたセッションは、変数が 1 でも Code Mode なしで再開されます。
権限とフックは何が効くのか
ここが運用上いちばん大事な部分です。
Code Mode で Claude のコードが行う個々のツール呼び出しは、これまでどおり deny と ask の権限ルール、および PreToolUse フックを通ります。Bash 用のルールやマッチャーを変える必要はありません。そのうえでモードごとに次の扱いになります。
| 権限モード | コード実行前の扱い |
|---|---|
| auto モード | 分類器が、ツール呼び出し単位ではなくコードを実行前に審査する。検索結果から取ったパスのような、実行時に決まる値は見えない |
| それ以外のモード | コードは審査なしで始まり、そのモードで確認が出る呼び出しごとに確認が出る |
公式ドキュメントは、auto モードで統制したい呼び出しには、ルールかフックを残すよう案内しています。コード全体を事前に見る分類器は、実行時に決まる引数までは判断できないためです。
コードそのものを検査したい場合は、REPL（Claude のコードを実行する内部ツール）に一致する PreToolUse フックを書き、JavaScript を tool_input.code から読みます。設定の形は次のようになります。スクリプトの中身は各自の方針に合わせて書く部分で、この例は動作を確認していません。
{
"hooks": {
"PreToolUse": [
{
"matcher": "REPL",
"hooks": [
{
"type": "command",
"command": "${CLAUDE_PROJECT_DIR}/.claude/hooks/check-repl-code.sh"
}
]
}
]
}
}
なお、公式ドキュメントは別の注意も添えています。Bash のルールはコマンドの文字列に一致するため、Code Mode の有無にかかわらず、拒否したコマンドがルールに一致しない形で実行される可能性があります。文字列に依存しない制限が要るなら、サンドボックスを使います。
フックが失敗したときの挙動が変わる
Code Mode では、PreToolUse フックが判断を返せないとき、ツール呼び出しは拒否されます。onFailure を設定していなくても同じです。公式ドキュメントが挙げるエラーは 2 つです。
-
the hook failed: フックが起動できない、強制終了された、終了コード 126、127、128 超で終わった、HTTP エラーや不正な出力を返した場合。フックを直します -
the hook did not finish: Claude のコードからの呼び出しでタイムアウトした場合。セッション内でコードが一度でも動いた後は、ほかのツール呼び出しでも同様です。フックのtimeoutを延ばします
失敗時に呼び出しを通したい場合は、command か http のフックに "onFailure": "continue" を付けます。通常の Claude Code でフックがタイムアウトしても呼び出しは止まらないので、Code Mode ではフックの堅牢性が一段厳しく問われます。
UserPromptSubmit フックにも注意が必要です。コードがバックグラウンドで動く場合、command、http、mcp_tool のフックがコードの出力に対しても走ります。出力を通したいときは、フックの入力で source が poll_event の場合にブロックしないようにします。
長く動くコードの扱い
コードが長いビルドやテストを走らせるとき、Claude は終わるのを待つか、バックグラウンドで続けさせます。
- 待つ場合: コードが終わってから Claude が答えます。コードは 10 分で止まります。権限の確認に使った時間も含みます
- バックグラウンドの場合: 会話を続けられ、コードは最長 2 時間動きます
バックグラウンド実行にしたいときは、セッションを auto モードか bypassPermissions で始めます。それでも Claude が待つ場合は、現在のモードと起動のしかたを見直します。途中で別のモードに切り替えたなら Shift+Tab で元に戻し、別のモードで始めた場合は claude --continue --permission-mode auto を Code Mode オンで実行します。--tools にツール名を渡している場合は、そのフラグを外して auto モードで始め直します。
auto モードでは、前のコードが動いている最中に新しいコードが始まると、前のコードは分類器の審査を失います。そのとき残りの呼び出しについて確認が出ます。IDE が接続されていないと、次のようなカウントダウンが出ます。
Claude Code will automatically block this request in 1:59, to avoid holding up an unattended session
カウントが尽きる前に答えないと、その呼び出しは拒否され、以降カウントダウンが出る呼び出しは確認なしで拒否されます。確認を再び出すには Claude にメッセージを送ります。
実機検証（v2.1.325・2026-11-15 JST）
公式ドキュメントの要件が実際の挙動と合うかを、Claude Code 2.1.325 で確認しました。環境は Linux のクラウドセッション内のサンドボックスで、対話モードの確認には tmux で作った疑似端末を使いました。認証情報やセッション ID の値は記事に載せていません。
結果の一覧
CLAUDE_CODE_EXPERIMENTAL_CODE_MODE=1 を付けて起動し、ツール一覧と起動バナーを確認しました。
| 条件 | Code Mode |
|---|---|
-p（クラウド判定の環境変数がある状態） |
無効。ツール一覧は環境変数なしと同じ 39 ツールで、REPL なし |
-p（クラウド判定の環境変数を外した状態） |
無効。REPL も Poll も出ない |
対話 claude（クラウド判定の環境変数がある状態） |
無効 |
対話 claude（クラウド判定の環境変数を外した状態） |
有効。初回に確認が出て、Yes で REPL と Poll が加わる |
| 上のどれかに agent teams の環境変数を足した状態 | 無効 |
-p が無効なのは、公式ドキュメントの「ターミナルの対話 claude のみ」と一致します。
有効になった画面
対話モードで条件を満たすと、初回に確認画面が出ました。選択肢は No, start without it と Yes, turn on Code Mode で、説明文には次の趣旨が書かれています。
Code Mode (experimental)
In Code Mode, Claude works by writing and running JavaScript that calls its tools, instead of calling them one at a time.
This is an early experiment. It can behave differently from normal Claude Code, and it may change or be removed in any release.
A session that you start in Code Mode can be resumed only with Code Mode on. ...
Yes を選ぶと、起動バナーに次の行が出ました。
⚠ Code Mode (experimental) is on · this session can be resumed only with Code Mode on
「使えるツールを列挙して」と尋ねると、先頭に REPL と Poll が並びました。無効のときの一覧には REPL、Poll、Glob、Grep が出ず、Bash、Read、Edit、Write などが並びます。
REPL, Poll, Agent, Artifact, ArtifactComments, ArtifactData, AskUserQuestion, CronCreate, ... Write,
mcp__easel__chart, Read, Glob, Grep, Bash, NotebookEdit
3 ファイルの行数を数えさせた結果
10 行、20 行、30 行のファイルを 3 つ用意し、行数を数えるよう頼みました。トランスクリプトでは、Claude が JavaScript を 1 回書き、Promise.all で 3 ファイルを並列に読んでいました。
TOOL_USE REPL {"code": "const names = ['f1.txt','f2.txt','f3.txt'];
const out = await Promise.all(names.map(async n => { ... await file(n).text() ... }));
out", "description": "Read three files and count lines"}
TOOL_USE Poll {}
... <event kind="repl-eval" eval="2" ms="86" status="settled"> ...
画面には Read 3 files と表示され、回答は「f1.txt が 10 行、f2.txt が 20 行、f3.txt が 30 行」でした。REPL の中から Read ツールが 3 回呼ばれており、個々のツール呼び出しは従来どおりツールごとの経路を通ります。
無効になる条件の切り分け
対話モードで無効になったときは、起動バナーに isn't available と理由が出ました。公式の対応表にある it only works in the interactive terminal と、it can't be used together with agent teams yet の 2 つを確認できました。クラウドセッション由来の環境変数を 1 つずつ外して試した結果は次のとおりです。
| 条件 | 結果 |
|---|---|
親環境そのまま（CLAUDE_CODE_REMOTE=true と CLAUDE_CODE_ENTRYPOINT=remote_projects） |
for now it only works in the interactive terminal で無効 |
CLAUDE_CODE_ENTRYPOINT だけ除去 |
無効 |
CLAUDE_CODE_REMOTE だけ除去 |
無効 |
CLAUDE_CODE_ENTRYPOINT=cli に置換（CLAUDE_CODE_REMOTE は true のまま） |
無効 |
CLAUDE_CODE_ENTRYPOINT を除去し CLAUDE_CODE_REMOTE=false
|
有効 |
| 両方を除去 | 有効 |
有効な状態にプロジェクト設定 env の CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 を足す |
it can't be used together with agent teams yet で無効 |
有効な状態にシェルの CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 を足す |
無効 |
読み取れることは 3 点です。
- クラウドセッションが付ける
CLAUDE_CODE_REMOTE=true、またはターミナル以外を示すCLAUDE_CODE_ENTRYPOINT（今回はremote_projects）のどちらか一方があるだけで、Code Mode は止まりました。公式ドキュメントが「クラウドセッションは不可」と書いている挙動の判定条件にあたると考えられます - agent teams の環境変数は、設定ファイルの
envに書いてもシェルで渡しても Code Mode を止めます - 切り分けのために環境変数を外したのは、条件を調べるための操作です。クラウドセッションで Code Mode を使う手段として勧めるものではありません
agent teams を設定ファイルで有効にしているリポジトリでは、同じ環境で起動すると Code Mode が止まる見込みです。ただし、今回はそのリポジトリ自体では起動しておらず、再現は未確認です。
未検証の項目
次の項目は今回確認していません。公式ドキュメントの記述のみが根拠です。
- カスタム
ANTHROPIC_BASE_URLのときの挙動（検証環境の接続先が api.anthropic.com のため再現できませんでした） -
apiKeyHelper、OpenTelemetry、DISABLE_TELEMETRY、--restricted、Amazon Bedrock との非互換 - トークンやコストの削減効果（小さな作業を 1 回試しただけで、測っていません）
同名の Cloudflare の Code Mode との違い
Code Mode という名前は、Cloudflare が提唱した手法にもあります。以前の記事「Code Mode入門 — MCPツール定義を1,000トークンに圧縮するCloudflareの新手法」で扱ったものです。
| Cloudflare の Code Mode | Claude Code の Code Mode | |
|---|---|---|
| 目的 | 大量の MCP ツール定義でコンテキストが埋まるのを避ける | 多数のツール呼び出しを 1 回のコード実行にまとめる |
| コードの書き手 | LLM | Claude |
| 実行場所 | V8 サンドボックス | Claude Code のセッション内（内部ツール名 REPL） |
| 位置づけ | MCP 向けの設計パターンと SDK | Claude Code の実験機能（環境変数で有効化） |
どちらも「LLM にツールを直接呼ばせず、コードを書かせる」という発想は共通です。ただし、解く問題と実装は別物で、片方の記事の設定や挙動がもう片方に当てはまるわけではありません。公式ドキュメントも、Claude Code の Code Mode が MCP ツール定義のトークン節約を目的にしているとは書いていません。
2.1.325 で入った Code Mode の修正
実験機能の安定度を測るうえで、導入直後の修正が参考になります。2.1.323 の公開から 1 日ほどで公開された 2.1.325 の CHANGELOG には、Code Mode 関連の修正が 3 件あります。
- Code Mode のスクリプトが
EnterWorktreeで入った worktree を無視する、~のパスをプロジェクト内に書く、サインインが切れた MCP サーバーを/mcpが接続中と表示する、という不具合の修正 - 権限ダイアログやプラン承認で Yes と一緒に入力した言葉が、Code Mode で Claude に届かない不具合の修正
- Code Mode のスクリプト実行中に終了したセッションを再開すると、Claude が自分で作業を始めてしまう不具合の修正（次の入力を待つようになった）
worktree やパスの扱いに関する修正が入っていることから、導入直後の版では、worktree 運用やホームディレクトリ以下のパスを使う作業で挙動の差が出た可能性があります。使う場合は 2.1.325 以降にそろえるのが無難です。
導入の判断のしかた
公式ドキュメントから読み取れる範囲での、判断の目安です。
- 試す価値が高いのは、手元の端末で対話的に使う、ファイルをまたぐ繰り返し作業です。要件の表を満たす環境なら、環境変数を 1 つ足すだけで切り替えられ、戻すのも簡単です
- agent teams を使っている環境では、実機でも Code Mode が止まりました。Code Mode を試すセッションでは
CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMSを外します - 見送るのが自然なのは、
-pや Agent SDK で自動化している用途、VS Code や Desktop を主に使う場合、Bedrock や Vertex 経由で使っている場合です。いずれも対象外です - 組織で使う場合は、まず managed settings の扱いを決めます。禁止するなら値
0、許可するなら個人のユーザー設定で各自が有効化する形になり、一括の強制有効化はできません - auto モードと組み合わせるなら、拒否したい操作の
denyルールとPreToolUseフックを先に整えます。分類器は実行時の値を見ないため、ルールとフックが最後の砦になります - すでに
PreToolUseフックを運用しているなら、失敗やタイムアウトで呼び出しが拒否される挙動を前提に、timeoutとonFailureを見直します
まとめ
Code Mode は、Claude が JavaScript を書いて複数のツール呼び出しを 1 回のコード実行にまとめる、Claude Code の実験的な機能です。有効化は CLAUDE_CODE_EXPERIMENTAL_CODE_MODE=1 で、プロジェクト設定では効かず、組織は 0 で禁止できます。
使える環境は限られます。対話のターミナル、ネイティブビルド、Anthropic の API 直結、対応モデル、そして 2.1.323 以降が条件で、2026-11-14 JST 時点の stable チャネルにはまだ届いていません。安全面では、個々のツール呼び出しにルールとフックが効く一方、auto モードの分類器は実行時の値を見られないため、統制したい操作にはルールとフックを残します。
実機検証では、対話の claude で条件を満たすと REPL と Poll が加わり、3 ファイルの読み取りが 1 回のコード実行で並列に行われました。一方、-p、クラウドセッション由来の環境変数、agent teams の環境変数のいずれかがあると無効でした。コスト削減効果は測っていません。
実験機能なので、仕様は変わり得ます。導入前に公式ドキュメントの最新版で要件の表を確認してください。
関連記事
- Code Mode入門 — MCPツール定義を1,000トークンに圧縮するCloudflareの新手法
- Claude Code auto modeを安全に回す — 破壊的コマンドを止める3層防御
- Claude Code Auto Mode入門 — 安全な自律コーディングを実現する権限制御の全貌