Claude Codeスクリーンリーダー対応ガイド — ax-screen-readerの設定と制約

Claude Codeには、ターミナル画面を装飾なしのプレーンテキストに置き換える--ax-screen-readerモードがあります。VoiceOverやNVDAが一行ずつ順番に読み上げられる形式で、有効化の方法は3つ、優先順位も決まっています。設定手順と読み上げられる範囲、まだ対応していない挙動までをまとめます。

有効化する3つの方法と優先順位

有効化の手段は3つあり、どれも同じモードを指します。使う頻度に応じて選べます。

claude --ax-screen-reader

シェルのプロファイルに追記して恒久化する場合はこうです。

export CLAUDE_AX_SCREEN_READER=1

3つの優先順位は固定です。--ax-screen-readerフラグがCLAUDE_AX_SCREEN_READER環境変数に勝ち、環境変数がsettingsのaxScreenReaderに勝ちます。環境変数は0を指定するとsettingsがtrueでも強制的にオフにできます。SSH接続でClaude Codeを使う場合は、環境変数やsettingsをローカル側ではなく実行先のリモートマシンに設定する必要があります。settingsファイルの配置場所とマージ順の詳細はClaude Code設定ガイドにまとめています。

有効化するとターミナルの見え方はどう変わるか

モードが有効になると、Claude Codeは常に旧来の描画方式(classic renderer)を使います。tui設定でfullscreenを選んでいても、モードが有効な間は効果がありません。ただしclaude attachやagent viewから接続するバックグラウンドセッションは、この設定に関わらずフルスクリーンのまま描画されます。

起動直後には、どの方法で有効になったかを示す確認行が表示されます。[Screen Reader Mode: on via flag]のように表示され、この書式はv2.1.206以降で導入されました。それより前のバージョンでは[Accessible screen reader mode: on]とだけ表示されます。Claude Codeが自身を再起動する場合(アップデート適用時など)、新しいプロセスは環境変数経由でモードを引き継ぐため、確認行は使った方法に関わらずon via envになります。

確認行の表示後、Claude Codeは3秒間、以降の描画を止めます。スクリーンリーダーが確認行を読み終えるための間です。何かキーを押せばすぐに解除できます。この待ち時間はCLAUDE_AX_STARTUP_QUIET_MS環境変数(ミリ秒単位、既定3000、上限600000)で変更でき、0を指定すれば待ちません。この機能はv2.1.217以降が必要です。

読み上げられる内容 — ラベル・テーブル・キャレット

読み上げの中身は、罫線や、色でしか示されない情報を省いたプレーンテキストです。変化のない部分は再描画しないので、進行中のスピナーも静止したテキストとして扱われます。テーブルは罫線の格子ではなく「見出し: 値」という文の並びとして読み上げられます(v2.1.198以降)。

トランスクリプトの各メッセージには、種類を示すラベルが先頭に付きます。ラベルはスクリーンリーダーの検索コマンドでも拾えるので、履歴内を種類別に移動できます。

ターミナルのカーソルは常に入力中の位置に追従します。スクリーンリーダーの「現在行を読む」コマンドで、いま編集しているプロンプトの内容がそのまま答えになります。出力はターミナルのスクロールバックに蓄積されるので、スクリーンリーダーの復読コマンドやターミナルの検索で過去の発言を読み返せます。

入力編集と権限モード変更の読み上げ

文字を入力したりBackspaceで削除したりすると、変化した文字だけが書き込まれます。行末での削除はv2.1.222以降、入力自体の1文字ずつの読み上げはv2.1.219以降が必要です。それより前のバージョンでは、1文字打つたびに行全体が書き直され、スクリーンリーダーは行を毎回読み直していました。

単語や行を丸ごと削除したときは、削除された文字列がそのままアナウンスされます(v2.1.218以降)。対象は次の操作です。

• 単語削除: Ctrl+W / macOSのOption+Delete / WindowsのCtrl+Backspace
• 行頭までの削除: Ctrl+U / Cmd+Backspace
• 行末までの削除: Ctrl+K

Shift+Tabで権限モードを切り替えると、[plan mode on]のように切り替わった先のモードがアナウンスされます(v2.1.210以降)。アナウンスは1回だけで、以降の再描画では繰り返されません。

メニューと確認プロンプトの操作

矢印キーで選ぶ通常のメニューは、スクリーンリーダーモードでは番号付きの一覧に変わります。権限確認のメニューも対象です。各選択肢が番号付きの行として読み上げられたあと、有効な範囲を示す「Enter selection」の案内が続きます。数字を入力してEnterを押すだけで選べます。取り消せるメニューはEscで閉じられ、範囲外の数字を入力すると有効な範囲が再度アナウンスされます。

はい・いいえで答えるプロンプトは、2択メニューではなく文字入力に変わります。yまたはn(yes / noも可)を入力してEnterを押します。

ターン間のジャンプとベル通知

Claude Codeはターンの区切りでOSC 133というシェル連携用の目印を出力します。ターミナル側の「前のプロンプトへジャンプ」機能を使えば、履歴を読み進めずにターンを移動できます。

