GSD 2

The evolution of Get Shit Done — now a real coding agent.

The original GSD went viral as a prompt framework for Claude Code. It worked, but it was fighting the tool — injecting prompts through slash commands, hoping the LLM would follow instructions, with no actual control over context windows, sessions, or execution.

This version is different. GSD is now a standalone CLI built on the Pi SDK, which gives it direct TypeScript access to the agent harness itself. That means GSD can actually do what v1 could only ask the LLM to do: clear context between tasks, inject exactly the right files at dispatch time, manage git branches, track cost and tokens, detect stuck loops, recover from crashes, and auto-advance through an entire milestone without human intervention.

One command. Walk away. Come back to a built project with clean git history.

npm install -g gsd-pi

---

What Changed From v1

The original GSD was a collection of markdown prompts installed into ~/.claude/commands/. It relied entirely on the LLM reading those prompts and doing the right thing. That worked surprisingly well — but it had hard limits:

• No context control. The LLM accumulated garbage over a long session. Quality degraded.
• No real automation. "Auto mode" was the LLM calling itself in a loop, burning context on orchestration overhead.
• No crash recovery. If the session died mid-task, you started over.
• No observability. No cost tracking, no progress dashboard, no stuck detection.

GSD v2 solves all of these because it's not a prompt framework anymore — it's a TypeScript application that controls the agent session.

	v1 (Prompt Framework)	v2 (Agent Application)
Runtime	Claude Code slash commands	Standalone CLI via Pi SDK
Context management	Hope the LLM doesn't fill up	Fresh session per task, programmatic
Auto mode	LLM self-loop	State machine reading .gsd/ files
Crash recovery	None	Lock files + session forensics
Git strategy	LLM writes git commands	Programmatic branch-per-slice, squash merge
Cost tracking	None	Per-unit token/cost ledger with dashboard
Stuck detection	None	Retry once, then stop with diagnostics
Timeout supervision	None	Soft/idle/hard timeouts with recovery steering
Context injection	"Read this file"	Pre-inlined into dispatch prompt
Roadmap reassessment	Manual	Automatic after each slice completes
Skill discovery	None	Auto-detect and install relevant skills during research

---

How It Works

GSD structures work into a hierarchy:

Milestone  →  a shippable version (4-10 slices)
  Slice    →  one demoable vertical capability (1-7 tasks)
    Task   →  one context-window-sized unit of work

The iron rule: a task must fit in one context window. If it can't, it's two tasks.

The Loop

Each slice flows through phases automatically:

Research → Plan → Execute (per task) → Complete → Reassess Roadmap → Next Slice

Research scouts the codebase and relevant docs. Plan decomposes the slice into tasks with must-haves (mechanically verifiable outcomes). Execute runs each task in a fresh context window with only the relevant files pre-loaded. Complete writes the summary, UAT script, marks the roadmap, and commits. Reassess checks if the roadmap still makes sense given what was learned.

/gsd auto — The Main Event

This is what makes GSD different. Run it, walk away, come back to built software.

/gsd auto

Auto mode is a state machine driven by files on disk. It reads .gsd/STATE.md, determines the next unit of work, creates a fresh agent session, injects a focused prompt with all relevant context pre-inlined, and lets the LLM execute. When the LLM finishes, auto mode reads disk state again and dispatches the next unit.

What happens under the hood:

1. Fresh session per unit — Every task, every research phase, every planning step gets a clean 200k-token context window. No accumulated garbage. No "I'll be more concise now."

2. Context pre-loading — The dispatch prompt includes inlined task plans, slice plans, prior task summaries, dependency summaries, roadmap excerpts, and decisions register. The LLM starts with everything it needs instead of spending tool calls reading files.

3. Git branch-per-slice — Each slice gets its own branch (gsd/M001/S01). Tasks commit atomically on the branch. When the slice completes, it's squash-merged to main as one clean commit.

4. Crash recovery — A lock file tracks the current unit. If the session dies, the next /gsd auto reads the surviving session file, synthesizes a recovery briefing from every tool call that made it to disk, and resumes with full context.

