feat(cli): add CSI-u key forwarding for modified special keys (e.g. <S-CR>)

[S1M0N38]

Description

Introduce a bool flag in cli.win.csiu to force csi-u escape sequences. After testing across various envs I found out that explicitly forcing csi-u when cli.mux.backend="tmux". I had this setup working in Wezterm with some custom config (see discussion 295). When using Ghostty close to no config is required (on mac os you have to force alt to behave as meta key e.g. macos-option-as-alt = left).

I've tested this new option with the following coding agents running lazyvim with sidekick extra enabled in ghostty terminal emulator (not inside a tmux session - the only tmux session are the ones spawned by sidekick.nvim)

• agy (by Google - gemini-cli was discontinued for non-enterprise users) ✅
• claude code (by Anthropic) ✅
• pi (by earendil-works) ✅
• codex (by OpenAI) ✅
• copilot (by GitHub) ✅
• opencode (by Anomalyco) ✅
• agent (by Cursor) ❌

The agent CLI by cursor in not really optimized for tmux, from their docs:

If you're in tmux or having trouble with other keybindings, Ctrl+J is the most reliable option.

Configuration

The config that I've use was the following

opts = {
  nes = { enabled = false },
  cli = {
    mux = {
      backend = "tmux",
      enabled = true,
    },
    win = {
      csiu = true, -- this is the new option
      keys = {
        prompt = false, -- Disable <c-p> for opening prompts
      },
    },
  },
}

Related Issue(s)

No issue. Just a workaround in discussions #295

Additional Notes

The code in this PR was generated with AI, tested manually and iteratively refined. I think this issue regarding escape seq between various layers of the stack can be somewhat hard to for a user to debug (keyboard -> terminal emulator -> nvim terminal -> tmux -> coding agent). Maybe having the option to enabled the usage of CSI-u could beneficial.

I think that the failure point is when the nvim terminal emulator try to interpret the escape sequence and it's not related to sidekick.nvim specifically. Maybe this issue will be solved if/when libghostty-vt will replace the current vterm (hopefully to be more spec-comply).

If this PR is out of the scope of this project, feel free to close this PR without additional comments.

[Copilot]

Pull request overview

Adds an opt-in cli.win.csiu configuration to forward modified special keys (e.g. <S-CR>) to agent CLIs using CSI-u escape sequences, and ensures tmux sessions spawned by Sidekick can pass CSI-u through when enabled.

Changes:

• Introduces cli.win.csiu config flag and injects default CSI-u keymaps into cli.win.keys when enabled.
• Adds tmux session option injection (extended-keys, extended-keys-format csi-u) gated by cli.win.csiu.
• Adds a dedicated CSI-u module plus test coverage for keymap bytes, tmux option segments, and config keymap injection behavior.

Reviewed changes

Copilot reviewed 4 out of 4 changed files in this pull request and generated 1 comment.

File	Description
tests/csiu_spec.lua	New tests covering CSI-u byte sequences, tmux option injection, and config-driven keymap injection.
lua/sidekick/config.lua	Adds cli.win.csiu option + injects CSI-u default keymaps during Config.setup().
lua/sidekick/cli/session/tmux.lua	Adds M.options() to append tmux extended-keys options when CSI-u is enabled.
lua/sidekick/cli/csiu.lua	New module defining default CSI-u forwarding keymaps and their terminal-job send behavior.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.