Claude Code ガイド

Appearance

原文（日本語に翻訳） ​

ターミナル通知が送信された際にiTerm2 + tmux環境で発生するターミナル表示の崩れ（ランダムな文字、入力のずれ）を修正しました。

原文（英語） ​

Fixed terminal display tearing (random characters, drifting input) in iTerm2 + tmux setups when terminal notifications are sent.

概要 ​

Claude Code v2.1.111では、iTerm2とtmuxを組み合わせた環境で長時間の処理完了通知が送信された際に発生していた表示崩れ（ランダムな文字の表示、入力カーソルのずれ）が修正されました。この問題はiTerm2の通知機能とtmuxのエスケープシーケンス処理の不整合によって引き起こされていました。

基本的な使い方 ​

この修正はiTerm2 + tmux環境を使用しているユーザーに自動的に適用されます。特別な設定変更は不要です。

影響を受けていた環境 ​

  • macOSのiTerm2ターミナル
  • tmuxセッション内でClaude Codeを実行
  • Claude Codeの通知機能が有効な状態

修正前に発生していた症状 ​

# 長い処理（コード生成、ファイル解析等）の完了後：
# - ランダムな文字が画面に表示される
# - プロンプト入力位置がずれる
# - 画面の一部が正常に表示されなくなる

実践例 ​

長時間タスク後の安定動作確認 ​

bash
# tmuxセッションを開始
tmux new-session -s claude-session

# Claude Codeで長時間タスクを実行（修正前は完了後に表示崩れが発生していた）
claude "このリポジトリ全体のセキュリティ監査を実施してください"

# v2.1.111以降：通知送信後も画面が正常に表示される

通知が送信されるタイミング ​

# 以下の場合にターミナル通知が送信される：
# - 長時間の処理が完了した場合
# - エラーが発生した場合
# - ユーザーの注意が必要な場合

# これらの通知送信後もiTerm2 + tmux環境で正常に動作するようになった

tmuxと組み合わせた開発ワークフロー ​

bash
# 複数のtmuxウィンドウでClaude Codeを並行実行する場合
# 変更前：一方のウィンドウの通知が他方の表示を崩すことがあった
# 変更後：各ウィンドウが独立して正常に動作する

# ウィンドウ1でコードレビュー
tmux new-window -n review
claude "このコードをレビューしてください"

# ウィンドウ2でテスト生成
tmux new-window -n tests
claude "テストケースを生成してください"

問題が継続する場合の対処法 ​

# v2.1.111でも表示崩れが発生する場合：
# 1. Ctrl+L で画面を再描画（v2.1.111で強化済み）
# 2. tmuxのrefresh-clientを実行：Ctrl+b r
# 3. Claude Codeを再起動

注意点 ​

  • この修正はiTerm2 + tmuxの組み合わせに特化した修正です。他のターミナルエミュレータ（Terminal.app、WezTermなど）では別の動作をする可能性があります
  • tmuxを使用していない場合（iTerm2を直接使用）は、この特定の問題の影響を受けていませんでした
  • Claude Codeの通知機能は設定で無効化することもできます（問題が解決しない場合の回避策として）
  • Ctrl+Lが強化されてフル画面再描画を行うようになったことも、この問題の軽減に役立ちます

関連情報 ​