5. Stuck detection — If the same unit dispatches twice (the LLM didn't produce the expected artifact), it retries once with a deep diagnostic. If it fails again, auto mode stops with the exact file it expected.

6. Timeout supervision — Soft timeout warns the LLM to wrap up. Idle watchdog detects stalls. Hard timeout pauses auto mode. Recovery steering nudges the LLM to finish durable output before giving up.

7. Cost tracking — Every unit's token usage and cost is captured, broken down by phase, slice, and model. The dashboard shows running totals and projections. Budget ceilings can pause auto mode before overspending.

8. Adaptive replanning — After each slice completes, the roadmap is reassessed. If the work revealed new information that changes the plan, slices are reordered, added, or removed before continuing.

9. Escape hatch — Press Escape to pause. The conversation is preserved. Interact with the agent, inspect what happened, or just /gsd auto to resume from disk state.

The /gsd Wizard

When you're not in auto mode, /gsd reads disk state and shows contextual options:

• No .gsd/ directory → Start a new project. Discussion flow captures your vision, constraints, and preferences.
• Milestone exists, no roadmap → Discuss or research the milestone.
• Roadmap exists, slices pending → Plan the next slice, or jump straight to auto.
• Mid-task → Resume from where you left off.

The wizard is the on-ramp. Auto mode is the highway.

---

Getting Started

Install

npm install -g gsd-pi

Log in to a provider

First, choose your LLM provider:

gsd
/login

Select from 20+ providers — Anthropic, OpenAI, Google, OpenRouter, GitHub Copilot, and more. If you have a Claude Max or Copilot subscription, the OAuth flow handles everything. Otherwise, paste your API key when prompted.

GSD auto-selects a default model after login. To switch models later:

/model

Use it

Open a terminal in your project and run:

gsd

GSD opens an interactive agent session. From there, you have two ways to work:

/gsd — guided mode. Type /gsd and GSD reads your project state and walks you through whatever's next. No project yet? It helps you describe what you want to build. Roadmap exists? It plans the next slice. Mid-task? It resumes. This is the hands-on mode where you work with the agent step by step.

/gsd auto — autonomous mode. Type /gsd auto and walk away. GSD researches, plans, executes, verifies, commits, and advances through every slice until the milestone is complete. Fresh context window per task. No babysitting.

Two terminals, one project

The real workflow: run auto mode in one terminal, steer from another.

Terminal 1 — let it build

gsd
/gsd auto

Terminal 2 — steer while it works

gsd
/gsd discuss    # talk through architecture decisions
/gsd status     # check progress
/gsd queue      # queue the next milestone

Both terminals read and write the same .gsd/ files on disk. Your decisions in terminal 2 are picked up automatically at the next phase boundary — no need to stop auto mode.

First launch

On first run, GSD prompts for optional API keys (Brave Search, Context7, Jina) for web research and documentation tools. All optional — press Enter to skip any.

Commands

Command	What it does
/gsd	Guided mode — reads project state, walks you through what's next
/gsd auto	Autonomous mode — researches, plans, executes, commits, repeats
/gsd stop	Stop auto mode gracefully
/gsd discuss	Discuss architecture and decisions (works alongside auto mode)
/gsd status	Progress dashboard
/gsd queue	Queue future milestones (safe during auto mode)
/gsd prefs	Model selection, timeouts, budget ceiling
/gsd doctor	Validate .gsd/ integrity, find and fix issues
Ctrl+Alt+G	Toggle dashboard overlay

---

What GSD Manages For You

Context Engineering

Every dispatch is carefully constructed. The LLM never wastes tool calls on orientation.

Artifact	Purpose
PROJECT.md	Living doc — what the project is right now
DECISIONS.md	Append-only register of architectural decisions
STATE.md	Quick-glance dashboard — always read first
M001-ROADMAP.md	Milestone plan with slice checkboxes, risk levels, dependencies
M001-CONTEXT.md	User decisions from the discuss phase
M001-RESEARCH.md	Codebase and ecosystem research
S01-PLAN.md	Slice task decomposition with must-haves
T01-PLAN.md	Individual task plan with verification criteria
T01-SUMMARY.md	What happened — YAML frontmatter + narrative
S01-UAT.md	Human test script derived from slice outcomes

Git Strategy

Branch-per-slice with squash merge. Fully automated.

main:
  feat(M001/S03): auth and session management
  feat(M001/S02): API endpoints and middleware
  feat(M001/S01): data model and type system

gsd/M001/S01 (preserved):
  feat(S01/T03): file writer with round-trip fidelity
  feat(S01/T02): markdown parser for plan files
  feat(S01/T01): core types and interfaces

One commit per slice on main. Per-task history preserved on branches. Git bisect works. Individual slices are revertable.

Verification

Every task has must-haves — mechanically checkable outcomes:

• Truths — Observable behaviors ("User can sign up with email")
• Artifacts — Files that must exist with real implementation, not stubs
• Key Links — Imports and wiring between artifacts

The verification ladder: static checks → command execution → behavioral testing → human review (only when the agent genuinely can't verify itself).

Dashboard

Ctrl+Alt+G or /gsd status opens a real-time overlay showing:

• Current milestone, slice, and task progress
• Auto mode elapsed time and phase
• Per-unit cost and token breakdown by phase, slice, and model
• Cost projections based on completed work
• Completed and in-progress units

---

Configuration

Preferences

GSD preferences live in ~/.gsd/preferences.md (global) or .gsd/preferences.md (project). Manage with /gsd prefs.

---
version: 1
models:
  research: claude-sonnet-4-6
  planning: claude-opus-4-6
  execution: claude-sonnet-4-6
  completion: claude-sonnet-4-6
skill_discovery: suggest
auto_supervisor:
  soft_timeout_minutes: 20
  idle_timeout_minutes: 10
  hard_timeout_minutes: 30
budget_ceiling: 50.00
---

Key settings:

Setting	What it controls
models.*	Per-phase model selection (Opus for planning, Sonnet for execution, etc.)
skill_discovery	auto / suggest / off — how GSD finds and applies skills
auto_supervisor.*	Timeout thresholds for auto mode supervision
budget_ceiling	USD ceiling — auto mode pauses when reached
uat_dispatch	Enable automatic UAT runs after slice completion
always_use_skills	Skills to always load when relevant
skill_rules	Situational rules for skill routing

Bundled Tools

GSD ships with 9 extensions, all loaded automatically:

Extension	What it provides
GSD	Core workflow engine, auto mode, commands, dashboard
Browser Tools	Playwright-based browser for UI verification
Search the Web	Brave Search + Jina page extraction
Context7	Up-to-date library/framework documentation
Background Shell	Long-running process management with readiness detection
Subagent	Delegated tasks with isolated context windows
Slash Commands	Custom command creation
Ask User Questions	Structured user input with single/multi-select
Secure Env Collect	Masked secret collection without manual .env editing

Bundled Agents

Three specialized subagents for delegated work:

Agent	Role
Scout	Fast codebase recon — returns compressed context for handoff
Researcher	Web research — finds and synthesizes current information
Worker	General-purpose execution in an isolated context window

---

Architecture

GSD is a TypeScript application that embeds the Pi coding agent SDK.

gsd (CLI binary)
  └─ loader.ts          Sets PI_PACKAGE_DIR, GSD env vars, dynamic-imports cli.ts
      └─ cli.ts         Wires SDK managers, loads extensions, starts InteractiveMode
          ├─ wizard.ts       First-run API key collection (Brave/Context7/Jina)
          ├─ app-paths.ts    ~/.gsd/agent/, ~/.gsd/sessions/, auth.json
          ├─ resource-loader.ts  Syncs bundled extensions + agents to ~/.gsd/agent/
          └─ src/resources/
              ├─ extensions/gsd/    Core GSD extension (auto, state, commands, ...)
              ├─ extensions/...     10 supporting extensions
              ├─ agents/            scout, researcher, worker
              ├─ AGENTS.md          Agent routing instructions
              └─ GSD-WORKFLOW.md    Manual bootstrap protocol

Key design decisions:

• pkg/ shim directory — PI_PACKAGE_DIR points here (not project root) to avoid Pi's theme resolution collision with our src/ directory. Contains only piConfig and theme assets.
• Two-file loader pattern — loader.ts sets all env vars with zero SDK imports, then dynamic-imports cli.ts which does static SDK imports. This ensures PI_PACKAGE_DIR is set before any SDK code evaluates.
• Always-overwrite sync — npm update -g takes effect immediately. Bundled extensions and agents are synced to ~/.gsd/agent/ on every launch, not just first run.
• State lives on disk — .gsd/ is the source of truth. Auto mode reads it, writes it, and advances based on what it finds. No in-memory state survives across sessions.

---

Requirements

• Node.js ≥ 20.6.0 (22+ recommended)
• An LLM provider — any of the 20+ supported providers (see Use Any Model)
• Git — initialized automatically if missing

Optional:

• Brave Search API key (web research)
• Context7 API key (library docs)
• Jina API key (page extraction)

---

Use Any Model

GSD isn't locked to one provider. It runs on the Pi SDK, which supports 20+ model providers out of the box. Use different models for different phases — Opus for planning, Sonnet for execution, a fast model for research.

Built-in Providers

Anthropic, OpenAI, Google (Gemini), OpenRouter, GitHub Copilot, Amazon Bedrock, Azure OpenAI, Google Vertex, Groq, Cerebras, Mistral, xAI, HuggingFace, Vercel AI Gateway, and more.

OAuth / Max Plans

If you have a Claude Max, Codex, or GitHub Copilot subscription, you can use those directly — Pi handles the OAuth flow. No API key needed.

OpenRouter

OpenRouter gives you access to hundreds of models through a single API key. Use it to run GSD with Llama, DeepSeek, Qwen, or anything else OpenRouter supports.

Per-Phase Model Selection

In your preferences (/gsd prefs), assign different models to different phases:

models:
  research: openrouter/deepseek/deepseek-r1
  planning: claude-opus-4-6
  execution: claude-sonnet-4-6
  completion: claude-sonnet-4-6

Use expensive models where quality matters (planning, complex execution) and cheaper/faster models where speed matters (research, simple completions). GSD tracks cost per-model so you can see exactly where your budget goes.

---

Star History

---

License

Business Source License 1.1

---

The original GSD showed what was possible. This version delivers it.

npm install -g gsd-pi && gsd