macでtmuxのキーバインドが　日本語入力中に効かない問題を解決した話。

最近、macOSでtmuxを使っていて、めちゃくちゃイライラする問題にハマってしまいました。

日本語入力モード（IME ON）のときにtmuxのキーバインドが効かないんですよ。

具体的には、tmuxのprefix（自分の場合はControl+t）は普通に認識されるんですが、その後のコマンドキー（nとか m、h、j、k、l など）を押すと、日本語入力の候補が表示されてしまって、結果としてtmuxのキーバインドが発火しないという状況です。

例えば、Control-t n の次のウィンドウへの移動をやろうとしたが日本語入力として認識されて、「の、内容、なんか...」みたいな変換候補が表示されてしまうんですよね。

そのときは、一度IMEをオフにして再度キーバインドを実行するのですが、地味にストレスが溜まります。。

なぜこの問題が起きるのか？AIに聞いた感じだと、macOSでは、キー入力の処理順序が以下のようになっているとのことです：

IME（日本語入力システム）
ターミナルアプリ（Ghostty、iTerm2など）
tmux
シェル（zsh、bashなど）

つまり、日本語入力モードになっていると、IMEがキー入力を先に処理してしまうため、ターミナルアプリやtmuxにキーが届かないんです。

解決方法：Karabiner-Elementsでサクッと解決

いろいろAIに調べてもらったら、OSレベルでキー入力をフックする必要があるということがわかりました。

そこで、Karabiner-Elementsを使うことにしました。

Karabiner-Elementsとは

Karabiner-Elementsは、macOSでキーボードのカスタマイズを行うための強力なツールです。OSレベルでキー入力を処理できるため、遅延なくIMEを制御できるのが大きなメリットですね。

手順

Karabiner-Elementsをインストール
設定ファイルを作成
設定を有効化

1. Karabiner-Elementsをインストール

まずはインストールから。Homebrewで簡単にインストールできます：

  $ brew install --cask karabiner-elements

インストール後、Karabiner-Elementsアプリを起動して、必要な権限（アクセシビリティ、入力監視）を付与してください。

2. 設定ファイルを作成

以下の内容で設定ファイルを作成しましょう。

ファイルパス: ~/.config/karabiner/assets/complex_modifications/ghostty_tmux_ime.json

  {
    "title": "Ghostty tmux IME control",
    "rules": [
      {
        "description": "Ghosttyでcontrol+t押下時にIMEをオフにする",
        "manipulators": [
          {
            "type": "basic",
            "conditions": [
              {
                "type": "frontmost_application_if",
                "bundle_identifiers": [
                  "^com\\.mitchellh\\.ghostty$"
                ]
              }
            ],
            "from": {
              "key_code": "t",
              "modifiers": {
                "mandatory": [
                  "control"
                ]
              }
            },
            "to": [
              {
                "key_code": "japanese_eisuu"
              },
              {
                "key_code": "t",
                "modifiers": [
                  "control"
                ]
              }
            ]
          }
        ]
      }
    ]
  }

※ 上記はghosttyというターミナルアプリを使っている場合で、他のターミナルアプリを使用している場合は下記で修正方法を説明しています。

※ tmuxのキーバインドのprefixがCtrl+tにしているのでこの設定になっていますが、たぶんほとんどの方は別のprefixにしていると思うので、tのところを変更してください

3. 設定を有効化

設定ファイルを作成したら、Karabiner-Elementsアプリで有効化します：

Karabiner-Elementsアプリを開く
Complex Modifications タブを選択
Add predefined rule ボタンをクリック
Ghostty tmux IME control の "Ghosttyでcontrol+t押下時にIMEをオフにする" を Enable にする

これで設定は完了です！

設定の説明

この設定は以下のように動作します：

Ghosttyがアクティブなときのみ動作（bundle_identifiersで制限）
Control-t が押されると：
- まず japanese_eisuu（英数キー）を送信してIMEをオフにする
- その後、Control-t をtmuxに送信
結果として、次の n や m などのキーが英数モードで入力される

という感じで、遅延なくIMEを制御できるようになります。

他のターミナルアプリを使っている場合

自分はGhosttyを使っているんですが、iTerm2やAlacrittyなど、他のターミナルアプリを使用している場合は、bundle_identifiers を変更すればOKです。

iTerm2の場合:

  "bundle_identifiers": [
    "^com\\.googlecode\\.iterm2$"
  ]

Alacrittyの場合:

  "bundle_identifiers": [
    "^org\\.alacritty$"
  ]

Bundle Identifierは、Karabiner-ElementsのEventViewerでアプリを切り替えると確認できます。

tmuxのprefixキーが異なる場合

tmuxのprefixを Control-b や Control-a など別のキーに設定している場合は、設定ファイルの key_code を変更してください。

Control-bの場合:

  "from": {
    "key_code": "b",
    "modifiers": {
      "mandatory": ["control"]
    }
  }

  "to": [
    {
      "key_code": "japanese_eisuu"
    },
    {
      "key_code": "b",
      "modifiers": ["control"]
    }
  ]