NeilandOrca
eb92ba9448
Orca's terminal already encodes Shift+Enter as the kitty CSI-u sequence `\x1b[13;2u`, but without `vtExtensions.kittyKeyboard` xterm.js never answers the `CSI ? u` probe. CLIs that gate enhanced input on that handshake (Claude Code, Codex, etc.) therefore drop the extended bytes and treat Shift+Enter as a plain Enter — most visibly when running inside tmux, which strips extended-key encodings by default. - Enable `vtExtensions.kittyKeyboard` in the default terminal options (matches VS Code's xtermTerminal). - Lock in the flag with a regression test in pane-lifecycle.test.ts. - Add docs/terminal-extended-keys.md explaining the Orca side and the tmux-side `set -s extended-keys on` + `terminal-features xterm*:extkeys` users need for nested Shift+Enter to reach a CLI. Verified end-to-end in Electron: `cat -v` + Shift+Enter now prints `^[[13;2u`, and `printf '\e[?u'` elicits the expected `CSI ? 0 u` reply from xterm.js. Co-authored-by: Orca <help@stably.ai>
2.1 KiB
Extended Key Chords in the Terminal (Shift+Enter, etc.)
What Orca sends
Orca's built‑in terminal already encodes extended key chords using the kitty keyboard protocol (CSI‑u). For example, Shift+Enter is sent as the byte sequence:
ESC [ 1 3 ; 2 u (i.e. \x1b[13;2u)
See src/renderer/src/components/terminal-pane/terminal-shortcut-policy.ts
for the full table.
Orca also advertises kitty‑protocol support to the running program via
vtExtensions.kittyKeyboard on xterm.js (see
src/renderer/src/lib/pane-manager/pane-terminal-options.ts), so CLIs that
probe with CSI ? u learn that the terminal speaks CSI‑u and enable their
enhanced input handlers.
Why Shift+Enter may not reach your CLI inside tmux
tmux, by default, strips both extended‑key encodings (modifyOtherKeys
CSI 27 ; 2 ; 13 ~ and kitty‑style CSI 13 ; 2 u). If you run Claude
Code, Codex, or any other CLI under tmux, Shift+Enter will look like a
plain Enter unless tmux is told to pass those bytes through.
Add this to ~/.tmux.conf (tmux 3.2+):
set -s extended-keys on
set -as terminal-features 'xterm*:extkeys'
Then reload: tmux source-file ~/.tmux.conf (or restart the tmux server).
extended-keys on— tell tmux to accept and forward the extended encodings instead of collapsing them to the unshifted key.terminal-features 'xterm*:extkeys'— tell tmux that the surrounding terminal (Orca, in this case) understands those encodings, so tmux is willing to emit them.
Verifying end‑to‑end
Inside an Orca terminal (no tmux), run:
cat -v
Press Shift+Enter. You should see:
^[[13;2u
That's caret notation for \x1b[13;2u — the expected CSI‑u encoding. If
you see ^M (or a blank newline) instead, either the chord isn't reaching
the terminal (check keyboard-handlers.ts / terminal-shortcut-policy.ts)
or you're inside tmux without the config above.
Inside tmux after the config, the same cat -v test should print the same
^[[13;2u.