Keyboard Shortcuts

What It Does

GSD registers five keyboard shortcuts for actions that benefit from instant access over a slash command. These work during any active session — whether auto mode is running, you’re reviewing output, or watching a build.

Four shortcuts use the Ctrl+Alt modifier and require the Kitty keyboard protocol for reliable detection. In unsupported terminals (macOS Terminal.app, Warp, JetBrains IDEs), GSD shows slash-command fallback hints in place of the shortcuts rather than silently dropping them.

The fifth shortcut — Ctrl+V / Alt+V — pastes an image from your clipboard directly into the conversation as vision input. Use Alt+V in terminals where Ctrl+V is reserved for paste (e.g. Warp).

Usage

Shortcut	Action	Fallback
Ctrl+Alt+G	Toggle dashboard overlay	/gsd status
Ctrl+Alt+V	Toggle voice transcription	/voice
Ctrl+Alt+B	Show background shell processes	/bg
Ctrl+V / Alt+V	Paste image from clipboard (screenshot → vision input)	—
Escape	Pause auto mode (preserves conversation)	—

How It Works

Ctrl+Alt+G — Dashboard Overlay

Opens a full-screen overlay showing milestone progress, the active slice and task, completed units, timing, and cost metrics. Same view as /gsd status, but toggled in place without breaking your conversation. Press Escape, Ctrl+C, or Ctrl+Alt+G again to close.

Only activates when a .gsd/ directory is present in the current working directory. If not found, a notice is shown: “No .gsd/ directory found. Run /gsd to start.”

Ctrl+Alt+V — Voice Transcription

Toggles real-time speech-to-text transcription on and off. Requires a microphone. Equivalent to running /voice. Supported on macOS and Linux.

Ctrl+Alt+B — Background Process Manager

Opens an overlay listing all running background shell processes — dev servers, file watchers, build processes. Shows process ID, command, status, and uptime. Equivalent to running /bg. Press Escape or q to close.

Ctrl+V / Alt+V — Clipboard Image Paste

Pastes an image from your system clipboard into the conversation as vision input. Useful for attaching screenshots, mockups, or error dialogs without saving them as files first. GSD passes the image directly to the model.

Use Ctrl+V in most terminals. Use Alt+V in terminals where Ctrl+V is reserved for paste (e.g. Warp).

Escape — Pause Auto Mode

When auto mode is running, pressing Escape aborts the current agent turn and pauses auto mode with all state preserved. GSD’s agent_end hook detects the aborted stop reason and calls pause automatically. Run /gsd auto to resume from where it left off.

This is distinct from a graceful /gsd stop, which lets the current unit finish before stopping. Escape is an immediate abort — the conversation history is preserved but the active turn is cut short.

Terminal Compatibility

Shortcuts relying on Ctrl+Alt require the Kitty keyboard protocol — a modern terminal extension that enables precise modifier key detection. Supported terminals include Kitty, WezTerm, Ghostty, and recent versions of iTerm2.

In terminals without protocol support, Ctrl+Alt combinations can’t be reliably detected. GSD auto-detects this at startup using TERM_PROGRAM and TERMINAL_EMULATOR environment variables and appends fallback hints to affected shortcut descriptions.

Known unsupported terminals:

Terminal	Detection	Fallback behavior
macOS Terminal.app	TERM_PROGRAM=apple_terminal	Slash-command hints shown
Warp	TERM_PROGRAM=warpterm	Slash-command hints shown
JetBrains IDE terminals	TERMINAL_EMULATOR contains JetBrains	Slash-command hints shown

Note

You don’t need to configure anything — GSD detects capabilities automatically at startup. If your terminal supports the protocol, shortcuts just work. If it doesn’t, fallback commands are always available.

What Files It Touches

Keyboard shortcuts are entirely read-only and in-memory. No files are created, modified, or deleted by pressing a shortcut. The dashboard overlay reads planning files the same way /gsd status does.

Examples

Checking milestone progress mid-execution without typing:

[Auto mode running...]
→ Press Ctrl+Alt+G
[Dashboard overlay opens — shows S03/T02 in progress, 4/7 tasks done]
→ Press Escape to close and return to conversation

Pasting a screenshot for analysis:

> Cmd+Shift+4    (macOS — capture screenshot to clipboard)
> Ctrl+V         (or Alt+V in Warp)
[Image appears inline in the conversation]
> What's wrong with this error message?

Pausing a runaway auto-mode turn:

[Auto mode dispatched a task you want to stop...]
→ Press Escape
● Auto mode paused — state preserved.
> /gsd auto    ← resume when ready

Using voice instead of typing a long thought:

→ Press Ctrl+Alt+V
● Voice transcription active
[Speak your message — it types into the input bar]
→ Press Ctrl+Alt+V again to stop

Related Commands

• /gsd status — Dashboard (same as Ctrl+Alt+G)
• /gsd stop — Stop auto mode gracefully after the current unit finishes
• /gsd auto — Start or resume autonomous mode