本文へスキップ
hdknr blog
戻る

Claude Code の Code Mode を試す — ツール呼び出しを JavaScript で束ねる実験的機能の使いどころと起動のコツ

はじめに

Claude Code に、ひっそりと Code Mode という実験的機能が追加されました。Oikon さんの X への投稿(以下「投稿」)で知った方も多いと思います。

普段の Claude Code は、Bash・Read・Edit といったツールを 1 回に 1 つずつ 呼び出し、結果を読んでから次の手を考えます。Code Mode を有効にすると、Claude は複数のツール呼び出しを JavaScript のプログラムとして書きます。そして、それを 1 ステップでまとめて実行 します。

この記事では、公式ドキュメントと投稿をもとに、Code Mode の仕組み、向いているタスク、有効化の手順、起動できないときの回避策、権限まわりの挙動と制約をまとめます。要点だけ先に書くと、有効化は CLAUDE_CODE_EXPERIMENTAL_CODE_MODE=1(v2.1.323 以降)で、起動しないときは --setting-sources project,local で切り分けられます。

用語の整理

用語意味
Code ModeClaude Code の実験的機能。Claude がツール呼び出しを JavaScript で書いてまとめて実行する。既定ではオフ
REPLCode Mode で Claude が書いたコードを実行するツールの名前。フックや権限ルールで指定するときに使う
CLAUDE_CODE_EXPERIMENTAL_CODE_MODECode Mode を有効(1)/無効(0)にする環境変数
Cloudflare の Code ModeMCP のツールを TypeScript の API に変換し、LLM にその API を呼ぶコードを書かせる手法。同じ発想の先行例

背景: 「ツールを呼ぶ代わりにコードを書かせる」発想

この考え方自体は新しいものではありません。Cloudflare が「Code Mode: the better way to use MCP」で MCP 向けに提案しており、投稿によれば Pi エージェントなども先駆けとして取り入れていたとのことです。筆者は、Claude Code の Code Mode をこの発想を Bash や Edit などの組み込みツールにまで広げたものと捉えています(公式ドキュメントがそう位置づけているわけではありません)。

Code Mode の仕組み

通常モードと Code Mode の処理の流れを比べると、次のようになります。

通常モードでは Claude が Bash・Read・Edit・Bash を 1 つずつ呼び出し、そのたびに全出力が文脈に戻ってくるため往復が 4 回発生する。Code Mode では Claude が JavaScript を 1 回 REPL ツールに送り、シェル実行・結果の加工・編集・テストをコード内で連続して行い、必要な部分だけを 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() });

$ でシェルコマンドを実行し、その結果をもとに edit() でファイルを書き換え、最後にテストを走らせています。最終行では、編集したファイル名とテスト結果だけをまとめています。図の例のように通常モードなら 4 往復ほどかかる処理が、1 回のコード実行で済みます(往復数は筆者の想定で、公式の数字ではありません)。

画面上では、コードそのものではなく個々のツール呼び出し(編集の差分など)が表示されます。コードを確認したいときは Ctrl+O でトランスクリプトビューアーを開くと、各スクリプトが折りたたまれた Code 行として表示されます。

Code Mode のメリットと使いどころ

投稿で挙げられていたメリットは次の 4 点です。

公式ドキュメントでも、多数のファイルにまたがる同じ変更、読む前に絞り込みたい検索結果、同時に走らせられる独立したコマンド群が使いどころとして挙げられています。

向いているタスク

投稿者の所感では、並列にできるステップが多いタスクほど効果が大きく、逐次的な作業ではあまり差が出ない とのことです。具体的に便利だったケースとして、次のものが挙げられていました。

向いていないタスク

投稿では、判断が必要で JavaScript のスクリプトに落とし込みにくいタスク は不向きとされています。筆者の補足ですが、途中の結果を見て方針を変えるような作業は、従来どおり 1 ツールずつ進めたほうが Claude の判断を挟めるはずです。

Code Mode の有効化手順(環境変数と settings.json)

1. バージョンを確認する

Code Mode には Claude Code v2.1.323 以降 が必要です。

# 現在のバージョンを確認
claude --version
# v2.1.323 未満なら更新
claude update

2. 環境変数を設定する

CLAUDE_CODE_EXPERIMENTAL_CODE_MODE を 1 にして起動します。

CLAUDE_CODE_EXPERIMENTAL_CODE_MODE=1 claude

毎回有効にしたい場合は、ユーザー設定 ~/.claude/settings.json の env に書きます。

