Keyboard Shortcuts

What It Does

GSD registers three keyboard shortcuts and inherits two from the underlying platform. Together they cover the actions that benefit most from instant access over a slash command — no typing, no context switch.

Three shortcuts use the Ctrl+Alt modifier combination and require the Kitty keyboard protocol for reliable detection. In terminals that don’t support the protocol (macOS Terminal.app, Warp, JetBrains IDEs), GSD appends a slash-command fallback hint to the shortcut description rather than silently dropping it.

The remaining two — Ctrl+V for paste-image and Escape for interrupt — are platform-level bindings managed by the underlying pi coding agent. Both are configurable via ~/.gsd/agent/keybindings.json.

Usage

Shortcut	Action	Fallback
Ctrl+Alt+G	Open GSD dashboard overlay	/gsd status
Ctrl+Alt+V	Toggle voice mode	/voice
Ctrl+Alt+B	Open background process manager	/bg
Ctrl+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 the 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 Mode

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

macOS — Compiles a Swift binary on first use (requires Xcode CLI tools). No external API key needed; transcription runs locally via the Speech framework.

Linux — Uses a Python script powered by Groq’s Whisper API. Requires:

• GROQ_API_KEY set in your environment (run /gsd keys add groq to configure)
• python3 installed (sudo apt install python3)
• libportaudio2 installed (sudo apt install libportaudio2)
• Python dependencies are auto-installed on first run

When voice is active, a flashing ● transcribing indicator appears in the footer. Press Escape or Enter to stop transcription and dismiss the voice overlay. Pressing Ctrl+Alt+V again also toggles it off if the overlay is not the focused input.

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 — 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.

This is a platform-level keybinding. The default is ctrl+v. If your terminal reserves Ctrl+V for paste (e.g. Warp), remap it to alt+v or another key in ~/.gsd/agent/keybindings.json:

{
  "pasteImage": "alt+v"
}

Escape — Pause Auto Mode

When auto mode is running, pressing Escape pauses it with all state and conversation preserved. GSD’s agent_end hook detects the aborted stop reason and calls pause automatically, suspending auto mode so you can review, redirect, or step away. 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.

Terminal Compatibility

The Ctrl+Alt shortcuts require the Kitty keyboard protocol — a modern terminal extension that enables precise modifier key detection. GSD auto-detects terminal capabilities at startup using the TERM_PROGRAM and TERMINAL_EMULATOR environment variables.

Supported terminals: Kitty, WezTerm, Ghostty, iTerm2 (recent versions).

In terminals without protocol support, GSD appends a fallback hint to the affected shortcut descriptions:

Open GSD dashboard — shortcut may not work in this terminal, use /gsd status

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 terminal capabilities automatically at startup. If your terminal supports the protocol, shortcuts just work. If it doesn’t, fallback slash 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.

The exception is first-run voice setup on macOS, which compiles a Swift binary to ~/.gsd/agent/speech-recognizer. On Linux, Python dependencies are installed into ~/.gsd/voice-venv/ on first activation.

Creates (voice first-run only)

File	Purpose
~/.gsd/agent/speech-recognizer	Compiled Swift speech recognizer binary (macOS, first run)
~/.gsd/voice-venv/	Python virtualenv with speech dependencies (Linux, first run)

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 the conversation

Pasting a screenshot for analysis:

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

Pausing a running auto-mode turn to review progress:

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

Using voice instead of typing a long thought:

→ Press Ctrl+Alt+V
● transcribing  (footer indicator flashes)
[Speak your message — it types into the input bar]
→ Press Escape or Enter to stop

Remapping paste-image for Warp users:

~/.gsd/agent/keybindings.json

{
  "pasteImage": "alt+v"
}

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
• /gsd keys — Manage API keys (including GROQ for Linux voice)