ツールを1回ずつ呼ばせる代わりに Claude に JavaScript を書かせると、トークンはどれだけ減るのか。Claude Code v2.1.323 で入った実験機能 Code Mode を、公式ドキュメントの例と同じ作業でオンとオフ3回ずつ回しました。入力トークンの合計はオンが 39,121〜39,517、オフが 99,045〜99,083 です。
Claude Code Code Modeはツール呼び出しをJavaScriptにまとめる
公式ドキュメントの説明
Code Mode がオフのとき、Claude は Bash・Read・Edit などのツールを1回ずつ呼び、結果を読んでから次の手を決めます。オンにすると、Claude はツール呼び出しを含む JavaScript を書き、Claude Code がそのコードをセッションの中で実行します。公式ドキュメントの “How Code Mode works” には次の一文があります。
One piece of code can run commands in parallel, use one result in the next call, and return the part of the output that Claude needs to read.
会話の画面に出るのはツール呼び出しの要約で、コード本体は出ません。コードを読むには Ctrl+O で transcript viewer を開き、Code の行を展開します。
向いている作業と使える条件
“When to use Code Mode” は、多くのファイルに同じ変更を入れる作業、Claude が読む前に絞り込みが要る検索、同時に走らせてよい独立したコマンドを挙げています。使える条件は次のとおりです。
- Claude Code v2.1.323 以降の native build
- Claude のサブスクリプションか Console アカウント。gateway・Amazon Bedrock・Microsoft Foundry などを通すと使えない
- モデルは Opus 5.5・Sonnet 5.5・Haiku 5.5・Fable 5.2
- ターミナルで動かす対話の
claudeだけ。-p・Agent SDK・VS Code のパネル・Desktop アプリ・クラウドセッションでは使えない
既定はオフで、ドキュメントには “It may change or be removed in any release.” とあります。
CLAUDE_CODE_EXPERIMENTAL_CODE_MODEの置き場所
シェルで1を渡して起動する
CLAUDE_CODE_EXPERIMENTAL_CODE_MODE=1 claude
初回は確認画面が出て、選択肢は No, start without it と Yes, turn on Code Mode の2つです。Yes を選ぶと Claude Code が再起動し、起動画面に次の行が出ました。
⚠ Code Mode (experimental) is on · this session can be resumed only with Code Mode on
Claude Code はこの答えを .claude.json(既定の場所は ~/.claude.json)に codeModeCaveatsAcceptedV1 と codeModeAutoModeCaveatAcceptedV1 を true にして保存し、2回目からは確認を出しません。/status の Code Mode の行には、どこで有効にしたかも出ます。
Code Mode: on (experimental) · CLAUDE_CODE_EXPERIMENTAL_CODE_MODE in the shell environment
プロジェクトの.claude/settings.jsonでは有効にならない
チームで揃えるつもりで、リポジトリの .claude/settings.json に書いた場合です。
{
"env": {
"CLAUDE_CODE_EXPERIMENTAL_CODE_MODE": "1"
}
}
この状態で起動すると、Code Mode のバナーは出ず、/status からも Code Mode の行ごと消えました。Setting sources には Shared project settings と出るので、Claude Code は設定ファイル自体を読んでいます。同じ env を ~/.claude/settings.json に移すと有効になり、/status の出どころが変わりました。
Code Mode: on (experimental) · CLAUDE_CODE_EXPERIMENTAL_CODE_MODE in user settings
settings reference の “Variables Claude Code ignores in env” に理由があります。
You can turn on Code Mode with
CLAUDE_CODE_EXPERIMENTAL_CODE_MODEfrom your shell, user settings, or a--settingsfile, and not from managed, project, or local settings.
Code Mode のページは、clone したリポジトリが勝手に Code Mode をオンにできないようにするためだと説明しています。
置き場所ごとの1と0の扱い
| 置き場所 | 1 を書いたとき | 0 を書いたとき |
|---|---|---|
| シェルの環境変数 | 有効(実測) | ほかに 1 があってもオフ |
~/.claude/settings.json | 有効(実測) | シェルの 1 に勝ってオフ(実測) |
--settings で渡すファイル | 有効 | ほかに 1 があってもオフ |
| プロジェクト・ローカル設定 | 無視(実測) | ドキュメントに記載なし |
| managed settings | 単独では有効にならない。ユーザー設定の 1 が要る | 組織全体でオフ |
シェルで 1、ユーザー設定で 0 にして起動すると、バナーも /status の行も出ないままオフでした。理由が画面に出るのは、OpenTelemetry が有効なときのように条件を満たさなかった場合だけです。
同じ作業でオンとオフを3回ずつ比べた
計測の条件
Claude Code v2.1.325、--model sonnet(Sonnet 5.5)、--effort medium、--permission-mode default で揃えました。対象は Markdown 12本のプロジェクトで、存在しないファイルを指すリンクを 9本入れてあります。プロンプトは “Try Code Mode” の手順4にある例文をそのまま使いました。
Read every Markdown file in this project and list the links that point to local files that don’t exist.
設定ディレクトリは CLAUDE_CONFIG_DIR で普段のものと分け、Bash(find *) や Bash(test *) などの読み取り系コマンドを allow に入れました。トークンは transcript の jsonl にある usage を message.id ごとに1回だけ足しています。同じ id の行が content ブロックの数だけ並ぶので、行ごとに足すと多く出ます。
結果
| 項目 | オン | オフ |
|---|---|---|
| API リクエスト | 2回 | 3回 |
| 1回目のリクエストの入力 | 19,079〜19,082 | 32,530〜32,533 |
| 入力トークン合計 | 39,121〜39,517 | 99,045〜99,083 |
| 出力トークン合計 | 983〜1,023 | 1,426〜1,517 |
| 送信から回答まで | 8.5〜9.3秒 | 12.4〜12.9秒 |
| 見つけた壊れたリンク | 9/9 | 9/9 |
リクエスト回数は3回とも同じで、トークンの幅も約1%に収まりました。オフでも Claude は1回目で Markdown を find で集め、2回目で Python のスクリプトを書いて、Bash 1回で全リンクを確かめています。往復の差は1回だけです。
オフの3回はスクリプトを実行する前に権限の確認が1回ずつ出て、検証用のドライバが1秒以内に Yes を返しました。時間の差にはこの分も入っています。
差の約6万トークンはツール定義と往復1回分
transcript には api-request-shape という行があり、API に送った system と tools がそのまま残っています。数えるスクリプトです。
import json, sys
for line in open(sys.argv[1]):
d = json.loads(line)
if d.get("type") == "api-request-shape":
tools = d["shape"]["tools"]
system = sum(len(b.get("text", "")) for b in d["shape"]["system"])
print(f"system {system}文字 / tools {len(tools)}本 {len(json.dumps(tools))}バイト")
print([t["name"] for t in tools])
break
オンとオフの1回目の jsonl に流した結果です。
$ python3 tools_in_request.py on1.jsonl
system 8771文字 / tools 1本 30792バイト
['REPL']
$ python3 tools_in_request.py off1.jsonl
system 8723文字 / tools 15本 73315バイト
['Agent', 'Artifact', 'AskUserQuestion', 'Bash', 'Edit', 'ListAgents', 'Read', 'ReportFindings', 'ScheduleWakeup', 'SendFeedback', 'Skill', 'ToolSearch', 'Workflow', 'DeferredToolPlaceholder', 'Write']
system は 8,771文字と 8,723文字でほぼ同じです。違うのはツールの欄で、オンは REPL の1本だけでした。シェルとファイル操作は REPL の説明の中に $・file・edit などの関数として書かれ、Read や Agent などのツールも型定義の形で載っています。ツール定義は 73,315バイトから 30,792バイトに縮み、1回目のリクエストは約 13,450トークン小さくなりました。
2回目どうし(on2 と off2)で差の 59,962トークンを分けると、26,171 が1〜2回目のリクエストの大きさの差、33,791 がオフにだけある3回目のリクエストでした。
ただ、オフの 99,083 のうち 93,109 はキャッシュ読み取りです。”How Claude Code uses prompt caching” のページは、キャッシュから読み直した分を “cached token rate” で課金すると書いているので、料金の差はトークン数の差ほど開きません。同じページはツール定義を system prompt の層に置いていて、ツール定義の組み合わせが変わるとキャッシュが無効になると書いています。オンとオフはツール定義が違うので、キャッシュも別々です。今回いちばん最初に送ったオンのリクエスト(on1 の1回目)は、キャッシュ読み取り 0、書き込み 19,077 でした。
PreToolUseフックにはコード内の呼び出しも1件ずつ届く
REPLにマッチさせるとコード全体を読める
“Permission checks” は、コード自体を検査する方法を次のように書いています。
To check the code itself, write a
PreToolUsehook that matchesREPL, the tool that runs Claude’s code, and read the JavaScript fromtool_input.code.
計測では matcher を * にした PreToolUse フックを置き、届いた入力をすべて jsonl に書き出しました。
{
"hooks": {
"PreToolUse": [
{"matcher": "*", "hooks": [{"type": "command", "command": "python3 /tmp/cm-tools/hooklog.py"}]}
]
}
}
import json, os, sys, time
d = json.load(sys.stdin)
d["_logged_at"] = time.time()
with open(os.environ.get("CM_HOOK_LOG", "/tmp/cm-tools/hooks.jsonl"), "a") as f:
f.write(json.dumps(d, ensure_ascii=False) + "\n")
たまったログを、ツール名と tool_use_id の先頭部分で数えます。
import collections, json, sys
rows = [json.loads(l) for l in open(sys.argv[1])]
print(dict(collections.Counter(r["tool_name"] for r in rows)))
print(dict(collections.Counter(r["tool_use_id"].split("_")[0] for r in rows)))
print("先頭から末尾まで", round(rows[-1]["_logged_at"] - rows[0]["_logged_at"], 2), "秒")
$ python3 hook_summary.py hooks-on2.jsonl
{'REPL': 1, 'Bash': 31, 'Read': 12}
{'toolu': 1, 'repl': 43}
先頭から末尾まで 1.12 秒
$ python3 hook_summary.py hooks-off2.jsonl
{'Bash': 2}
{'toolu': 2}
先頭から末尾まで 5.76 秒
1回のコードで44回呼ばれた
オンの2回目では PreToolUse が 44回呼ばれました。REPL が1回、コードの中の $`...` が Bash として31回、file(f).text() が Read として12回です。中の呼び出しの tool_use_id は toolu_ ではなく repl_ で始まるので、フックの側で見分けられます。オフは Bash の2回だけで、5.76秒はその2回のあいだにモデルの応答待ちが挟まった時間です。画面のほうは Searched for 1 pattern, read 12 files, ran 30 shell commands の1行にまとまっていました。
呼び出しのたびに Slack へ通知するフックや外部 API に問い合わせるフックだと、今回の作業では受け取る件数がオフの22倍になります。”Tool call refused by a hook” によると、コードから来た呼び出しでフックが起動できなかったりタイムアウトしたりすると、onFailure を設定していなくても Claude Code はその呼び出しを拒否します。タイムアウトで拒否されたときのエラー文は the hook did not finish で、ドキュメントはフックの timeout を上げるよう案内しています。
生成コードの無駄がフックのログに出た
オンの1回目だけ Bash が 61回で、2回目・3回目の31回のほぼ倍でした。フックのログに残った tool_input.code を開くと、リンクを確かめるループの頭に何もしない行が入っています。
for(const x of fs){ if(!(await $`test -e ${x.full}`.nothrow()).exitCode===0) {}
const r=await $`test -e ${x.full}`.nothrow(); if(r.exitCode!==0) out.push(`${x.f}:${x.line} -> ${x.l}`);}
$ python3 hook_summary.py hooks-on1.jsonl
{'REPL': 1, 'Bash': 61, 'Read': 12}
{'toolu': 1, 'repl': 73}
先頭から末尾まで 2.0 秒
1行目の if は中身が空で、同じ test -e を2回ずつ走らせています。答えは9本とも正しく、画面には ran 60 shell commands と出るだけなので、コードを開かないと気づきません。
transcriptの集計は仮想の行を外して数える
中の呼び出しはisVirtualの行で残る
オンの1回目の jsonl には assistant の行が 75行ありました。API の応答は2回で、残りの73行はコードの中の呼び出しです。1行を項目を絞って出すとこうなります。
{
"type": "assistant",
"isVirtual": true,
"madeBy": "other",
"message": {
"model": "<synthetic>",
"content": [
{
"type": "tool_use",
"name": "Bash"
}
],
"usage": {
"input_tokens": 0,
"output_tokens": 0
}
}
}
行数で数えるとリクエストが75回に見える
import json, sys
rows = [json.loads(l) for l in open(sys.argv[1])]
assistant = [r for r in rows if r.get("type") == "assistant"]
print("assistant 行:", len(assistant))
real = {r["message"]["id"] for r in assistant if not r.get("isVirtual")}
inner = [r for r in assistant if r.get("isVirtual")]
print("API 応答:", len(real))
print("コード内の呼び出し:", len(inner))
$ python3 count_requests.py on1.jsonl
assistant 行: 75
API 応答: 2
コード内の呼び出し: 73
usage が0なのでトークンの合計は変わりません。ずれるのはリクエスト数とツールの使用回数で、message.id の重複を除いたうえで isVirtual の行を分ける必要があります。
auto modeとpermission modeで確認のされ方が変わる
auto modeの分類器はコードを1回だけ読む
“Permission checks” の auto mode の項です。
the classifier reviews each piece of code before it runs, not each tool call. It doesn’t see values computed at run time, such as a path taken from search output, so keep rules or hooks for calls you must control
初回の確認画面にも “In auto mode, the safety check reads each piece of JavaScript once, before it runs.” と出ます。検索結果から取ったパスのように、実行して初めて決まる値は分類器から見えません。deny と ask のルールと PreToolUse フックはコードの中の呼び出し1件ずつに効くので、止めたい操作は、ルールかフックで止めてください。
manual modeでは呼び出しごとに確認が出る
--permission-mode default で起動すると、画面下には ⏸ manual mode on と出ました。auto mode 以外のモードでは、コードは確認なしで走り始め、そのモードで確認が要るツール呼び出しのたびに確認が出ます。今回は Bash(test *) などを allow に入れていたので、オンの3回は確認が0回でした。
コードの終わりを待つ使い方では、コードは10分で止まり、確認画面で待った時間もこの10分に入ります。バックグラウンドで最大2時間走らせるには、auto か bypassPermissions で起動します。
Code Modeが有効にならない条件
理由がバナーに出るもの
CLAUDE_CODE_EXPERIMENTAL_CODE_MODE=1 CLAUDE_CODE_ENABLE_TELEMETRY=1 claude
⚠ Code Mode (experimental) isn't available: OpenTelemetry is on (CLAUDE_CODE_ENABLE_TELEMETRY or ENABLE_BETA_TRACING_DETAILED), and Code Mode doesn't yet send
it an event for each tool call. Starting with the ordinary tools.
CLAUDE_CODE_EXPERIMENTAL_CODE_MODE=1 DISABLE_TELEMETRY=1 claude
⚠ Code Mode (experimental) isn't available: it needs settings that Claude Code downloads from Anthropic, and this session doesn't download them
(DISABLE_TELEMETRY, DO_NOT_TRACK, CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC or CLAUDE_CODE_DISABLE_FEATURE_FLAGS turns that off). Starting with the ordinary
tools.
Claude CodeのOpenTelemetry設定でトークン消費を集めている環境では、Code Mode は有効になりません。DISABLE_TELEMETRY のほかに DO_NOT_TRACK・CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC・CLAUDE_CODE_DISABLE_FEATURE_FLAGS でも止まることは、メッセージ自体に書かれていました。ツール呼び出しを検査する Mod を入れている場合も、ドキュメントの表によると it doesn't yet work with an installed mod の理由で止まります。
何も出ずにオフになるもの
-p で同じ環境変数を付けた結果です。
CLAUDE_CODE_EXPERIMENTAL_CODE_MODE=1 claude -p "Reply with the single word ok." \
--model haiku --max-turns 1 --output-format stream-json --verbose \
| python3 -c "
import json, sys
for line in sys.stdin:
d = json.loads(line)
if d.get(\"subtype\") == \"init\":
print(\"tools:\", len(d[\"tools\"]), \"REPL\" in d[\"tools\"])
if d.get(\"type\") == \"result\":
print(\"result:\", d[\"subtype\"], d[\"result\"])
"
tools: 25 False
result: success ok
ツールは25本で REPL は無く、警告も出ないまま普段のツールで最後まで動きました。このブログの自動投稿は launchd から claude -p を回しているので(ログイン期限の記事)、Code Mode は入れられません。プロジェクト設定の env とユーザー設定の 0 も、前の章のとおり表示なしでオフになります。
remoteControlAtStartupよりCode Modeが優先される
普段の ~/.claude/settings.json では remoteControlAtStartup を true にしています。同じ設定を検証用の設定ディレクトリに入れて Code Mode を付けると、Code Mode はオンになり、Remote Control のほうがつながりませんでした。
⚠ Code Mode (experimental) is on · this session can be resumed only with Code Mode on
⚠ Remote Control isn't available in Code Mode (experimental) yet, so this session isn't connected. To use Remote Control, quit Claude Code and start it again
with CLAUDE_CODE_EXPERIMENTAL_CODE_MODE set to 0.
スマホから Remote Control で触る予定のセッションでは、シェルに環境変数が残っていないかを先に確かめてください。
まとめ
- Code Mode は v2.1.323 の実験機能。シェルかユーザー設定の
CLAUDE_CODE_EXPERIMENTAL_CODE_MODE=1で有効になり、プロジェクト設定や-pでは何も表示されずオフのまま - 12本の Markdown のリンク確認では、入力トークンが約99,000から約39,000に減った。4割強はツール定義が REPL 1本になった分、残りは往復1回分
- PreToolUse フックはコードの中の呼び出しにも1件ずつ届き、今回は2件が44件になった。
tool_use_idのrepl_で見分けられる - transcript では中の呼び出しが
isVirtualの assistant 行で残る。リクエスト数を数えるときは外す