Claude Code のスクリーンリーダーモード — 機械処理に流用しようとして間違えた

Claude Code にスクリーンリーダーモードが入り、専用のドキュメントページも用意された。罫線やスピナー、その場での再描画といった視覚前提のターミナル表示を、ラベル付きの平文の並びに置き換えるモードだ。有効化の方法は3通りある。

何が変わるのか
1. 権限プロンプトが番号付きリストになる
2. ターミナルベルで状態を知らせる
有効化の3通り
機械処理に流用しようとして、間違えた
1. -p の出力が本当に変わらないか、バイトで比べた
出力モードの使い分け
ターン間ジャンプの設定は端末による
併用できる関連設定
書かれていないこと
なぜ再描画が問題になるのか
Windows で試すなら
筆者ならこう試す
参考

何が変わるのか

ターミナル UI は、同じ場所を何度も描き直して進捗を見せる作りになっている。目で見ている分には自然だが、スクリーンリーダーは書き換わるたびに読み直そうとするので、内容を最後まで追えない。

このモードでは、その前提をやめる。

罫線文字を使わない
色だけを手がかりにしない
変更のない内容を再描画しない（スピナーは静的なテキストになる）
表は Header: value の文に展開する
tui の設定を上書きして classic レンダラーを強制する
出力がスクロールバックに蓄積されるので読み返せる

行頭にラベルが付くのも実務的だ。you: / claude: / tool: / tool error: / error: / Permission Required: / Cost: の形で、読み上げの区切りになると同時に検索もできる。

権限プロンプトが番号付きリストになる

変化として一番大きいのはここだと思う。矢印キーで選ぶメニューから、番号付きリストに変わる。

各選択肢が番号の付いた行として読み上げられ、Enter selection が有効な範囲を告げる。範囲外の数字を入力すれば聞き直してくれる。Yes / No は y と n をタイプする（yes / no でも通る）。キャンセルは Escape で、プロンプトの末尾に or Escape to cancel が付く。

矢印キーでの選択は、今どこにカーソルがあるかを目で見る前提の操作だ。それを番号の指定に置き換えたことで、読み上げだけで完結する。

ターミナルベルで状態を知らせる

返答が終わったとき、権限プロンプトが出たとき、5秒を超えたツールが終わったときにベルが鳴る。画面を注視していなくても状態が分かる。

v2.1.211 以降、このモードでは /terminal-setup がベルの設定に触らないようになった。せっかくの通知が設定変更で消える事故を防ぐ変更だ。

有効化の3通り

# そのセッションだけ
claude --ax-screen-reader

# そのシェルだけ
export CLAUDE_AX_SCREEN_READER=1

// マシン全体 ~/.claude/settings.json（VS Code の統合ターミナルを含む）
{ "axScreenReader": true }

優先順位はフラグ、環境変数、設定ファイルの順。CLAUDE_AX_SCREEN_READER=0 にすれば、設定ファイルが true でも強制的にオフになる。SSH で使うときはリモート側に設定する。v2.1.181 未満では error: unknown option '--ax-screen-reader' になる。

起動時に、どの経路で有効になったかを示す行が出る。

[Screen Reader Mode: on via flag]
[Screen Reader Mode: on via env]
[Screen Reader Mode: on via settings]

この表示形式は v2.1.206 以降で、それ以前は [Accessible screen reader mode: on] だった。自己再起動したときは環境変数を継承するので、常に on via env になる。設定した経路と表示が食い違って見えることがあるが、動作としては正しい。

機械処理に流用しようとして、間違えた

正直に書いておく。この機能を知ったとき、筆者が最初に考えたのは「平文になるならログ解析や CI への取り込みに使えるのでは」ということだった。

調べたら、公式が明確に否定していた。

Screen reader mode doesn’t change non-interactive mode with the -p flag. Non-interactive mode already writes plain text and remains an alternative for scripting.

--ax-screen-reader が変えるのは対話 TUI の描画方式だけで、-p の出力には影響しない。スクリプト用途には -p と --output-format json という別の正解が用意されている。

もう1つ思い込みがあった。「平文になる＝ANSI エスケープシーケンスが消える」と考えていたが、ドキュメントに剥がすという記述はない。書かれているのは「色だけを手がかりにしない」であって、色の除去ではない。それどころか、このモードはターン境界をジャンプするための OSC 133 シェル統合マーカーを能動的に出力する。エスケープシーケンスはむしろ増える。

視覚出力や配布物は実測してから「動く」と言うようにしてきたが、今回は自分の期待でドキュメントを読み違えかけた。用途を決めつける前に、公式が何を目的として作ったかを読むほうが早い。

-p の出力が本当に変わらないか、バイトで比べた

公式が否定していると書いたが、読んだだけで済ませたくなかった。2.1.220 で同じ質問を2回投げて、出力を突き合わせた。

claude -p "1から3までの数字を箇条書きで出して" ... | cat -A
claude -p "1から3までの数字を箇条書きで出して" ... --ax-screen-reader | cat -A

cat -A は行末や制御文字も見える形で出す。結果は両方ともこれだった。

- 1$
- 2$
- 3$

行末の $ まで含めて一致した。-p はもともと平文を出しているので、このモードが足すものが無い。記述どおりだ。

環境変数の経路も動いた。CLAUDE_AX_SCREEN_READER=1 を付けて -p を叩いても、エラーにならず通常どおり応答が返る。

スクリプト用の正解として案内されている --output-format json を叩くと、21個のキーが返ってきた。

{"type":"result","subtype":"success","is_error":false,
 "result":"OK","num_turns":1,"duration_ms":3528,
 "total_cost_usd":0.0605835,
 "usage":{"input_tokens":10,"cache_creation_input_tokens":28756,
          "cache_read_input_tokens":23415,"output_tokens":144},
 "session_id":"...","permission_denials":[],"ttft_ms":...}

total_cost_usd と usage と permission_denials がそのまま入っている。読み上げ用の平文をパースするより、この JSON を読むほうが速いし壊れない。平文が欲しくて --ax-screen-reader を思い出したなら、それは --output-format json の出番になる。

出力モードの使い分け

	`--ax-screen-reader`	`-p`	`-p --output-format json`
目的	支援技術での対話利用	スクリプト・CI	構造化した取得
対話性	あり（承認できる）	なし	なし
形式	ラベル付き平文＋OSC 133	プレーンテキスト	JSON
機械処理用途で選ぶ	非推奨	可	推奨

JSON なら result、session_id、total_cost_usd、モデル別の内訳が取れる。--json-schema で構造化出力、stream-json で NDJSON も選べる。自動化パイプラインを組むならこちらだ。

CI 向けには --bare もある。フックや MCP、CLAUDE.md の自動探索をスキップするもので、将来 -p の既定になる予定とされている。

ターン間ジャンプの設定は端末による

OSC 133 マーカーを使ったターン間の移動は、端末側の対応が要る。

端末	操作
iTerm2	`Cmd+Shift+Up`
VS Code	`Ctrl+Up`（Windows）/ `Cmd+Up`（Mac）
Windows Terminal	既定なし。`scrollToMark` の割り当てが要る
macOS Terminal	マーカーを解釈しない
WezTerm	マーカーが出力されない