CLAUDE_CODE_NATIVE_CURSORとは — ターミナル本来のカーソル表示に切り替える環境変数

CLAUDE_CODE_NATIVE_CURSORでできること

CLAUDE_CODE_NATIVE_CURSOR は、Claude Codeのプロンプト入力欄でカーソルの描き方を切り替える環境変数です。1 を設定すると、Claude Codeが自分で描くブロックカーソルの代わりに、ターミナルが本来持っているカーソルを入力位置に表示します。

既定の状態では、Claude Codeは入力キャレットの位置にブロック状のカーソルを自前で描画します。この変数を有効にすると、その描画をやめてターミナルのカーソルに委ねます。結果として、点滅の間隔・縦棒や下線などの形状・ウィンドウがフォーカスを失ったときの見た目が、Claude Code側の設定ではなくターミナルアプリ側の設定に従うようになります。

iTerm2やWindows Terminalでカーソル形状を縦棒に変えていたり、点滅間隔を独自に調整していたりする場合、既定のブロックカーソルはその設定を無視して表示されます。CLAUDE_CODE_NATIVE_CURSOR=1 にすると、ターミナル側の見た目をClaude Codeの入力欄にもそのまま反映できます。逆に、ターミナルの既定設定のままで構わない人や、常に同じ見た目のカーソルを好む人には、この変数を有効にする理由はありません。

設定する2つの方法

環境変数なので、設定できる場所は2つあります。1つはシェルで直接エクスポートする方法、もう1つは設定ファイルの env キーに書く方法です。どちらを選ぶかは、その場で試したいか、常設したいかで決まります。

シェルで一時的に試すだけなら、claude を起動する前にエクスポートします。

export CLAUDE_CODE_NATIVE_CURSOR=1
claude

このシェルを閉じると設定は消えます。毎回のセッションで有効にしたいなら、~/.bashrc や ~/.zshrc に同じ export 行を追記します。効くのはそのマシンでそのシェルを使う場合だけで、別のマシンや、Claude Codeを別のシェルから起動する場合には引き継がれません。

Windows PowerShellとCMDでは、変数を設定するコマンドの書式が異なります。

$env:CLAUDE_CODE_NATIVE_CURSOR = "1"

set CLAUDE_CODE_NATIVE_CURSOR=1

いずれのシェルでも、代入コマンドは成功しても画面に何も表示されません。設定できたかどうかは、claude を起動する前に同じシェルで変数を出力させて確認します(PowerShellなら echo $env:CLAUDE_CODE_NATIVE_CURSOR、CMDなら echo %CLAUDE_CODE_NATIVE_CURSOR%)。

常設したい、またはプロジェクトのメンバー全員に配りたい場合は、設定ファイルの env キーに書きます。

{
  "env": {
    "CLAUDE_CODE_NATIVE_CURSOR": "1"
  }
}

どのファイルに書くかで適用範囲が変わります。

設定ファイルの env ブロックに書いた値は、シェルで先に設定していた同名の変数より優先されます。Claude Codeが起動時に各エントリをプロセス環境へ書き込み、シェルから引き継いだ値を上書きする仕組みです。

たとえば、シェルで CLAUDE_CODE_NATIVE_CURSOR=0 をエクスポートした状態でも、~/.claude/settings.json の env に "CLAUDE_CODE_NATIVE_CURSOR": "1" と書いておけば、起動時に設定ファイル側の値でプロセス環境が上書きされ、有効になるのは 1 の方です。組織の管理設定が同じ変数をさらに指定していれば、そちらがユーザー設定より優先されます。

チームで統一したいだけなら .claude/settings.json に、自分だけ試したいなら .claude/settings.local.json か個人の ~/.claude/settings.json に書き分けると、意図しない全員展開を避けられます。

オン/オフの書き方

真偽値を取る環境変数の例に漏れず、CLAUDE_CODE_NATIVE_CURSOR も 1 または true でオン、0 または false でオフになります。大文字小文字は区別されません。設定ファイルの env ブロックからは値を削除できないため、いったんオンにしたものを個人環境で打ち消したいときは、空文字列を指定して未設定として扱わせる方法が使えます。空文字列にした場合でも、Claude Codeが起動する子プロセスにはその空の値がそのまま渡ります。

diffTool のように専用の設定キーが用意されている項目とは違い、CLAUDE_CODE_NATIVE_CURSOR に対応する settings.json の個別キーはありません。切り替えられるのは環境変数だけです。公式ドキュメントは、モデル選択・タイムアウト・機能トグルのような「安全」に分類した変数を、ユーザー・プロジェクト・ローカル・管理設定のどのファイルからでも起動時に適用すると説明しています。CLAUDE_CONFIG_DIR のように保存先を変える変数や、テレメトリの送信先を変える変数はプロジェクト・ローカル設定からは無視される専用の除外リストに載っていますが、CLAUDE_CODE_NATIVE_CURSOR はこのリストに含まれていません。そのため、チームのプロジェクト設定に書けば全員に配れます。

有効化する前に知っておきたい既知の不具合

公式ドキュメントは、特定のバージョン以降が必要とは明記していません。ただし公式changelogを追うと、この変数を有効にした状態に限って起きていた表示の不具合が複数回修正されています。

