Claude CodeをGhosttyで使うときの設定と既知の症状

Ghosttyは、Claude Code側が名前を挙げて対応しているターミナルの1つです。Shift+Enterの改行、デスクトップ通知、リンクのクリックは設定なしで動きます。手を入れるのはOptionキーと、tmux越しに使うときの3行くらいです。一方でGitHubには、Ctrl+Vの画像貼り付け、Vim mode後のShift+Enter、macOSのfd上限の案内という3件の症状が報告されています。3件とも、いまもopenのままです。

Ghosttyで設定なしに動くClaude Codeの機能

公式ドキュメントがGhosttyを名指ししている機能は次のとおりです。

Shift+Enterは、/terminal-setupを実行する必要がありません。VS CodeやZedと違い、ターミナル側の設定ファイルを書き換える手順は要らないのです。ターミナル別の対応表はClaude Code複数行入力に、/terminal-setupの挙動はterminal-setupコマンドでShift+Enterが効かないときの対処にあります。

通知だけは、Ghostty専用のチャンネルも用意されています。

{
  "preferredNotifChannel": "ghostty"
}

"auto"のままでもGhosttyでは通知が届くため、この指定が要るのは他のチャンネルを明示していたときの切り替え用です。通知全般の設計はClaude Codeの通知設定で扱っています。

Ghostty向けの修正が入ったバージョン

Ghosttyは、changelogに名前が繰り返し出てくるターミナルです。症状が出た環境のClaude Codeが次のバージョンより古いなら、先にアップデートで解消するか試せます。

Optionキーを効かせるにはGhostty側の設定を見る

Option+EnterやOption+P(モデル切り替え)のようなOption系のショートカットは、OptionをMeta(Alt)として送る設定が前提です。Claude Codeのドキュメントは、Ghosttyについて「ターミナルの設定ファイルでOption-as-Alt系の項目を探す」とだけ案内しています。

Ghosttyでこの項目に当たるのがmacos-option-as-altです。

# Ghosttyの設定ファイル
macos-option-as-alt = true

未設定のときの既定値はキーボードレイアウト次第で、U.S. StandardとU.S. Internationalではtrue、それ以外ではfalseです。日本語配列など別のレイアウトを使っていてOption+Pが反応しないなら、この既定値の違いが疑わしい点です。

iTerm2側の同じ設定はiTerm2のOption keyとクリップボードにあります。

tmuxの中でGhosttyを使うとShift+Enterが送信になる

Ghostty自体はShift+Enterに対応していても、Claude Codeをtmuxの中で動かすと状況が変わります。公式ドキュメントによると、tmux内では既定でShift+Enterが改行ではなく送信になり、デスクトップ通知と進捗バーも外側のターミナルに届きません。

~/.tmux.confに次の3行を足し、tmux source-file ~/.tmux.confで反映します。

set -g allow-passthrough on
set -s extended-keys on
set -as terminal-features 'xterm*:extkeys'

1行目が通知と進捗バーをtmuxの外へ通し、2・3行目がShift+Enterと素のEnterをtmuxに見分けさせます。ここまでやってもShift+Enterが効かないときは、tmuxを介さない素のGhosttyで再現するかを見ると、原因がGhostty側かtmux側かが分かれます。

Ctrl+Vで画像が貼れない症状

