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.

All three GSD 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+N	Open notification history	/gsd notifications
Ctrl+Alt+P	Open parallel worker monitor	/gsd parallel watch
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+N — Notification History

Opens a scrollable overlay showing all persisted notifications with severity icons and relative timestamps. Entries are filterable by severity — cycling through all → error → warning → info. Equivalent to running /gsd notifications.

The overlay marks all visible notifications as read when opened. Use c inside the overlay to clear all notifications. Press Escape or q to close.

Ctrl+Alt+P — Parallel Worker Monitor

Opens a full-screen overlay showing real-time parallel worker progress — milestone assignments, worker statuses, timing, and recent log output. Equivalent to running /gsd parallel watch.

Only activates when a .gsd/parallel/ directory is present. If parallel workers haven’t been started, a notice is shown: “No parallel workers found. Run /gsd parallel start first.”

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 notification overlay reads from the notification store. The parallel monitor reads from .gsd/parallel/.

Reads

File	Purpose
.gsd/	Checked for existence before opening dashboard overlay
.gsd/parallel/	Checked for existence before opening parallel monitor
.gsd/runtime/notifications.db	Notification history read by the notification overlay

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

Reviewing notification history after a long auto-mode run:

→ Press Ctrl+Alt+N
[Notification overlay opens — shows warnings and info from recent units]
→ Press f to cycle filters (all → error → warning → info)
→ Press c to clear, Escape to close

Monitoring parallel workers without leaving the conversation:

[/gsd parallel start running three workers...]
→ Press Ctrl+Alt+P
[Parallel monitor overlay opens — shows M003, M004, M005 worker statuses]
→ Press Escape to close

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

Remapping paste-image for Warp users:

~/.gsd/agent/keybindings.json

{
  "pasteImage": "alt+v"
}

Related Commands

• /gsd status — Dashboard (same as Ctrl+Alt+G)
• /gsd notifications — Notification history (same as Ctrl+Alt+N)
• /gsd stop — Stop auto mode gracefully after the current unit finishes
• /gsd auto — Start or resume autonomous mode
• /gsd parallel — Parallel milestone orchestration (same as Ctrl+Alt+P)