v2.1.183の不具合は、Vimキーバインドでプロンプトを編集するモードを使っているときに限って起きていました。ノーマルモードで履歴を上下にたどったあとにネイティブカーソルが入力行から外れて表示され、実際の入力位置と見た目がずれる症状です。vimモードを使わない人には関係がありません。

いずれも「ネイティブカーソルを有効にしているときだけ」条件付きで発生していた不具合で、現在配布されているバージョンでは修正済みです。ただし、古いバージョンのまま CLAUDE_CODE_NATIVE_CURSOR=1 を試す場合は、こうした入力欄でカーソルが見えなくなる症状が既知の問題として過去に存在した点を踏まえておくと、原因の切り分けが早くなります。カーソルが消えたように見えたら、まず claude updateで最新版に上げてから再現するかどうかを確認するのが手早い切り分け方です。

画面拡大鏡向けのCLAUDE_CODE_ACCESSIBILITYとは別物

カーソル関連の環境変数には、CLAUDE_CODE_ACCESSIBILITY という似た名前のものもあります。こちらは、macOS Zoomのような画面拡大鏡がカーソル位置を追跡できるようにするための変数です。1 に設定すると、ネイティブなターミナルカーソルを常時表示させたまま、既定の「反転表示によるカーソル表示」を無効にします。

公式のアクセシビリティ機能一覧は、この変数を画面拡大鏡・縮小モーション・色覚サポートテーマと並ぶ「オプトインの支援機能」の1つとして扱っています。バージョン2.1.218以降では、入力キャレットだけでなく /config や /plugin のようなメニューで選択中の行もカーソルと同じ扱いで拡大鏡に追いやすくなります。

CLAUDE_CODE_NATIVE_CURSOR はターミナルの点滅・形状設定に合わせることが目的で、CLAUDE_CODE_ACCESSIBILITY は拡大鏡にカーソル位置を確実に伝えることが目的です。どちらも見た目の違う「ターミナル本来のカーソル」を使わせる変数ですが、想定する利用場面が異なります。画面拡大鏡を使っているなら後者を、ターミナルの見た目をそのまま活かしたいだけなら前者を選ぶ基準になります。

なお、音声読み上げソフトを使う場合は CLAUDE_CODE_ACCESSIBILITY ではなく CLAUDE_AX_SCREEN_READER を使います。こちらはスクリーンリーダー向けにターミナル画面全体の描画方法を変えるオプトイン機能で、カーソルの見た目だけを変える2つの変数とは扱う範囲が異なります。

フルスクリーン表示のカーソルとは別の設定

Claude Codeには、CLAUDE_CODE_NO_FLICKER という別の環境変数もあります。こちらはリサーチプレビュー段階のフルスクリーン描画モードを有効にするための変数で、長い会話でもメモリー使用量を抑えつつ画面のちらつきを減らす機能です。フルスクリーン表示(TUI)の仕組みと制約にまとまっているとおり、この描画モードはtui設定を上書きし、/tui fullscreen からも切り替えられます。

CLAUDE_CODE_NATIVE_CURSOR はプロンプト入力欄のカーソルの見た目だけを切り替える設定で、フルスクリーン描画モードそのもののオン・オフとは別の話です。両者は名前も効果も異なるので、「カーソルの表示がおかしい」という症状を調べるときは、まずどちらの設定を有効にしているかを切り分けます。

似た名前の環境変数を早見表で見分ける

カーソルや画面の表示に関わる環境変数は、CLAUDE_CODE_NATIVE_CURSOR のほかにも複数あり、名前が似ているぶん取り違えやすいものです。

3つとも設定できる値の書式は共通で、1/true でオン、0/false でオフです。ただし対象になる症状はそれぞれ異なるため、不具合を報告するときや設定をチームに配るときは、どの変数の話をしているのかを変数名で明示すると混同を防げます。名前だけを頼りに「カーソルの設定」とまとめて呼ぶと、担当者が別の変数を調整してしまうことがあります。

Cursorエディタの話ではない点に注意

CLAUDE_CODE_NATIVE_CURSOR の「cursor」は、テキスト入力位置を示すカーソル(caret)を指す一般名詞で、AIコードエディタのCursorとは無関係です。検索するときにこの変数名とエディタ名が混ざりやすいので、区別して覚えておくと安全です。

まとめ

CLAUDE_CODE_NATIVE_CURSOR は、Claude Codeの入力欄カーソルをブロック描画からターミナル本来の表示に切り替える環境変数です。設定は 1 に指定するだけとシンプルですが、過去にはこの変数を有効にした状態でだけ発生していた入力欄のカーソル消失が複数バージョンにわたって報告・修正されてきました。ターミナルのカーソル設定(点滅・形状)をそのままClaude Codeの入力欄にも反映させたい人にとっては便利な切り替えですが、有効にしていて入力欄のカーソルが見えなくなったら、まず手元のバージョンが最新かどうかを確認してみてください。名前の似た CLAUDE_CODE_ACCESSIBILITY や CLAUDE_CODE_NO_FLICKER とは目的が異なるため、切り替える前に早見表でどの変数の話かを確かめておいてください。