---
name: code-mode
description: Claude Code の Code Mode(実験機能、CLAUDE_CODE_EXPERIMENTAL_CODE_MODE=1)で作業を走らせる・試す・トークンを測る手順。「/code-mode」「Code Mode で動かして」「tmux で claude を立てて指示」「REPL ツールで実行」「Code Mode のトークン量を測って」と言われたら、直接そう呼ばれていなくても使う。--bg の別セッションでは Code Mode が効かないので、tmux で対話式のセッションを立てて指示文を貼る。
---
# Code Mode で作業を走らせる
Code Mode は、ツール呼び出しを JavaScript(REPL)にまとめて実行する実験機能。環境変数 `CLAUDE_CODE_EXPERIMENTAL_CODE_MODE=1` を付けて起動した対話式のセッションだけで効く。
## 先に知っておくこと
- **`claude --bg` では効かない。** 起動時に「Code Mode isn't available: … doesn't work in background jobs, in teammates' panes or with Remote Control」と出て、通常のツールで動く。`--settings` で変数を渡しても同じ。
- **Remote Control は使えない。** `claude agents` / `claude logs` にも出ない。進み具合は tmux で見る。
- **起動時に有効化の確認が出る**(「Yes, turn on Code Mode」/「No, start without it」。既定は No)。Yes を選ばないと通常モードで始まる。`launch.sh` が自動で Yes を答える。
- **指示文は引数で渡さない。** `--add-dir` のように可変長の引数があると、指示文が値として読まれることがある。起動後に貼り付ける。
- Code Mode で始めたセッションは、Code Mode を有効にした環境でしか再開できない。
## 手順
1. 指示文をファイルに書く。自己完結させ、完了時に `result:` の行を書くよう指示する。
2. `scripts/launch.sh <tmux セッション名> <作業ディレクトリ> <指示文ファイル>` を実行する。tmux を立て、有効化確認に Yes を答え、指示文を貼って送る。指示文の末尾には「終わったら目印ファイルを `touch` する」が自動で足される。
3. 進み具合は `tmux capture-pane -t <名前> -p | grep -v '^\s*$' | tail -20`。自分で見るときは `tmux attach -t <名前>`。
4. **完了後の片付けは自動。** `scripts/close-when-done.sh` が目印ファイルを待ち(最長 3 時間)、画面の記録とトークン量をログに保存して tmux を閉じる。結果はこのログを読む。画面の文字(`result:` など)で完了を判定しない(指示文自身が映って誤検知する)。
起動直後に「Code Mode (experimental) is on」の行が出ていれば有効。出ていなければ通常モードなので、やり直す。
**使われたかは、終わったあとに記録で確かめる。** 画面の表示だけでは、実際に REPL ツールを呼んだか分からない。ログ(`$CODE_MODE_LOGDIR/<名前>.log`、既定は `~/.claude/code-mode-logs/`)の末尾の「Code Mode の使用: あり(REPL N 回)」を見る(`measure.py` が記録の `tool_use` を数える)。「なし」なら Code Mode は効いていない。
## 設定(環境変数)
| 変数 | 意味 |
|---|---|
| `CLAUDE_CMD` | 起動するコマンド。既定は `claude`。権限モードや `--add-dir` など、起動の引数はここに含める。シングルクォートは含めない |
| `CODE_MODE_AUTOTRUST=1` | フォルダ信頼の確認(既定は No, exit)に自動で Yes を答える。**既定は無効**。信頼してよい作業ディレクトリでだけ付ける。無効のときは確認画面で止まり、終了コード 4 を返す |
| `CODE_MODE_LOGDIR` | ログと完了の目印の置き場。既定は `~/.claude/code-mode-logs` |
| `MODE=normal` | Code Mode なしで同じ構成のセッションを立てる(比較用) |
## トークン量を測る
`scripts/measure.py <作業ディレクトリ>` が、そのディレクトリのセッションの記録(`~/.claude/projects/`)から入力・出力・キャッシュのトークン数を合計する。
トークンは作業ディレクトリ単位で集計するので、専用のディレクトリで立てる(他のセッションも使うディレクトリで測ると、全部の合計になる)。金額は `--price in,out,cache_write,cache_read`($/MTok)を渡したときだけ計算する。サブスクリプションのセッションでは `/cost` が使用率しか出さないので、単価を持たないときは「金額は測れない(使用率のみ)」と書く。
報告には「どのモデルか・何トークン・金額の出どころ」を書く。推測の単価で断定しない。
## 効果の実測(2026-11-21、同じ課題を Code Mode あり・なしで 1 回ずつ。モデルは同じ Sonnet 5.5)
| 課題 | 合計トークン(あり/なし) | 出力 | 概算金額(あり/なし) | REPL 回数 |
|---|---|---|---|---|
| Rust 電卓ロジック | 659,622 / 1,075,214(−39%) | 9,670 / 9,756 | $0.87 / $1.09(−20%) | 3 |
| Python CSV 集計 | 485,687 / 889,534(−45%) | 4,268 / 5,332 | $0.73 / $0.89(−18%) | 2 |
| Python Markdown 表整形 | 819,407 / 891,718(−8%) | 6,508 / 5,365 | $0.88 / $0.89(−1%) | 4 |
- 全ケースで REPL が呼ばれ、生成物(テスト全件成功・コミット済み)の品質は同等だった。
- 減るのは主にキャッシュ読込(毎ターン読み直す量)。ツール呼び出しを 1 回の REPL にまとめるので、ターン数が減る課題ほど効く。直しの往復が増えた課題(Markdown 表整形はテスト失敗後の修正で REPL 4 回・Edit 5 回)では差が縮む。
- 金額は仮の単価(入力 $3・出力 $15・キャッシュ書込 $3.75・キャッシュ読込 $0.30 /MTok)での概算。実際の単価ではないので、断定には使わない。標本は 3 件だけで、小さな新規作成の課題に限る。大きな既存コードの修正では未測定。