mirror of
https://github.com/stablyai/orca.git
synced 2026-10-15 08:03:08 +00:00
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>
67 lines
2.1 KiB
Markdown
67 lines
2.1 KiB
Markdown
# 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][kitty] (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+):
|
||
|
||
```tmux
|
||
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`.
|
||
|
||
[kitty]: https://sw.kovidgoyal.net/kitty/keyboard-protocol/
|