<S-CR> and other CSI u in CLI Coding Agent with tmux enabled

[S1M0N38]

I had the problem that the pi coding agent support CSI u for parsing keymaps (e.g. <S-CR> for new lines, <M-CR> for follow up message, ...) but using the default sidekick with tmux enabled in mux config was not working correctly.

Trying to debug issues about escape sequence transmission between Terminal (Wezterm in my case), Tmux (multiplexer outside), Neovim, Neovim terminal buffer, tmux (inside neovim terminal buffer) and pi (the coding agent) can be a bit hard.

The following is my config collection that I've tested in these two cases

• wezterm -> neovim -> sidekick.nvim + tmux
• wezterm -> tmux -> neovim -> sidekick.nvim + tmux

---

Terminal Emulator

If you are on another terminal like Ghostty or Kitty, maybe some of these are working out of the box (or maybe it required some config). In any case at the end you should be able to run successfully the tests with Ctrl V in neovim.

The first thing to configure is the terminal emulator (Wezterm in my case)

~/.config/wezterm/wezterm.lua

local config = wezterm.config_builder()
config.term = "wezterm"
config.enable_kitty_keyboard = true
config.keys = {
  { key = "Enter", 
    mods = "ALT", 
    action = wezterm.action({ SendString = "\x1b[13;3u" }) 
  } -- This disable wezterm full screen default mapping
}

This configure the $TERM env var to be wezterm (so other CLI/TUI apps knows about the terminal emulator capabilities) and enable kitty keyboard (which enable support for CSI u in wezterm, for example when you send Ctrl + Enter the escape sequence \x1b[13;5u is sent).

We also need to make our system aware which are the wezterm capability:

1. download: curl -o wezterm.terminfo https://raw.githubusercontent.com/wez/wezterm/main/termwiz/data/wezterm.terminfo
2. compile: tic -x wezterm.terminfo
3. verify: infocmp wezterm

Testing

You can test that you have setup your terminal emulator for CSI u by opening a empty Neovim terminal buffer and type in INSERT mode Ctrl V followed by a key combo. Using Crtl V in INSERT mode, enter a special insert mode where the key combo are translated in neovim format. For example you should see:

• Crtl + Enter -> <C-CR>
• Alt + Enter -> <M-CR>
• Alt + Ctrl + Shift + Enter -> <M-C-S-CR>

(M is for meta, C is for control, S is for shift, CR is for Carriage Return aka Enter, ...)

---

Tmux

Then we need to configure tmux. It's important to be on version 3.6a or above (see by running tmux -V) because there are some issue related to CSI u in version 3.5 and below. So update it if you need it.

set -s extended-keys always
set -g extended-keys-format csi-u

set -as terminal-features 'xterm*:extkeys'

# Here im using wezterm because in the previous step with have defined
# $TERM to be `wezterm`. Other terminal required different values.

set -as terminal-features 'wezterm*:extkeys' 

set -g default-terminal "tmux-256color"
set -g allow-passthrough on

---

Sidekick.nvim

Now it's time to configure sidekick.nvim. I think that there is a issue about the implementation of the neovim terminal buffer (i.e. where the sidekick agent is run) which does not support fully the CSI u. So the transmission of keycombo (e.g. Shift-CR) is not perform in the right way and the coding agent does not recive the right escaping seq to perform the expected action (e.g. adding a new line in the prompt).

The following workaround in the sidekick.nvim should fix this by sending the full CSI u instead of the one automatically generated

return {
  "folke/sidekick.nvim",
  opts = {
    cli = {
      win = {
        keys = {
          shift_cr = { "<S-CR>", function(self)
            if self:is_running() then
              vim.api.nvim_chan_send(self.job, "\x1b[13;2u")
            end
          end, mode = "t", desc = "CSI-u Shift+Enter" },
          alt_cr = { "<A-CR>", function(self)
            if self:is_running() then
              vim.api.nvim_chan_send(self.job, "\x1b[13;3u")
            end
          end, mode = "t", desc = "CSI-u Alt+Enter" },
        },
      },
      mux = {
        backend = "tmux",
        enabled = true,
      },
    },
  },
}

Here I've defined two keymaps that maps the Shift + Enter and Alt + Enter to the corresponding CSI u escape sequence (which the rest of the config is based on). You can define other keys as well.