From c7acc3a7c4e2e0a97a24c23bb70c7750ef10627c Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?T=C3=82CHES?= Date: Mon, 23 Mar 2026 08:57:43 -0600 Subject: [PATCH] fix: document iTerm2 Ctrl+Alt+G keybinding conflict and add helpful hint (#2231) When iTerm2's Left Option Key is set to "Normal" (the default), Ctrl+Alt+G sends only Ctrl+G, triggering the external editor action instead of the GSD dashboard. This adds an iTerm2-specific hint to the "No editor configured" warning and documents the fix in troubleshooting and keyboard shortcuts docs. Closes #1563 Co-authored-by: Claude Opus 4.6 (1M context) --- docs/troubleshooting.md | 10 ++++++++++ .../18-quick-reference-commands-shortcuts.md | 2 ++ .../modes/interactive/components/extension-editor.ts | 3 +++ .../src/modes/interactive/interactive-mode.ts | 9 ++++++++- 4 files changed, 23 insertions(+), 1 deletion(-) diff --git a/docs/troubleshooting.md b/docs/troubleshooting.md index 977a7881a..50c7cf271 100644 --- a/docs/troubleshooting.md +++ b/docs/troubleshooting.md @@ -278,6 +278,16 @@ Doctor rebuilds `STATE.md` from plan and roadmap files on disk and fixes detecte - **Forensics:** `/gsd forensics` for structured post-mortem analysis of auto-mode failures - **Session logs:** `.gsd/activity/` contains JSONL session dumps for crash forensics +## iTerm2-Specific Issues + +### Ctrl+Alt shortcuts trigger the wrong action (e.g., Ctrl+Alt+G opens external editor instead of GSD dashboard) + +**Symptoms:** Pressing Ctrl+Alt+G opens the external editor prompt (Ctrl+G) instead of the GSD dashboard. Other Ctrl+Alt shortcuts behave as their Ctrl-only counterparts. + +**Cause:** iTerm2's default Left Option Key setting is "Normal", which swallows the Alt modifier for Ctrl+Alt key combinations. The terminal receives only the Ctrl key, so Ctrl+Alt+G arrives as Ctrl+G. + +**Fix:** In iTerm2, go to **Profiles → Keys → General** and set **Left Option Key** to **Esc+**. This makes Alt/Option send an escape prefix that terminal applications can detect, enabling Ctrl+Alt shortcuts to work correctly. + ## Windows-Specific Issues ### LSP returns ENOENT on Windows (MSYS2/Git Bash) diff --git a/docs/what-is-pi/18-quick-reference-commands-shortcuts.md b/docs/what-is-pi/18-quick-reference-commands-shortcuts.md index fa6b09ad0..8b195117a 100644 --- a/docs/what-is-pi/18-quick-reference-commands-shortcuts.md +++ b/docs/what-is-pi/18-quick-reference-commands-shortcuts.md @@ -40,6 +40,8 @@ | Alt+Enter (during streaming) | Queue follow-up message | | Alt+Up | Retrieve queued messages | +> **iTerm2 users:** Ctrl+Alt shortcuts (e.g., Ctrl+Alt+G for the GSD dashboard) require Left Option Key set to "Esc+" in Profiles → Keys → General. The default "Normal" setting swallows the Alt modifier. + ### CLI ```bash diff --git a/packages/pi-coding-agent/src/modes/interactive/components/extension-editor.ts b/packages/pi-coding-agent/src/modes/interactive/components/extension-editor.ts index f0a9eae8b..0b05c3ada 100644 --- a/packages/pi-coding-agent/src/modes/interactive/components/extension-editor.ts +++ b/packages/pi-coding-agent/src/modes/interactive/components/extension-editor.ts @@ -113,6 +113,9 @@ export class ExtensionEditorComponent extends Container implements Focusable { private openExternalEditor(): void { const editorCmd = process.env.VISUAL || process.env.EDITOR; if (!editorCmd) { + // No editor configured — nothing to do. + // The main interactive-mode handler shows a warning with an iTerm2 hint; + // this component is a secondary editor so we silently bail. return; } diff --git a/packages/pi-coding-agent/src/modes/interactive/interactive-mode.ts b/packages/pi-coding-agent/src/modes/interactive/interactive-mode.ts index cd9550f12..df9d4d681 100644 --- a/packages/pi-coding-agent/src/modes/interactive/interactive-mode.ts +++ b/packages/pi-coding-agent/src/modes/interactive/interactive-mode.ts @@ -2460,7 +2460,14 @@ export class InteractiveMode { // Determine editor (respect $VISUAL, then $EDITOR) const editorCmd = process.env.VISUAL || process.env.EDITOR; if (!editorCmd) { - this.showWarning("No editor configured. Set $VISUAL or $EDITOR environment variable."); + let msg = "No editor configured. Set $VISUAL or $EDITOR environment variable."; + if (process.env.TERM_PROGRAM === "iTerm.app") { + msg += + "\n\nTip: If you meant to open the GSD dashboard (Ctrl+Alt+G), set Left Option Key to" + + " \"Esc+\" in iTerm2 → Profiles → Keys. With the default \"Normal\" setting," + + " Ctrl+Alt+G sends Ctrl+G instead."; + } + this.showWarning(msg); return; }