この記事は何
皆さんは、ターミナルのマルチプレクサに何を使っていますか？
僕はこれまで、Wezterm の上で Zellij を使ってペインやタブを管理していたのですが、最近 herdr というツールに乗り換えてみました。
ところが、herdrに乗り換えたところ、どうもうまく操作ができない場面に出くわしました。具体的には「ESCキーが効かない」という問題です。Zellijを使っていたときには起きなかったので、少し腰を据えて調査をしてみました。
この記事は、その調査でわかった原因と対処法をまとめたものです。結論だけ先に言ってしまうと、Weztermの enable_kitty_keyboard を false にすることで解決しました。
この記事は執筆時点（2026年7月）の情報をもとにしています。herdrやWezterm側のアップデートによって、挙動や対応状況が変わる可能性があります。
Weztermとは
Weztermは、Wez Furlong氏が開発しているターミナルエミュレータです。
主な特徴としては、以下のようなものが挙げられます。
- GPUアクセラレーションによる高速な描画
- Luaによる柔軟な設定
- Windows / macOS / Linux に対応したクロスプラットフォーム
- Rust製
設定をすべてLuaで書けるのが特徴で、~/.wezterm.lua に設定を書いていくスタイルです。プログラマブルに細かくカスタマイズできるので、こだわり派の方に人気のターミナルですね。
herdrとは
herdrは、ターミナルマルチプレクサ的なツールです。ターミナルマルチプレクサというのは、tmuxやZellijに代表される、1つのターミナルの中でペインを分割したり、複数の画面（セッション）を管理したりできるツールのことです。
herdrもそうしたツールの1つで、僕は今回、これまで使っていたZellijの代わりとして導入してみました。乗り換え自体はスムーズだったのですが、使い始めてすぐに次のような問題に気づくことになります。
Wezterm上でherdrを使っていて困ったこと
herdrを使い始めてすぐ、ESCキーが効かないことに気づきました。
ESCキーはVimでノーマルモードに戻るときをはじめ、いろいろな場面で使うキーです。それが効かないとなると、なかなかにストレスが溜まります。しかも、Zellijを使っていたときにはまったく問題がなかったので、herdrに乗り換えたことが引き金になっているのは明らかでした。
「herdr側の設定の問題かな？」と思っていろいろ探ってみたのですが、どうやら原因はherdr単体ではなく、Weztermとの組み合わせにありました。
原因: Kitty Keyboard Protocol
原因は、キーボードの入力方式（キーボードプロトコル）にありました。
Weztermには enable_kitty_keyboard という設定があり、これを true にすると「Kitty Keyboard Protocol」というキーボードプロトコルが有効になります。
昔ながらのターミナルでは、キー入力はシンプルな方式でエンコードされて送られます。ただ、この方式にはいくつか曖昧さがあります。たとえばESCキーは 0x1B という1バイトのコードとして送られるのですが、これは矢印キーやファンクションキーといった「エスケープシーケンスの始まり」を表すバイトと同じです。そのため、送られてきた 0x1B が「ESCキーそのもの」なのか「エスケープシーケンスの始まり」なのか、区別がつきにくいという問題があります。
Kitty Keyboard Protocolは、こうした曖昧さを解消するための拡張プロトコルです。これを有効にすると、ESCキーのようなキーが、他と区別できる専用のエスケープシーケンス（たとえば CSI 27 u のような形式）として送られるようになり、より正確にキーを識別できるようになります。
問題は、この新しいエンコーディングに対応していないアプリケーションに、この形式でESCが送られてきたときです。受け取った側はESCの入力を正しく解釈できず、結果として「ESCキーが効かない」ように見えてしまいます。今回のケースでは、herdr側がこのエンコーディングに対応しきれていないためか、ESCキーが効かなくなっていたようです。
Zellijで問題が起きなかったのは、Zellij側がこのプロトコルに対応していた（あるいは影響を受けない形で扱っていた）ためだと考えられます。
なお、同じような問題はherdrのリポジトリでもIssueとして報告されています。
ちなみに、この手の問題はherdrに限った話ではなく、Kitty Keyboard Protocolに対応していないTUIアプリでは起こりうるものです。
対処法: enable_kitty_keyboard を false にする
対処法はシンプルで、Weztermの設定で enable_kitty_keyboard を false にするだけです。
local wezterm = require 'wezterm'
local config = wezterm.config_builder()
-- Kitty Keyboard Protocol を無効にする
config.enable_kitty_keyboard = false
return config
すでに設定ファイルを持っている場合は、config.enable_kitty_keyboard = false の一行を足すだけで大丈夫です。設定を反映させれば、herdr上でもESCキーが効くようになるはずです。
enable_kitty_keyboard の既定値は false なので、そもそも明示的に設定していなければこの問題は起きません。裏を返すと、この問題に遭遇したということは、どこかで enable_kitty_keyboard = true を設定しているはずです。NeovimなどのTUIアプリで、より高度なキー入力を扱うためにあえて有効にしている方は、心当たりがあるかもしれません。
設定の詳細は公式ドキュメントも参照してみてください。
enable_kitty_keyboard を false にすると、Wezterm単体で使う場合に Kitty Keyboard Protocol の恩恵が受けられなくなります。具体的には、Ctrl系やShift系の組み合わせをより細かく区別するといった、高度なキー入力の識別ができなくなります。NeovimなどのTUIアプリで、この機能を前提にしたキーバインドを組んでいる場合は、逆に不便になることもあります。ご自身の環境で何を優先したいかを天秤にかけて設定してみてください。
最後に
今回は、Wezterm上でherdrを使うときにESCキーが効かなくなる問題と、その対処法を紹介しました。改めて整理すると、以下のようになります。
- 原因はWeztermの
enable_kitty_keyboard（Kitty Keyboard Protocol） - herdrがこのプロトコルのキーエンコーディングに対応しきれていないため、ESCキーが効かなくなる
-
enable_kitty_keyboardをfalseにすることで回避できる - ただし、Wezterm単体での高度なキー入力の識別とはトレードオフになる
現状ではherdr側でこのプロトコルへの対応がされていないようなので、enable_kitty_keyboard を false にして回避するのが現実的な対処法です。今後herdr側で対応が入って、enable_kitty_keyboard を有効にしたままでも快適に使えるようになることに期待したいところです。
同じようにWezterm + herdr でESCキーが効かずに困っている方の助けになれば幸いです。最後までお読みいただきありがとうございました。