Shift+Enter in Claude Code inserts a newline without submitting your prompt—essential for writing multi-line code or complex queries. However, getting this key combination to work reliably through a terminal stack involving iTerm2 and tmux requires configuration at multiple layers.
This guide explains both the fix and the reasoning behind it.
If you just want it working, here's what you need:
Tested Configuration:
- macOS Tahoe 26.2
- zsh 5.9 (with
TERM=xterm-256color) - iTerm2 Build 3.6.6
- tmux 3.6a (invoked as
tmux -u)
Add these lines to your ~/.tmux.conf:
bind-key -n S-Enter send-keys Escape "[13;2u"
set -s extended-keys on
set -as terminal-features 'tmux-256color:extkeys'Then reload your tmux configuration:
tmux source-file ~/.tmux.conf- Open Settings → Profiles → Keys → Key Bindings
- Click the + button to add a new binding
- Set Keyboard Shortcut to Shift+Enter (press the keys)
- Set Action to "Send Escape Sequence"
- Set Esc+ value to
[13;2u
Run the terminal setup command inside Claude Code:
/terminal-setup
If Shift+Enter now inserts a newline instead of submitting, you're done. Read on to understand why each piece is necessary.
When you press Shift+Enter in most terminal applications, nothing special happens—it behaves exactly like Enter. This is because traditional terminal protocols don't distinguish between Enter and Shift+Enter. They both send the same byte: carriage return (ASCII 13).
Claude Code uses Shift+Enter as a distinct input for "insert newline without submitting." For this to work, the terminal must send a unique sequence that Claude Code can recognize.
Modern terminals solve the modifier key problem using CSI u encoding (also called "fixterms" or "libtermkey" encoding). Instead of sending a single byte, the terminal sends an escape sequence that encodes both the key and its modifiers.
The format is:
ESC [ <keycode> ; <modifier> u
For Shift+Enter:
- Keycode 13 (Enter/carriage return)
- Modifier 2 (Shift)
This produces: ESC [ 1 3 ; 2 u or written as an escape sequence: \e[13;2u
When Claude Code receives this sequence, it knows you pressed Shift+Enter specifically, not just Enter.
Understanding why multiple configurations are needed requires tracing a keypress through the stack:
┌──────────┐ ┌──────────┐ ┌──────────┐ ┌─────────────┐
│ Keyboard │ -> │ iTerm2 │ -> │ tmux │ -> │ Claude Code │
└──────────┘ └──────────┘ └──────────┘ └─────────────┘
Each layer can intercept, translate, or drop the key sequence:
- Keyboard → iTerm2: The OS delivers a "Shift+Enter" event to iTerm2
- iTerm2 → tmux: iTerm2 must translate this into an escape sequence and send it to the running process (tmux)
- tmux → Claude Code: tmux must pass the sequence through (or re-encode it) to the application running inside the pane
- Claude Code: Interprets the escape sequence and inserts a newline
If any layer fails to properly encode or forward the sequence, Claude Code just sees a regular Enter.
By default, iTerm2 may not send CSI u encoded sequences for Shift+Enter. The key binding explicitly tells iTerm2: "When Shift+Enter is pressed, send this exact escape sequence."
| Setting | Value |
|---|---|
| Keyboard Shortcut | Shift+Enter |
| Action | Send Escape Sequence |
| Esc+ | [13;2u |
Note: You enter [13;2u in the field—iTerm2 automatically prepends the ESC character.
tmux sits between iTerm2 and Claude Code, and by default it doesn't pass through extended key sequences. Three settings are required:
# Explicitly bind Shift+Enter to send the CSI u sequence
bind-key -n S-Enter send-keys Escape "[13;2u"
# Enable extended keys support in tmux
set -s extended-keys on
# Tell tmux that the terminal supports extended keys
set -as terminal-features 'tmux-256color:extkeys'Why all three?
bind-key -n S-Enter: Creates an explicit mapping at the tmux layer. The-nflag means "no prefix required"—this binding is always active.set -s extended-keys on: Enables tmux's extended keys mode, allowing it to recognize and generate CSI u sequences.set -as terminal-features: Informs tmux that your terminal type (tmux-256color) supports theextkeysfeature. The-asflag appends to existing features rather than replacing them.
The /terminal-setup command configures Claude Code's expectations for your terminal. Run it once after installation to ensure Claude Code is listening for the correct key sequences.
To confirm the escape sequence is arriving correctly, you can use cat to display raw input:
cat -vThen press Shift+Enter. You should see:
^[[13;2u
(^[ is how cat -v displays the ESC character)
If you see this output, your terminal stack is correctly configured. Press Ctrl+C to exit.
Terminal emulation carries decades of legacy. The VT100 terminal from 1978 established conventions still in use today, and those conventions predate the expectation that modifier keys would matter for most inputs.
Modern terminal applications like Claude Code need richer input handling, but they must work within an ecosystem where:
- Terminal emulators have varying levels of support for extended key encodings
- Multiplexers like tmux and screen add another translation layer
- Backward compatibility prevents aggressive changes to defaults
The CSI u encoding is a relatively recent solution (popularized around 2017) that's gaining adoption but isn't yet universal. Until it becomes the default everywhere, configurations like this remain necessary.
If you've successfully configured Shift+Enter for a different terminal setup (Alacritty, Kitty, WezTerm, etc.), consider sharing your configuration to help others.