Commands Reference
Session Commands
| Command |
Description |
/gsd |
Step mode — execute one unit at a time, pause between each |
/gsd next |
Explicit step mode (same as /gsd) |
/gsd auto |
Autonomous mode — research, plan, execute, commit, repeat |
/gsd quick |
Execute a quick task with GSD guarantees (atomic commits, state tracking) without full planning overhead |
/gsd stop |
Stop auto mode gracefully |
/gsd steer |
Hard-steer plan documents during execution |
/gsd discuss |
Discuss architecture and decisions (works alongside auto mode) |
/gsd status |
Progress dashboard |
/gsd queue |
Queue and reorder future milestones (safe during auto mode) |
/gsd capture |
Fire-and-forget thought capture (works during auto mode) |
/gsd triage |
Manually trigger triage of pending captures |
/gsd visualize |
Open workflow visualizer (progress, deps, metrics, timeline) |
/gsd knowledge |
Add persistent project knowledge (rule, pattern, or lesson) |
/gsd help |
Categorized command reference with descriptions for all GSD subcommands |
Configuration & Diagnostics
| Command |
Description |
/gsd prefs |
Model selection, timeouts, budget ceiling |
/gsd mode |
Switch workflow mode (solo/team) with coordinated defaults for milestone IDs, git commit behavior, and documentation |
/gsd doctor |
Runtime health checks (7 checks) with auto-fix for common state corruption issues |
/gsd skill-health |
Skill lifecycle dashboard — usage stats, success rates, token trends, staleness warnings |
/gsd skill-health <name> |
Detailed view for a single skill |
/gsd skill-health --declining |
Show only skills flagged for declining performance |
/gsd skill-health --stale N |
Show skills unused for N+ days |
/gsd hooks |
Show configured post-unit and pre-dispatch hooks |
/gsd run-hook |
Manually trigger a specific hook |
/gsd migrate |
Migrate a v1 .planning directory to .gsd format |
Git Commands
| Command |
Description |
/worktree (/wt) |
Git worktree lifecycle — create, switch, merge, remove |
Session Management
| Command |
Description |
/clear |
Start a new session (alias for /new) |
/exit |
Graceful shutdown — saves session state before exiting |
/kill |
Kill GSD process immediately |
/model |
Switch the active model |
/login |
Log in to an LLM provider |
/thinking |
Toggle thinking level during sessions |
/voice |
Toggle real-time speech-to-text (macOS, Linux) |
Keyboard Shortcuts
| Shortcut |
Action |
Ctrl+Alt+G |
Toggle dashboard overlay |
Ctrl+Alt+V |
Toggle voice transcription |
Ctrl+Alt+B |
Show background shell processes |
Escape |
Pause auto mode (preserves conversation) |
Note: In terminals without Kitty keyboard protocol support (macOS Terminal.app, JetBrains IDEs), slash-command fallbacks are shown instead of Ctrl+Alt shortcuts.
CLI Flags
| Flag |
Description |
gsd |
Start a new interactive session |
gsd --continue (-c) |
Resume the most recent session for the current directory |
gsd --model <id> |
Override the default model for this session |
gsd --print "msg" (-p) |
Single-shot prompt mode (no TUI) |
gsd --mode <text|json|rpc|mcp> |
Output mode for non-interactive use |
gsd --list-models [search] |
List available models and exit |
gsd --debug |
Enable structured JSONL diagnostic logging for troubleshooting dispatch and state issues |
gsd config |
Re-run the setup wizard (LLM provider + tool keys) |
gsd update |
Update GSD to the latest version |
Headless Mode
gsd headless runs /gsd commands without a TUI — designed for CI, cron jobs, and scripted automation. It spawns a child process in RPC mode, auto-responds to interactive prompts, detects completion, and exits with meaningful exit codes.
# Run auto mode (default)
gsd headless
# Run a single unit
gsd headless next
# Machine-readable output
gsd headless --json status
# With timeout for CI
gsd headless --timeout 600000 auto
# Force a specific phase
gsd headless dispatch plan
| Flag |
Description |
--timeout N |
Overall timeout in milliseconds (default: 300000 / 5 min) |
--json |
Stream all events as JSONL to stdout |
--model ID |
Override the model for the headless session |
Exit codes: 0 = complete, 1 = error or timeout, 2 = blocked.
Any /gsd subcommand works as a positional argument — gsd headless status, gsd headless doctor, gsd headless dispatch execute, etc.
f56b8c69f0