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

CLAUDE_CODE_NATIVE_CURSORでできること

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

Claude Codeの入力欄の見た目を、使っているターミナルの設定にそろえたいときの切り替えです。縦棒や下線の形、点滅の間隔を自分のターミナルで調整している人が対象になります。ターミナルの既定のままで困っていない人は、有効にする理由がありません。

この変数は見た目だけの話にとどまりません。ネイティブカーソルは、日本語入力(IME)の変換中の文字を入力欄の中に表示する仕組みや、画面拡大鏡・スクリーンリーダーが入力位置を追う仕組みとも関わっています。詳しくは後ろの「日本語入力や補助技術で使うとき」で扱います。

設定する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 Desktopアプリやセルフホスト環境のランナーが起動したセッションでは逆に、起動側が設定した変数が優先され、env の値は無視されます。

たとえば、シェルで 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 に書き分けると、意図しない全員展開を避けられます。

オン/オフの書き方

公式は、オンオフを切り替える環境変数の値を次のように定めています。1・true・yes・on でオン、0・false・no・off でオフで、大文字小文字は区別しません。CLAUDE_CODE_NATIVE_CURSOR もこの書式で扱えます。

設定ファイルの env ブロックからは、変数を削除できません。チームの .claude/settings.json で 1 になっているものを自分だけ打ち消したいときは、個人の ~/.claude/settings.json、そのプロジェクトだけなら .claude/settings.local.json に "CLAUDE_CODE_NATIVE_CURSOR": "0" と書いて、オフの値で上書きします。公式が空文字列を「未設定として扱う」と説明しているのは、プロバイダー選択の変数についてです。この変数をオフにする手段としては、0 を使います。

diffTool のように専用の設定キーが用意されている項目とは違い、CLAUDE_CODE_NATIVE_CURSOR に対応する settings.json の個別キーはありません。切り替えられるのは環境変数だけです。

公式は、モデル選択・タイムアウト・機能トグルのような変数を「安全」なものとして、どの設定ファイルからでも起動時に適用すると説明しています。一方、CLAUDE_CONFIG_DIR のように保存先を変える変数や、テレメトリの送信先を変える変数は、プロジェクト・ローカル設定では無視される専用のリストに載っています。CLAUDE_CODE_NATIVE_CURSOR はそのリストにありません。チームのプロジェクト設定に書けば、全員に配れます。

有効にしたあとカーソルがおかしいときの切り分け

環境変数のページの表には、この変数に必要なバージョンが載っていません。ただしchangelogには、ネイティブカーソルを有効にしたときの表示不具合の修正が複数あります。症状から、どのバージョンで直ったかを引けます。

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

v2.1.183・v2.1.268・v2.1.269の3件は、changelogが「ネイティブカーソルを有効にしているとき」と条件を明記しています。古いバージョンで CLAUDE_CODE_NATIVE_CURSOR=1 を試してカーソルが消えたように見えたら、まず claude updateで更新してから再現を確かめると、原因を絞れます。

日本語入力や補助技術で使うとき

日本語入力が主な使い方なら、この変数を試す動機になります。変換中の文字の扱いはv2.1.84の項目のとおりです。

画面拡大鏡の利用者向けには、別の環境変数 CLAUDE_CODE_ACCESSIBILITY があります。1 にすると、ネイティブなターミナルカーソルを常に見える状態にして、既定の反転表示によるカーソル表示を無効にします。macOS Zoomのような拡大鏡がカーソル位置を追えるようにするための設定です。

v2.1.218以降では、入力キャレットに加えて、/config や /plugin のようなメニューで選択中の行にもカーソルが付きます。公式のアクセシビリティ設定の表は、この変数を画面拡大鏡向けの設定として、縮小モーションの prefersReducedMotion や色覚対応テーマと並べています。

音声読み上げソフトを使う場合は、CLAUDE_AX_SCREEN_READER で画面全体の描画を変えます。1 で、装飾的な枠線やアニメーションのない平らなテキストで描画します(v2.1.181以降)。カーソルの見た目だけを変える2つの変数とは、扱う範囲が違います。

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

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

なお CLAUDE_CODE_DISABLE_ALTERNATE_SCREEN を 1 にすると、フルスクリーン描画が無効になり、従来のメイン画面レンダラーに戻ります。この変数は CLAUDE_CODE_NO_FLICKER と tui 設定のどちらよりも優先されます。

CLAUDE_CODE_NATIVE_CURSOR は入力欄のカーソルだけを切り替える設定で、別の変数で、切り替える対象が違います。カーソルの表示がおかしいときは、どの変数を有効にしているかから切り分けます。

不具合を報告するときやチームに設定を配るときは、「カーソルの設定」とまとめず変数名で書くと、別の変数を調整される行き違いを防げます。

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

CLAUDE_CODE_NATIVE_CURSOR の「cursor」は、テキスト入力位置を示すカーソル(caret)を指す一般名詞で、AIコードエディタのCursorとは無関係です。名前が似ているだけで別物です。

まとめ

個人のターミナルに合わせるだけなら、個人の ~/.claude/settings.json に CLAUDE_CODE_NATIVE_CURSOR を書く形で足ります。チームのプロジェクト設定に置いても全員に配れますが、使わない人は .claude/settings.local.json で 0 を入れて外せます。