Skip to content

an open-source alternative to the dots, bots and muses of the world, run an office of claude code/codex like agents on your laptop, sandboxes or anywhere, uses your existing subscriptions

fix(terminal): Shift+Enter inserts a newline instead of submitting

Snehitha46bce68f26aa
diff --git a/docs/pr-evidence/shift-enter-after.png b/docs/pr-evidence/shift-enter-after.png
new file mode 100644
index 00000000..291973c4
Binary files /dev/null and b/docs/pr-evidence/shift-enter-after.png differ
diff --git a/docs/pr-evidence/shift-enter-before.png b/docs/pr-evidence/shift-enter-before.png
new file mode 100644
index 00000000..464eef3e
Binary files /dev/null and b/docs/pr-evidence/shift-enter-before.png differ
diff --git a/src/renderer/src/components/terminalKeys.ts b/src/renderer/src/components/terminalKeys.ts
new file mode 100644
index 00000000..eff025f0
--- /dev/null
+++ b/src/renderer/src/components/terminalKeys.ts
@@ -0,0 +1,51 @@
+/**
+ * Modifier-key encoding for the embedded terminal.
+ *
+ * xterm.js encodes Shift+Enter exactly like Enter — a bare CR — so a TUI cannot
+ * tell the two apart, and Shift+Enter at a prompt submits instead of opening a
+ * new line (#481). Terminals that get this right send a distinct sequence, and
+ * the one Claude Code's `/terminal-setup` installs for iTerm2 and VS Code is
+ * ESC CR. Nothing configures that for our pane, so it has to be sent here.
+ *
+ * Kept structural and free of imports — no xterm, no window — so the mapping is
+ * unit-testable on its own, the same way askMeOrder.ts and queueDelivery.ts are.
+ * The caller supplies the fields it reads from a KeyboardEvent.
+ */
+
+/** ESC CR — "insert a newline, do not submit". Provider-neutral: it is the
+ * convention `/terminal-setup` writes for Claude Code, and the same sequence
+ * Alt+Enter has always produced, so any TUI that honours one honours the other. */
+export const NEWLINE_SEQUENCE = '\x1b\r';
+
+/** The fields this needs from a KeyboardEvent. */
+export interface TerminalKey {
+ type: string;
+ key: string;
+ shiftKey: boolean;
+ ctrlKey: boolean;
+ metaKey: boolean;
+ altKey: boolean;
+}
+
+/**
+ * The bytes to send for a key the terminal would otherwise encode wrongly, or
+ * null to let xterm handle it as usual.
+ *
+ * Deliberately narrow. Only Shift+Enter is claimed, and only when it is the ONLY
+ * modifier held:
+ * - plain Enter still submits, which is the whole point of the prompt;
+ * - Alt+Enter already produces this sequence natively, so intercepting it
+ * would be a no-op at best and a double-encode at worst;
+ * - Ctrl+Enter and Cmd+Enter belong to the TUI (and to the app's own
+ * shortcuts), so they are left alone rather than quietly redefined.
+ *
+ * keydown only: xterm's custom-key hook also sees keypress and keyup, and
+ * answering on more than one of them would insert the newline two or three times.
+ */
+export function terminalKeySequence(ev: TerminalKey): string | null {
+ if (ev.type !== 'keydown') return null;
+ if (ev.key !== 'Enter') return null;
+ if (!ev.shiftKey) return null;
+ if (ev.ctrlKey || ev.metaKey || ev.altKey) return null;
+ return NEWLINE_SEQUENCE;
+}
diff --git a/src/renderer/src/components/terminalPool.ts b/src/renderer/src/components/terminalPool.ts
index 669b175e..34591cfc 100644
--- a/src/renderer/src/components/terminalPool.ts
+++ b/src/renderer/src/components/terminalPool.ts
@@ -39,6 +39,7 @@ import {
type TerminalAutomationBlock
} from './terminalAutomation';
import { sanitizeTerminalSelection } from './terminalSelection';
+import { terminalKeySequence } from './terminalKeys';
import '@xterm/xterm/css/xterm.css';
export interface TerminalEntry {
@@ -255,6 +256,18 @@ export function acquireTerminal(ptyId: string, theme?: ThemeMap, fontSize = 14):
};
term.attachCustomKeyEventHandler((ev) => {
if (ev.type !== 'keydown') return true;
+ // Keys xterm would encode in a way the TUI cannot read. Checked BEFORE the
+ // Ctrl/Cmd gate below, because Shift+Enter holds neither: without this it
+ // fell straight through to xterm's default, which sends the same bare CR as
+ // Enter — so Shift+Enter submitted the prompt instead of opening a new line
+ // (#481). Writing to the pty directly is the same path the OSC colour replies
+ // below already use.
+ const seq = terminalKeySequence(ev);
+ if (seq !== null) {
+ if (!entry.exited) window.cth.writePty(ptyId, seq);
+ ev.preventDefault();
+ return false;
+ }
if (!(ev.ctrlKey || ev.metaKey)) return true;
const key = ev.key.toLowerCase();
if (key === 'c' && (ev.shiftKey || term.hasSelection())) {
diff --git a/test/terminal-keys.test.cjs b/test/terminal-keys.test.cjs
new file mode 100644
index 00000000..88ce01cb
--- /dev/null
+++ b/test/terminal-keys.test.cjs
@@ -0,0 +1,51 @@
+'use strict';
+/**
+ * Upstream issue #481: Shift+Enter at a prompt inside the embedded terminal
+ * submits instead of inserting a newline. xterm.js encodes Shift+Enter exactly
+ * like Enter — a bare CR — so the TUI cannot tell them apart. Terminals that
+ * get this right send ESC CR, which is what Claude Code's `/terminal-setup`
+ * installs for iTerm2 and VS Code; nothing configures our pane, so the pane has
+ * to send it. These tests pin the mapping, and pin how narrow it is: every other
+ * Enter combination is left to xterm and to the TUI.
+ */
+const test = require('node:test');
+const assert = require('node:assert/strict');
+const loadTs = require('./load-ts.cjs');
+
+const { terminalKeySequence, NEWLINE_SEQUENCE } = loadTs('src/renderer/src/components/terminalKeys.ts');
+
+/** A KeyboardEvent as the handler sees it. */
+const key = (over = {}) => ({
+ type: 'keydown', key: 'Enter',
+ shiftKey: false, ctrlKey: false, metaKey: false, altKey: false, ...over
+});
+
+test('Shift+Enter sends ESC CR — the sequence /terminal-setup installs', () => {
+ assert.equal(terminalKeySequence(key({ shiftKey: true })), '\x1b\r');
+ assert.equal(NEWLINE_SEQUENCE, '\x1b\r');
+});
+
+test('plain Enter is left alone, so the prompt still submits', () => {
+ assert.equal(terminalKeySequence(key()), null);
+});
+
+test('Enter with another modifier is left to the TUI', () => {
+ // Alt+Enter already produces ESC CR natively — intercepting it would double-encode.
+ assert.equal(terminalKeySequence(key({ shiftKey: true, altKey: true })), null);
+ assert.equal(terminalKeySequence(key({ altKey: true })), null);
+ // Ctrl+Enter / Cmd+Enter belong to the TUI and to the app's own shortcuts.
+ assert.equal(terminalKeySequence(key({ shiftKey: true, ctrlKey: true })), null);
+ assert.equal(terminalKeySequence(key({ shiftKey: true, metaKey: true })), null);
+});
+
+test('only keydown answers, so the newline is not inserted two or three times', () => {
+ // xterm's custom-key hook also sees keypress and keyup for the same press.
+ assert.equal(terminalKeySequence(key({ shiftKey: true, type: 'keypress' })), null);
+ assert.equal(terminalKeySequence(key({ shiftKey: true, type: 'keyup' })), null);
+});
+
+test('Shift with any other key is not claimed', () => {
+ for (const k of ['a', 'Tab', 'Backspace', 'ArrowUp', 'NumpadEnter']) {
+ assert.equal(terminalKeySequence(key({ shiftKey: true, key: k })), null, k);
+ }
+});