{
  "env": {
    "CLAUDE_CODE_EXPERIMENTAL_CODE_MODE": "1"
  }
}

なお、プロジェクト設定やローカル設定(.claude/settings.json・.claude/settings.local.json)に書いたこの変数は無視されます。クローンしたリポジトリが勝手に Code Mode を有効にできないようにするためです。

3. 初回の確認に答える

初めて Code Mode で起動すると確認が表示されるので、Yes, turn on Code Mode を選びます。再起動後、次のメッセージが出れば有効になっています。

Code Mode (experimental) is on · this session can be resumed only with Code Mode on

無効にするには、変数を削除するか 0 を設定します。組織の管理設定(managed settings)で 0 を設定すれば、組織全体で Code Mode を禁止することもできます。

4. 試してみる

まず試すなら、公式ドキュメントが例に挙げている次のプロンプトがちょうどよい題材です(「このプロジェクトのすべての Markdown ファイルを読み、存在しないローカルファイルを指すリンクを一覧にして」という意味で、日本語で指示しても構いません)。

Read every Markdown file in this project and list the links that point to local files that don't exist.

全 Markdown ファイルを読み、リンク先の存在を確かめる処理は、ループとフィルターで書ける典型的な「束ねると速い」タスクです。

実際に試してみた結果

筆者の環境(Claude Code v2.1.326、CLAUDE_CODE_EXPERIMENTAL_CODE_MODE=1)で、このブログのリポジトリを相手に Code Mode を動かしてみました。

まず目につくのは、Claude が直接呼べるツールが REPL(コードの実行)と Poll(実行結果の受け取り)の 2 つだけになることです。Bash・Read・Edit などは、すべて JavaScript の中から関数として呼び出します。

試したこと結果
sleep 1 を 3 回実行順番に await すると約 3.2 秒、Promise.all で同時に走らせると約 1.1 秒
前述の「リンク切れの一覧」1,422 個の Markdown ファイルを読んでリンクを調べる処理が 1 回のコード実行で終わった(約 23 秒)。Claude に返ったのは絞り込んだ結果の 29 件だけ
変数の持ち越し前の実行で作った変数を、次の実行でそのまま使えた
実行環境process や fetch は存在せず、require は「the vm context is sealed」というエラーになる。外部とのやり取りは用意されたツール経由に限られる
コマンドの失敗終了コードが 0 以外だと例外になる。.nothrow() を付ければ例外にせず続行できる。grep で何も見つからなかった場合は例外にならない

1,422 ファイル分の中身は Claude の文脈に一切入っていません。通常モードなら Read を 1,000 回以上呼ぶ作業なので、「中間出力を LLM が読まなくてよい」というメリットを実感できました。なお、29 件の大半はコードブロック内の記法の例や説明用のサンプルパスで、本当のリンク切れではありませんでした。筆者が書いた簡易チェックがコードブロックを除外していなかったためです。

つまずいた点

Code Mode が起動しないときの回避策(—setting-sources)

投稿者がつまずいたのがここで、Code Mode は他の機能と競合して起動しにくい とのことです。公式ドキュメントでも、次のような条件では Code Mode なしで起動すると明記されています(一部抜粋)。

有効にならなかった場合は、起動時に次の行と理由が表示されます。/status でも確認できます。

Code Mode (experimental) isn't available

投稿者は、読み込む設定ファイルを絞る ことでこれを回避していました。

CLAUDE_CODE_EXPERIMENTAL_CODE_MODE=1 claude --setting-sources project,local

--setting-sources project,local を付けると、ユーザー設定(~/.claude/settings.json)が読み込まれなくなります。競合の原因になる設定がユーザー設定側にあるなら、これで一時的に外せるというわけです(どこに書かれているかは環境によるので、まずは /status で理由を確かめてください)。

なお、前述のとおりプロジェクト設定やローカル設定ではこの変数が無視されます。そのため、環境変数はこの例のようにシェルから渡してください。

Code Mode での権限ルールと PreToolUse フック

Code Mode でも安全装置は残っています。

Code Mode の制約(-p・VS Code・Bedrock では使えない)

実験的機能なので、制約も多めです。

まとめ

ベンチマークの比較や大規模な横断調査など、「ツールを何十回も呼ぶ」作業が多い方は一度試してみる価値があります。

参考



前の記事
コーネル式ノートの書き方と使い方 — 3 分割ページと 5R サイクルで「書いて終わり」をなくす
次の記事
Claude Code の /autocompact 設定 — 1M コンテキストの自動圧縮を 400K に早めるコストと品質の得失