2026年9月29日に、Ghostty上でCtrl+Vの画像貼り付けが効かないというissue(#98029)が立ちました。報告の内容は短く、次のとおりです。

• 環境はmacOS(darwin)、ターミナルはGhostty、Claude Codeは2.1.284
• クリップボードにはPNGf形式(macOSのクリップボード上のPNG画像データ)が入っている
• 2.1.284でCtrl+Vの画像貼り付けが効かなくなった、という書き方

ラベルはbug / platform:macos / area:tuiで、状態はopenです。再現手順やエラーログはなく(エラー欄は空の配列)、原因の分析も書かれていません。「2.1.284で止まった」という以上のことは、issueからは読み取れません。

効かないときの切り分けと代替手段

Claude Codeの画像入力には、Ctrl+V以外にも経路があります。公式ドキュメントが挙げているのは3つです。

1. ウィンドウに画像をドラッグ&ドロップする
2. 画像をコピーしてCtrl+Vで貼り付ける
3. 「Analyze this image: /path/to/your/image.png」のように、パスを文章で渡す

Ctrl+Vが効かないあいだは、1か3に逃がせます。パス指定はクリップボードを使わない入力経路なので、今回の症状とは切り離して使えます。

もう1つ、キーバインドの割り当てを変えて切り分ける手があります。画像貼り付けのアクション名はchat:imagePasteで、既定はCtrl+V(WindowsとWSLではAlt+V)です。~/.claude/keybindings.jsonに別のキーを割り当てます。

{
  "bindings": [
    {
      "context": "Chat",
      "bindings": {
        "alt+v": "chat:imagePaste"
      }
    }
  ]
}

これで貼り付けが通るなら、原因はCtrl+Vというキーの受け渡し側にあります。通らないなら、クリップボードの画像データを読む処理側の問題です。この割り当てで実際に直るかどうかはissueに書かれておらず、あくまで切り分けの手段です。macOSでalt+vを使うときは、OptionをAltとして送る設定(前節)が効いている必要があります。キーバインドの変更は、保存すると自動で検出されて反映され、再起動は要りません。複数キーの連続入力を含む書き方はClaude Codeのkeybindingsでchordを組むにあります。

公式の一覧が画像貼り付けに挙げるのは、Ctrl+V、iTerm2のCmd+V、Windows・WSLのAlt+Vです。GhosttyのCmd+Vは載っていません。

Vim mode後のShift+Enterが送信になる症状

editorModeを"vim"にしているときに、貼り付けたあとのShift+Enterが改行ではなく送信になることがあります(#88377)。報告者の環境はGhostty 1.3.2(開発版)、macOS 15.6、Claude Code 2.1.237です。Ghosttyの設定はfont-family・font-size・working-directoryだけで、keybindings.jsonも無い素の状態でした。

報告に書かれた特徴は3つあります。

• 貼り付けが必須で、手入力だけなら毎回改行になる
• 貼り付けたあとは間欠的で、改行になる回も送信になる回もある
• Vim modeを有効にした環境で起きている(Vim modeを切った状態は試されていない)

送信されるとプロンプトが空になり、書きかけの入力が送られてしまいます。取り消しはできません。ラベルにはhas reproとstaleが付いています。

原因は確定していません。報告者は、貼り付けが終わるとエディタがINSERTからNORMALに移り、その状態のShift+Enterが送信経路に入るのではないか、という仮説を「未検証」と断ったうえで書いています。もう1つの仮説は、貼り付けが[Pasted text #N +M lines]のプレースホルダーに折りたたまれた状態が関係する、というものです。折りたたみの条件は「800字超、または3行超」で、公式ドキュメントの記述と一致します。

貼り付け直後にモードを見る

報告者は、貼り付けた直後に入力欄のVim mode表示を見て、NORMALになっているかを確かめるよう提案しています。NORMALなら、間欠的ではなく毎回起きる挙動だと切り分けられます。

回避の選択肢は、公式ドキュメントで動作が保証されているものから選びます。

• 貼り付けたあとの改行はCtrl+Jか、\を打ってからEnterにする。どちらも「どのターミナルでも設定なしで動く」と明記されています
• /configのEditor modeを一時的にnormalへ戻す
• chat:newline(既定はCtrl+J)を、手に馴染む別のキーへ割り当てる

Vim mode自体の操作はClaude CodeのVim modeにまとめてあります。貼り付けた内容の扱いはClaude Codeの貼り付けテキストの注入対策も参照してください。

macOSのfd上限の案内でターミナルが固まる

3件目はGhostty固有ではなく、Terminal.appでも起きる報告です(#96603)。ただしGhosttyの新規ウィンドウも巻き込まれるため、Ghosttyユーザーは知っておく価値があります。

報告によると、Claude Codeがファイル記述子のエラーに遭うと、同梱のBunが次のコマンドを実行するよう案内します。

ulimit -n 2147483646
sudo launchctl limit maxfiles 2147483646

案内に従うとシステム全体の上限が約21億になります。macOSの/usr/bin/loginは、シェルを起動する前に取りうる記述子をすべて閉じにいくため、以後は新しいTerminal.appやGhosttyのウィンドウが約3分間、CPU 100%のまま空白になる、というのが報告者の観察です。SIPの制約で上限を再び下げることもできず、元に戻せたのは再起動だけだったと書かれています。報告時の環境はGhostty 1.3.1、macOS 26.5.1、Claude Code 2.1.281(native)です。

根本原因と修正案はBun側(oven-sh/bun#37337)にあり、修正のPRも同じ側で出ています。Claude Codeでfd関連のエラーが出て、この案内文が表示された場合は、sudo launchctl limit maxfilesのコマンドをそのまま実行しないでください。エラー自体の原因は別に調べる形になります。

Ghosttyでの不具合を見分ける順番

スクロールバックや画面の描画に関する症状は、ターミナルを問わず起きるものがあります。Claude Codeでスクロールバックが消える問題にGhostty環境の報告も含めて書いています。