singularity/singularity-forge
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions 1

fix: document iTerm2 Ctrl+Alt+G keybinding conflict and add helpful hint (#2231)

Browse source 
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) <noreply@anthropic.com>
This commit is contained in:
TÂCHES 2026-03-23 08:57:43 -06:00 • committed by GitHub
parent 8d4b9d08a5
commit c7acc3a7c4
4 changed files with 23 additions and 1 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

10
docs/troubleshooting.md
View file

@ -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)

2
docs/what-is-pi/18-quick-reference-commands-shortcuts.md
View file

@ -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

3
packages/pi-coding-agent/src/modes/interactive/components/extension-editor.ts
View file

@ -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;
}

9
packages/pi-coding-agent/src/modes/interactive/interactive-mode.ts
View file

@ -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;
}