[BUG] Documentation gap: EDITOR subprocess receives CSI-u mode 2

Preflight Checklist

• [x] I have searched existing issues and this hasn't been reported yet
• [x] This is a single bug report (please file separate reports for different bugs)
• [x] I am using the latest version of Claude Code

What's Wrong?

Claude Code enables CSI-u keyboard mode 2 (ESC [ > 4 ; 2 m) for its own key handling,
but does not document this behaviour or its implications for terminal editors invoked via
the EDITOR environment variable.

When running inside tmux, CSI-u mode 2 is inherited by the subprocess spawned via
EDITOR (tested with emacsclient -nw -c). In mode 2, every keypress is encoded as a
CSI-u sequence. Emacs is not equipped to decode all CSI-u sequences, so keypresses
produce garbled output in the editor buffer instead of their expected actions.

For example, pressing C-x in Emacs causes ;5u to be inserted as literal text rather
than executing the C-x prefix command.

This does not reproduce outside tmux (tested: running Claude Code directly in WezTerm).

What Should Happen?

Claude Code should document that it enables CSI-u keyboard mode 2 and explain the
implications for users who invoke terminal editors via EDITOR. The documentation should
recommend wrapping the editor binary in a shim that resets CSI-u mode before launch and
restores it after exit. This is a simple, robust, user-side solution that requires no
upstream fix and works regardless of terminal emulator or multiplexer.

Example shim (e.g. saved as ~/.local/bin/emacsclient ahead of the real binary on PATH):

#!/bin/sh
printf '\e[>4;0m'    # reset CSI-u mode before handing off terminal
emacsclient -nw -c "$@"
printf '\e[>4;2m'    # restore CSI-u mode 2 for Claude Code

Error Messages/Logs

No error messages. The symptom is garbled input in the editor: Ctrl+key combinations
produce literal text like `;5u` or `1;5u` in the buffer instead of executing commands.

Raw terminal capture (via `script`) confirming Claude Code enables CSI-u mode 2 on startup:


00000890: 3034 681b 5b3e 3175 1b5b 3e34 3b32 6d1b  04h.[>1u.[>4;2m.


Sequences confirmed emitted by Claude Code:
- `ESC [ > 1 u` — interpreted as: push Kitty keyboard protocol state (not tested)
- `ESC [ > 4 ; 2 m` — enable CSI-u mode 2 (all keys encoded as CSI-u)

Steps to Reproduce

1. Configure tmux with set -g extended-keys on in tmux.conf.
2. Set EDITOR=emacsclient -nw -c (or any terminal editor that uses legacy key encoding).
3. Start a tmux session and run Claude Code inside it.
4. Press the keyboard shortcut to open the editor buffer (e.g. Ctrl+G).
5. In the editor, press any Ctrl+<letter> key (e.g. C-x).
6. Observe garbled output (e.g. ;5u) inserted into the buffer instead of the expected action.

Claude Model

None

Is this a regression?

I don't know

Last Working Version

2.0.x

Claude Code Version

2.1.84 (Claude Code)

Platform

Anthropic API

Operating System

macOS

Terminal/Shell

Other

Additional Information

Is This a Regression?

Not a strict regression — CSI-u support is a welcome addition introduced in version 2.1.0
(2026-01-07), confirmed via CHANGELOG git history. The missing piece is documentation
explaining what Claude Code does to the terminal and what users need to do to make their
EDITOR setup work correctly alongside it.

Environment: WezTerm (outer terminal) → tmux → Claude Code → emacsclient.

Why tmux behaves differently from direct terminal emulators (conjectured; not fully tested):

tmux does not support the Kitty keyboard protocol (confirmed). The push/pop stack
(ESC [ > 1 u / ESC [ < u) that Claude Code appears to use to save and restore
keyboard state is therefore presumably not honoured by tmux. However, tmux does
independently track CSI-u mode via its extended-keys feature. The conjecture is that
when Claude Code sends ESC [ < u to pop the Kitty state before spawning EDITOR, tmux
ignores it, leaving ESC [ > 4 ; 2 m active for the pane, which the editor subprocess
then inherits.

Why direct terminal emulators are not affected is not known — it was observed but not
investigated.

Why a code fix from Claude Code's side is not straightforward (conjectured; not tested):

A proper fix would require Claude Code to query the prior CSI-u mode (ESC [ > 4 m)
before enabling mode 2, then restore it when spawning EDITOR. However, tmux does not
currently support the CSI-u mode query (confirmed: a proposal to add this to tmux was
partially rejected). Claude Code does emit ESC [ > 4 m on startup (visible in the raw
capture), but whether it reads and acts on the response is unknown. The shim approach
sidesteps this problem entirely.

Environment:

• Claude Code version: 2.1.84
• Outer terminal emulator: WezTerm (running tmux inside it)
• Multiplexer: tmux with extended-keys on
• OS: macOS 15 (Darwin 25.3.0)