Skip to content

Node-based terminal manager for AI coding agents — tmux-backed terminals and parallel agent sessions as draggable nodes on an infinite pan/zoom canvas. macOS, Linux, and a browser Server Edition.

fix(windows): let Ctrl+V paste in terminals

enes397c09db0ef6
diff --git a/CLAUDE.md b/CLAUDE.md
index 588ebeaec..bda1d5e82 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -788,7 +788,16 @@ session.
layouts still copy. A copy chord is **always swallowed**, selection or not: letting Ctrl+Shift+C
fall through would reach the pty as `\x03` (SIGINT). Ctrl+Insert exists because Chromium reserves
Ctrl+Shift+C for the inspector and a page cannot `preventDefault()` it — which is where Server
- Edition users land. Plain **Ctrl+C** is never intercepted. To select in **xterm** instead of tmux
+ Edition users land. Plain **Ctrl+C** is never intercepted.
+ **PASTE is the platform's, never ours** (`isPasteShortcut` → the `'native'` action): we own no
+ paste path — ⌘V on mac reaches the Edit menu's `{role:'paste'}`, whose `paste` event xterm frames
+ as a bracketed paste. All the terminal does is stop CANCELLING the chord, and that is a
+ **Windows-only** claim: xterm's keymap turns Ctrl+V into `\x16` with `cancel`, which suppressed
+ Chromium's paste command *and* the Ctrl+V accelerator behind it, so Ctrl+V pasted nothing at all
+ there (issue #562). Off Windows the chord stays `\x16` on purpose — mac pastes with ⌘V, Linux
+ with Ctrl+Shift+V, and Ctrl+V is a key vim/readline users really send. Ctrl+Shift+V and
+ Shift+Insert need no branch: measured against `evaluateKeyboardEvent`, xterm produces neither a
+ key nor a cancel for them, so the platform already pastes. To select in **xterm** instead of tmux
(or inside an app that grabs the mouse, like vim/htop), hold **Option** (mac —
xterm's `macOptionClickForcesSelection`) or **Shift** (Linux/Windows) while dragging.
**Copying now says so**: the OSC 52 handler floats a transient `Copied N lines` pill over the
diff --git a/src/renderer/components/kanban/ModalTerminal.tsx b/src/renderer/components/kanban/ModalTerminal.tsx
index 0326c8fa4..8a25e1a1f 100644
--- a/src/renderer/components/kanban/ModalTerminal.tsx
+++ b/src/renderer/components/kanban/ModalTerminal.tsx
@@ -247,8 +247,9 @@ export function ModalTerminal({ nodeId, spawn, searchOpen, onCloseSearch }: Moda
const action = terminalKeyAction(e, term.hasSelection(), ownsProjectJump, registryOwns)
if (action === 'pass') return true
// 'bubble': hand the chord to the window dispatcher — no preventDefault (it bails on
- // defaultPrevented), no xterm processing. See TerminalNode's twin comment.
- if (action === 'bubble') return false
+ // defaultPrevented), no xterm processing. 'native' leaves the event uncancelled for the
+ // PLATFORM's own paste (Windows Ctrl+V). See TerminalNode's twin comment.
+ if (action === 'bubble' || action === 'native') return false
e.preventDefault()
if (action === 'copy') window.nodeTerminal.clipboard.writeText(term.getSelection())
else if (action === 'shift-enter' && sessionId) transport.write(sessionId, SHIFT_ENTER_SEQ)
diff --git a/src/renderer/nodes/TerminalNode.tsx b/src/renderer/nodes/TerminalNode.tsx
index 3349b4228..4fe4e151c 100644
--- a/src/renderer/nodes/TerminalNode.tsx
+++ b/src/renderer/nodes/TerminalNode.tsx
@@ -2690,7 +2690,12 @@ export function TerminalNode({
// into a CSI write and cancel the event — and DO NOT preventDefault: the dispatcher bails
// on defaultPrevented events, so a prevented bubble would kill the very dispatch this
// exists to reach.
- if (action === 'bubble') return false
+ // 'native': same mechanics, different owner — the PLATFORM's paste (Windows Ctrl+V, issue
+ // #562). xterm would map it to \x16 and cancel the keydown, which suppresses both
+ // Chromium's paste command and the Edit menu's Ctrl+V accelerator; leaving the event
+ // untouched lets the ordinary `paste` event reach xterm's textarea, exactly as ⌘V does on
+ // macOS (bracketed-paste framing included).
+ if (action === 'bubble' || action === 'native') return false
e.preventDefault()
if (action === 'copy') window.nodeTerminal.clipboard.writeText(term.getSelection())
// Shift+Enter → ESC+CR so agent CLIs insert a newline instead of submitting
diff --git a/src/renderer/terminal/terminal-config.test.ts b/src/renderer/terminal/terminal-config.test.ts
index bf103c9a6..e7ac95768 100644
--- a/src/renderer/terminal/terminal-config.test.ts
+++ b/src/renderer/terminal/terminal-config.test.ts
@@ -8,6 +8,7 @@ import {
disposalAction,
forgetNodeTermState,
isCopyShortcut,
+ isPasteShortcut,
isLetterboxed,
letterboxFor,
markRecycled,
@@ -494,6 +495,36 @@ describe('copyKeyAction', () => {
})
})
+describe('isPasteShortcut (issue #562 — Ctrl+V did nothing on Windows)', () => {
+ const v = (p: Partial<CopyShortcutEvent> = {}): CopyShortcutEvent =>
+ ev({ key: 'v', code: 'KeyV', ...p })
+
+ it('claims Ctrl+V on Windows', () => {
+ expect(isPasteShortcut(v({ ctrlKey: true }), true)).toBe(true)
+ // Non-Latin layout: the physical KeyV position still counts, like isCopyShortcut's KeyC.
+ expect(isPasteShortcut(ev({ key: 'м', code: 'KeyV', ctrlKey: true }), true)).toBe(true)
+ })
+
+ it('claims NOTHING off Windows — there Ctrl+V is a pty control byte and paste is Cmd+V / Ctrl+Shift+V', () => {
+ // vim's blockwise-visual and readline's literal-next live on this chord.
+ expect(isPasteShortcut(v({ ctrlKey: true }), false)).toBe(false)
+ })
+
+ it('leaves the chords xterm already passes through alone', () => {
+ // Measured in @xterm/xterm's evaluateKeyboardEvent: Ctrl+Shift+V and Shift+Insert produce
+ // neither a key nor a cancel, so the platform paste already runs for them.
+ expect(isPasteShortcut(v({ ctrlKey: true, shiftKey: true }), true)).toBe(false)
+ expect(isPasteShortcut(ev({ key: 'Insert', code: 'Insert', shiftKey: true }), true)).toBe(false)
+ })
+
+ it('ignores keyup, plain V, AltGr (ctrl+alt) and Cmd+V', () => {
+ expect(isPasteShortcut(v({ ctrlKey: true, type: 'keyup' }), true)).toBe(false)
+ expect(isPasteShortcut(v(), true)).toBe(false)
+ expect(isPasteShortcut(v({ ctrlKey: true, altKey: true }), true)).toBe(false)
+ expect(isPasteShortcut(v({ metaKey: true }), true)).toBe(false)
+ })
+})
+
describe('terminalKeyAction', () => {
it('maps Shift+Enter keydown to shift-enter', () => {
expect(terminalKeyAction(ev({ key: 'Enter', code: 'Enter', shiftKey: true }), false)).toBe(
@@ -570,6 +601,38 @@ describe('terminalKeyAction', () => {
expect(SHIFT_ENTER_SEQ).toBe('\x1b\r')
})
+ // Issue #562: xterm maps Ctrl+V to \x16 AND cancels the keydown, which suppresses both
+ // Chromium's paste command and the Edit menu's Ctrl+V accelerator — so nothing pasted at all.
+ // 'native' = return false from the xterm handler WITHOUT preventDefault, so the platform pastes.
+ it('hands Windows Ctrl+V to the platform paste', () => {
+ const ctrlV = ev({ key: 'v', code: 'KeyV', ctrlKey: true })
+ expect(terminalKeyAction(ctrlV, false, false, false, true)).toBe('native')
+ expect(terminalKeyAction(ctrlV, true, false, false, true)).toBe('native')
+ })
+
+ it('leaves Ctrl+V as a pty control byte off Windows', () => {
+ const ctrlV = ev({ key: 'v', code: 'KeyV', ctrlKey: true })
+ expect(terminalKeyAction(ctrlV, false, false, false, false)).toBe('pass')
+ // The default reads the live platform; under vitest's node env that is not Windows, so every
+ // existing call site keeps its byte-identical behavior.
+ expect(terminalKeyAction(ctrlV, false)).toBe('pass')
+ })
+
+ it('never lets the paste claim shadow a copy chord or Shift+Enter', () => {
+ expect(terminalKeyAction(ev({ ctrlKey: true, shiftKey: true }), true, false, false, true)).toBe(
+ 'copy'
+ )
+ expect(
+ terminalKeyAction(
+ ev({ key: 'Enter', code: 'Enter', shiftKey: true }),
+ false,
+ false,
+ false,
+ true
+ )
+ ).toBe('shift-enter')
+ })
+
// The jump-to-project chord: WHICH events are the chord is decided once, in lib/projectJump.ts
// (and tested there — layout, AltGr, keyup, digit range). This module only obeys the answer.
// It bubbles (not swallow) so the window dispatcher can perform the switch while still
diff --git a/src/renderer/terminal/terminal-config.ts b/src/renderer/terminal/terminal-config.ts
index 7e4c61a47..c83efca18 100644
--- a/src/renderer/terminal/terminal-config.ts
+++ b/src/renderer/terminal/terminal-config.ts
@@ -6,6 +6,7 @@ import type {
TerminalCursorInactiveStyle,
TerminalCursorStyle
} from '@shared/types'
+import { isWindowsPlatform } from '@shared/platform-utils'
import { isKnownTerminalThemeId, resolveTerminalTheme } from './themes'
/**
@@ -745,6 +746,37 @@ export function isCopyShortcut(e: CopyShortcutEvent): boolean {
return cmdC || ctrlShiftC
}
+/**
+ * The paste chord that xterm's own keymap would EAT — Ctrl+V, and only on Windows.
+ *
+ * We do not paste ourselves: the platform already does, and identically on every surface. On
+ * macOS ⌘V reaches the Edit menu's `{role:'paste'}` (Chromium routes those into the focused
+ * element), which dispatches a `paste` event to xterm's helper textarea; xterm's handler applies
+ * bracketed-paste framing and writes it to the pty. All this decision does is stop xterm from
+ * CANCELLING the keydown, so the same platform path runs on Windows too.
+ *
+ * Measured against `@xterm/xterm`'s `evaluateKeyboardEvent` (issue #562):
+ * - **Ctrl+V** maps to `\x16` (SYN) with `cancel: true`, so xterm calls `preventDefault()` — which
+ * suppresses Chromium's paste editing command AND keeps the Ctrl+V menu accelerator from firing
+ * (an accelerator only runs on a keydown the renderer did not consume). Hence: nothing pasted,
+ * nothing typed, no error. This is the whole bug.
+ * - **Ctrl+Shift+V** and **Shift+Insert** produce no key and no cancel, so xterm already lets them
+ * through to the platform. They need no branch here, and adding one would only risk breaking
+ * what works.
+ *
+ * **Windows only, deliberately.** On macOS ⌘V is the paste chord and Ctrl+V must stay `\x16`; on
+ * Linux the terminal convention is Ctrl+Shift+V, and Ctrl+V is a key people actually send (vim's
+ * blockwise-visual, readline's literal-next). Windows Terminal's own default is Ctrl+V = paste,
+ * so this matches what a Windows user's other terminal does — at the cost of `\x16` there, the
+ * same trade Windows Terminal ships.
+ */
+export function isPasteShortcut(e: CopyShortcutEvent, isWindows: boolean): boolean {
+ if (!isWindows || e.type !== 'keydown') return false
+ if (e.key.toLowerCase() !== 'v' && e.code !== 'KeyV') return false
+ // AltGr reports ctrl+alt, and Ctrl+Shift+V is not ours to claim (xterm already passes it).
+ return e.ctrlKey && !e.shiftKey && !e.altKey && !e.metaKey
+}
+
/**
* What a terminal keydown that MIGHT be a copy chord should do:
* - `copy` — it is a copy chord and there is a selection: copy it, swallow the key.
@@ -771,7 +803,7 @@ export function copyKeyAction(e: CopyShortcutEvent, hasSelection: boolean): Copy
*/
export const SHIFT_ENTER_SEQ = '\x1b\r'
-export type TerminalKeyAction = CopyKeyAction | 'shift-enter' | 'bubble'
+export type TerminalKeyAction = CopyKeyAction | 'shift-enter' | 'bubble' | 'native'
/**
* Superset of `copyKeyAction` used by the terminal's custom key handler.
@@ -794,7 +826,8 @@ export function terminalKeyAction(
e: CopyShortcutEvent,
hasSelection: boolean,
ownsProjectJump = false,
- registryOwns = false
+ registryOwns = false,
+ isWindows: boolean = isWindowsPlatform()
): TerminalKeyAction {
if (
e.type === 'keydown' &&
@@ -814,6 +847,13 @@ export function terminalKeyAction(
if (ownsProjectJump) return 'bubble'
const base = copyKeyAction(e, hasSelection)
if (base !== 'pass') return base
+ // Windows Ctrl+V: hand the chord to the PLATFORM's own paste (see `isPasteShortcut`). 'native'
+ // has the same mechanics as 'bubble' — return false from the xterm handler, do NOT
+ // preventDefault — but a different reason, so the two are not one branch: 'bubble' means the
+ // window dispatcher owns a registry command, 'native' means Chromium's editing command (and the
+ // Edit menu's `{role:'paste'}` accelerator behind it) does. Both need the event left uncancelled;
+ // only 'bubble' implies a registry owner.
+ if (isPasteShortcut(e, isWindows)) return 'native'
// `registryOwns` — decided by the caller via `terminalChordBubbles`, the same live-registry
// matcher discipline as `ownsProjectJump` — means the window dispatcher will claim this chord
// (an allowInTerminal app/canvas command). 'bubble' tells the consumer to return false WITHOUT
diff --git a/src/renderer/terminal/terminal-key-handler-parity.test.ts b/src/renderer/terminal/terminal-key-handler-parity.test.ts
new file mode 100644
index 000000000..484785fa3
--- /dev/null
+++ b/src/renderer/terminal/terminal-key-handler-parity.test.ts
@@ -0,0 +1,37 @@
+import { readFileSync } from 'fs'
+import { join } from 'path'
+import { describe, expect, it } from 'vitest'
+
+/**
+ * TWO xterm key handlers, one decision function.
+ *
+ * `TerminalNode` (canvas) and `ModalTerminal` (kanban card modal) both call `terminalKeyAction`
+ * and both act on its answer — the modal's own comments call itself a MIRROR of the node's. The
+ * decision is shared and tested; the ACTING is duplicated, and that is where it drifts.
+ *
+ * The uncancelled actions are the fragile half: `bubble` and `native` must return `false` WITHOUT
+ * `preventDefault()`, and a call site that knows only `bubble` falls through to the `preventDefault`
+ * line — which for `native` is precisely issue #562's bug (Ctrl+V eaten, nothing pasted), except
+ * now on one surface only, and the shared unit tests would still be green.
+ *
+ * Source-level, in the spirit of `hook-verified-parity.test.ts`: the alternative is a full
+ * xterm+DOM harness, and vitest here runs in the node environment.
+ */
+const FILES = [
+ 'src/renderer/nodes/TerminalNode.tsx',
+ 'src/renderer/components/kanban/ModalTerminal.tsx'
+]
+
+describe('terminal key-handler parity', () => {
+ for (const rel of FILES) {
+ it(`${rel} returns without preventDefault for both uncancelled actions`, () => {
+ const src = readFileSync(join(process.cwd(), rel), 'utf8')
+ expect(src).toContain("action === 'bubble' || action === 'native'")
+ // …and it does so BEFORE the preventDefault that copy / shift-enter need.
+ const guard = src.indexOf("action === 'bubble' || action === 'native'")
+ const prevent = src.indexOf('e.preventDefault()', guard)
+ expect(guard).toBeGreaterThan(-1)
+ expect(prevent).toBeGreaterThan(guard)
+ })
+ }
+})