macOSの標準TerminalとWezTermはこの目印に対応していません。この2つではyou:ラベルをスクロールバック内で検索して移動します。

スクリーンリーダーモードでは、応答が終わったとき・権限確認が表示されたとき・5秒を超えて実行したツールが完了したときにターミナルベルが鳴ります。ベル自体はスクリーンリーダーモード専用ではなく、モードの外でもpreferredNotifChannelを"terminal_bell"に設定すれば同様の通知が得られます。

スクリーンリーダー以外のアクセシビリティ設定

スクリーンリーダーモードと独立して使える設定が3つあり、併用もできます。

• 拡大鏡向け: CLAUDE_CODE_ACCESSIBILITY=1。ネイティブのターミナルカーソルを常に表示したままにし、macOSのZoomのような拡大鏡がカーソル位置を追従できるようにします。入力中のキャレットだけでなく、/configや/pluginのようなパネルで矢印キー移動したときの選択行もv2.1.218以降で追従対象です
• モーション低減向け: prefersReducedMotion設定。スピナーやシマー効果などのアニメーションを減らすか止めます
• 配色向け: theme設定。色覚特性に配慮したdark-daltonized / light-daltonizedを選べます

既知の制限

公式ドキュメントが明記する範囲で、まだ対応していない挙動は次のとおりです。

うまく動かない、あるいは使っている支援技術やターミナルで違う挙動が出た場合は、Claude CodeのGitHub issueで支援技術の種類・OS・ターミナルアプリを添えて報告する経路が用意されています。

進化のタイムライン — v2.1.181からv2.1.222まで

3通りの有効化方法や読み上げの細部は、1回のリリースでまとまって入ったわけではありません。公式ドキュメントが示す必須バージョンと、公式changelogに載った変更点を突き合わせると、数か月かけて積み上げられてきたことが分かります。

必須バージョンとしてv2.1.181・v2.1.198・v2.1.206が挙がっているのに、当時のchangelogにはその機能への言及がありません。機能が公式に発表されたのはv2.1.208で、発表の1か月近く前から動く状態で配布されていたことになります。安定させてからchangelogで告知する進め方だったと見えます。単語・行削除のアナウンスを加えたv2.1.218、行末読み上げの精度を上げたv2.1.222も、それぞれのリリースノートで前後の変更点を確認できます。

よくあるつまずき

• フラグを付けたのに何も変わらない場合: v2.1.181より前のバージョンを使っている可能性があります。claude --versionで確認します
• フルスクリーン設定にしているのに描画がおかしい場合: モードが有効な間はtui設定が無視され、常に旧来の描画方式になります。想定どおりの挙動です
• バックグラウンドセッションだけ様子が違う場合: claude attachやagent view経由のセッションは、モードの設定に関わらずフルスクリーン描画のままです
• SSH先で設定したのに効かない場合: 環境変数やsettingsはSSHの接続元ではなく、Claude Codeが実際に動くリモート側のマシンに置く必要があります
• 入力のたびに行全体が読み上げ直される場合: 1文字ずつの読み上げにはv2.1.219以降、行末削除にはv2.1.222以降が必要です。古いバージョンではこの挙動になりません

よくある質問

VoiceOverとNVDA以外のスクリーンリーダーでも使えますか

公式ドキュメントが名指ししているのはVoiceOverとNVDAです。出力自体は特定のスクリーンリーダーに依存しないプレーンテキストとして設計されていますが、他の製品での動作は公式に明言されていません。うまくいかない場合はGitHub issueでの報告が案内されています。

スクリーンリーダーを使っていれば自動で有効になりますか

いいえ。VoiceOverやNVDAが起動中でも、Claude Code側にそれを検出する仕組みはありません。OSのアクセシビリティ設定をどう変えていても、起動時にフラグ・環境変数・settingsのいずれかを明示しなければ通常モードのまま立ち上がります。

Windows Terminalでターン間のジャンプを使うには

既定のキー割り当てはありません。Windows Terminalの設定でscrollToMarkコマンドに任意のショートカットキーを割り当てると、iTerm2やVS Code統合ターミナルと同じくOSC 133の目印を使ったジャンプができるようになります。

CLAUDE_CODE_ACCESSIBILITYとスクリーンリーダーモードは併用できますか

できます。CLAUDE_AX_SCREEN_READER=1とCLAUDE_CODE_ACCESSIBILITY=1は独立した設定で、同時に有効にしても競合しません。拡大鏡でカーソル位置を追いながら、スクリーンリーダーモードの読み上げも受け取りたい場合は両方を設定します。

まとめ

--ax-screen-readerはv2.1.181で動作を始め、確認行の書式・削除のアナウンス・行末読み上げの精度がバージョンを追うごとに整備されてきました。今使っているバージョンがv2.1.222より古ければ、恩恵を受けられていない挙動が残っている可能性があります。claude updateで最新化してから、claude --ax-screen-readerで挙動を確かめます。