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

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

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の通知設定で扱っています。

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

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

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

# Ghosttyの設定ファイル(~/.config/ghostty/ 配下)
macos-option-as-alt = true

Ghosttyの設定リファレンスによると、値はtrue / false / left / rightです。leftとrightは、左右どちらかのOptionだけをAltとして扱います。未設定のときの既定値はキーボードレイアウト次第で、U.S. StandardとU.S. Internationalではtrue、それ以外ではfalseです。日本語配列など別のレイアウトを使っていてOption+Pが反応しないなら、この既定値の違いが疑わしい点です。

トレードオフもあります。trueにすると、Optionキーで入力していたUnicode文字(米国配列のOption+bで出る「∫」など)は入力できなくなります。記号入力を優先するならleftかrightで片側だけを割り当てる手があります。iTerm2側の同じ設定はiTerm2のOption keyとクリップボードにあります。

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です。~/.claude/keybindings.jsonに別のキーを割り当てます。

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

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

なお、公式の一覧では画像貼り付けはCtrl+VまたはCmd+V(iTerm2)と書かれています。Cmd+Vでの画像貼り付けはiTerm2向けの記載で、Ghosttyの項目はありません。

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が有効なときだけ起きる

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

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

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

報告者が提案している確認方法は単純です。貼り付けた直後に、入力欄のVim mode表示を見てください。NORMALになっていれば、仮説どおりの挙動です。INSERTのままでも送信されるなら、別の要因を疑うことになります。

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

• 貼り付けたあとの改行は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での不具合を見分ける順番

症状が出たら、次の順で見ると切り分けが早くなります。

1. 症状がGhostty固有か確認する。iTerm2やTerminal.appで再現するなら、ターミナルの問題ではない
2. keybindings.jsonと、Ghosttyの設定ファイルにキーバインドの独自設定が無いか確認する
3. Claude Codeのバージョンを確認する。Ctrl+Vの件は2.1.284で報告されている
4. issueのstate(open / closed)と、修正バージョンの記載を見る

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