Claude Codeの日本語入力が崩れる・文字化けする——原因は2つある。公式ドキュメントとGitHub Issueで切り分けた
Claude Codeで日本語入力時に文字が消える・文字化けする問題を、GPU描画バグとIME合成バグという別々の原因に切り分けて解説。公式の/terminal-setup修正と、まだ直っていないIME入力バグの回避策までまとめた。
エンジニアのゆとです。
「Claude Code 文字化け」で検索すると、結構な数の記事がヒットする。読んでみると大体「文字コードの設定を見直しましょう」「LANG環境変数をja_JP.UTF-8にしましょう」という話で終わっていて、正直それで直った試しがない人も多いんじゃないかと思う。
理由は単純で、「文字化け」と一口に言っても、実際には性質の違う複数の不具合が混ざっているからだ。この記事では、公式ドキュメントとGitHub Issueまで遡って、症状ごとに原因を切り分けた。
結論 — 「崩れ方」で原因が変わる
先に結論を書く。日本語入力まわりの不具合は、大きく2種類に分かれる。
- 表示が崩れる（文字化け・ちらつき） → VS Code / Cursor / Devin Desktopの統合ターミナルのGPU描画が原因。公式に修正コマンドが用意されている
- 入力中に文字が消える・カーソル位置がずれる → IMEの変換中（合成中）の文字をClaude Codeが正しく扱えていないのが原因。こちらはまだ根本修正されていない既知のバグで、回避策を使うしかない
どちらも「日本語入力の問題」とひとくくりにされがちだけど、原因も対処法も別物だ。順番に見ていく。
原因1: GPU描画による文字化け・表示崩れ
VS CodeやCursor、Devin Desktopの統合ターミナルでClaude Codeを動かすと、文字が四角や意味不明な記号に化けたり、画面がちらついたりすることがある。これはAnthropicの公式トラブルシューティングドキュメントに明記されている既知の症状だ。
原因は、これらのエディタの統合ターミナルが使っているGPUレンダラーだ。日本語のような全角文字を含む出力を描画する際に、このレンダラーが崩れた表示を出すことがある。
対処法はシンプルで、Claude Code内で以下のコマンドを実行するだけでいい。
/terminal-setupこのコマンドは、VS Code / Cursor / Devin Desktopに対してterminal.integrated.gpuAcceleration設定を"off"に書き換える。GPU描画を無効化することで、文字化けの原因そのものを止める仕組みだ。あわせてスクロールの挙動も調整されるので、実行後にエディタのウィンドウをリロード（再読み込み）すれば反映される。
手動で直したい場合は、エディタの設定（settings.json）に以下を追加してもいい。
{
"terminal.integrated.gpuAcceleration": "off"
}元に戻したくなったら"auto"に戻してウィンドウをリロードすれば元通りだ。パフォーマンスへの影響はほぼ体感できないレベルなので、日本語で使う場合は最初からoffにしておいて困ることはないと思う。
ちなみに/terminal-setupはこの文字化け対策以外に、Shift+Enterで改行できるようにするキーバインドも同時に書き込んでいる。「改行しようとしたら送信されてしまう」問題で悩んでいる場合は、ターミナル別の対処法をまとめた記事もあわせて見てほしい。
原因2: IME入力中の文字消失・カーソル位置ズレ
もう1つが、こちらの方が実は根が深い。日本語（や中国語・韓国語・ベトナム語などのマルチバイト言語）をIMEで変換入力しているときに、変換中の文字が消えたり、確定した文字の位置がずれたりする不具合だ。
これはGitHub Issueで継続的に報告されている、まだ未解決のバグになる。
なぜ起きるのか
Claude CodeのターミナルUIは、React InkというライブラリのuseInputフックでキー入力を処理している。このuseInputが、キーが押された瞬間に即座に処理してしまい、IMEが「変換中の文字を確定させる」までの合成（コンポジション）が終わるのを待たない。
その結果、変換途中の文字がそのまま処理されて欠落したり、重複したりする。ローマ字入力で「ありがとう」と打ったつもりが「りがとう」になっている、といった症状はこれが原因のことが多い。
これは英語圏のライブラリでよくある盲点で、Claude Code固有のバグというより、ターミナルUIライブラリの設計がマルチバイト言語のIME入力を想定していないことに起因する。実際、影響を受けるのは日本語だけでなく、中国語（ピンイン入力）・韓国語（ハングル入力）・ベトナム語（Telex/VNI入力）のユーザーも同様だ。
似た症状として、VS Code統合ターミナル限定で「IMEの変換候補ウィンドウが本来のカーソル位置ではなく、右端や画面下部にずれて表示される」という報告もある。
こちらはWindows + VS Code統合ターミナルという組み合わせに限定された報告で、Claude Codeが描画する「見せかけのカーソル」と、ターミナルが実際に管理しているカーソル位置がずれることで起きている。ページ上では未解決のまま自動クローズされており、正式な修正は確認できていない。
回避策
根本修正はReact Ink本体側の対応待ちで、開発コミュニティからは合成バッファリングを追加するプルリクエストが提案されている状態だ（vadimdemedes/inkリポジトリの#865）。マージされて依存関係が更新されるまでは、Claude Code側だけで直すことはできない。
それまでの回避策として、terminal-ime-proxyという有志製のラッパーツールが使える。IME入力を横取りして正しく合成してからClaude Codeに渡す、という仕組みだ。
npm install -g terminal-ime-proxy
timp claudeclaudeコマンドの代わりにtimp claudeで起動すると、IME周りの不具合が緩和される。ただし非公式のサードパーティツールなので、業務利用する場合は挙動を一度自分の環境で確認してから使うのが無難だ。
もう1つ、地味に厄介なバグとして「日本語IME変換中にEnterキーを押すと、変換確定ではなくメッセージが送信されてしまう」という報告もある。
これに心当たりがある場合は、変換を確定させるときは一呼吸置いてEnterを押す、あるいは変換候補が消えたのを目で確認してから次の操作に移る、という運用でしのぐしかないのが現状だ。
切り分けチェックリスト
自分の症状がどちらに当てはまるか、以下で切り分けられる。
| 症状 | 原因 | 対処法 |
|---|---|---|
| 画面全体がちらつく・文字が四角や記号に化ける | GPU描画（原因1） | /terminal-setupを実行してエディタをリロード |
| VS Code / Cursor / Devin Desktopの統合ターミナルでのみ発生する | GPU描画（原因1） | 同上 |
| 変換中の文字が消える・打ったはずの文字が抜ける | IME合成バグ（原因2） | terminal-ime-proxyを導入 |
| 変換候補の位置が右端や画面下にずれる | IME合成バグ（原因2） | 現状は回避策のみ、Issueを追う |
| 変換確定のつもりがメッセージ送信されてしまう | IME合成バグ（原因2） | Enterのタイミングに注意して運用でカバー |
英語入力では問題なく、日本語入力時にだけ症状が出るなら、まず/terminal-setupを試して、それでも直らなければIME合成バグの方を疑う、という順番で見ていくのが早い。
ターミナルアプリ自体を変える選択肢
そもそもの話として、統合ターミナルではなく、Kitty・iTerm2・WezTerm・Windows Terminalのような単体のターミナルアプリからClaude Codeを起動すれば、GPU描画由来の文字化けは経験しにくくなる。ただしIME合成バグの方はReact Ink側の問題なので、ターミナルを変えても解消しない点は注意してほしい。
Windows環境でClaude Codeを使っていて日本語入力に不満がある場合は、WSL・Git Bash・PowerShellそれぞれで挙動が微妙に違うので、環境選び自体を見直すのも手だ。
FAQ
/terminal-setupを実行しても文字化けが直らない
原因2（IME合成バグ）の方に該当している可能性が高い。/terminal-setupはGPU描画由来の文字化けにしか効かないので、症状が「入力中に文字が消える」系であればterminal-ime-proxyを試してほしい。
ファイルを開いたときに日本語が文字化けする場合も同じ原因か
これは別問題だ。この記事で扱っているのはターミナル上の表示・入力の話で、ファイル保存時の文字コード（UTF-8とShift-JISの混在など）が原因の文字化けは、エディタ側のエンコーディング設定を確認する話になる。症状としては似て見えるが、対処法は重ならない。
Macでも同じ問題は起きるか
GPU描画由来の文字化け（原因1）はmacOS版のVS Code / Cursor / Devin Desktopでも起こり得る。IME合成バグ（原因2）もOSに依存しない、ターミナルUIライブラリ側の問題なので、Windows/macOS/Linuxいずれでも起こる可能性がある。実際、報告されているIssueにはmacOS環境からのものも含まれている。
まとめ
「Claude Code 文字化け」で検索して出てくる記事の多くが「文字コードを見直しましょう」で止まっているのは、原因1（GPU描画）と原因2（IME合成バグ）を切り分けずに、ファイルの文字コード問題と混同しているケースが多いからだと思う。
表示が崩れるだけなら/terminal-setup一発で直る。入力中に文字が消えるなら、それはClaude Code側というよりターミナルUIライブラリの設計限界に近い話で、根本修正を待ちつつterminal-ime-proxyのような回避策でしのぐしかない。どちらのタイプかを見分けるところから始めるのが、遠回りに見えて一番早い。
