npm install -g gsd-pi@latest

What's New in v2.79

DB-Authoritative Runtime State

• Auto-mode coordination tables (#5247) — workers, leases, dispatches, and a command queue are now first-class DB rows, replacing ad-hoc files for cross-process auto coordination.
• auto.lock + paused-session.json → DB (#5250) — phase C pt 2 of the runtime-state migration. The on-disk lockfile and paused-session JSON are gone; lock acquisition, stale-lock detection, and pause state all live in gsd.db.
• Stuck-state migration (#5249) — copyPlanningArtifacts / reconcile deleted; auto-mode writers canonicalize through the DB instead of mirroring artifacts to disk.
• gsd headless recover — non-TTY DB recovery command for unattended environments where the interactive recover flow can't run.
• Doctor surfaces DB locks — gsd doctor reports DB-backed stale locks and flags exhausted run-uat retry counters so wedged runs are visible without log archaeology.

Workspace & Worktree Isolation

• GsdWorkspace + MilestoneScope handle types — workspace identity is now an explicit handle threaded through writers, metrics, and the DB connection instead of a module singleton.
• Symlink-safe canonicalization — deriveState read root and cache key are canonicalized; path normalization unified on realpathSync.native; gsdRootCache keys normalized and decoupled from per-turn cache clears; git-root anchor guarded against ~/.gsd resolution.
• Worktree-scoped DB + metrics — gsd-db connections and metrics ledgers are scoped by workspace identity, so concurrent milestones in separate worktrees can't cross-contaminate state.
• Worktree cwd anchoring — subagent dispatch anchors to the canonical worktree path, mergeAndExit anchors cwd at project root (closes #5079), MCP cwd is hardened against drift, and dispatch stops on cwd anchor failures.
• Slice isolation through resolver (#5246) — slice merge isolation routed through the worktree resolver; originalBase checks use isSamePath instead of string equality; auto-worktree validates milestoneId match in ByScope wrappers.
• Worktree CLI commands — gsd worktree {list, merge, clean, remove} exposed in the TUI dispatcher.

Deep Planning Mode (Phase 11)

• /gsd new-project --deep — opt-in deep mode for new projects, with research-decision and research-project dispatch units, deep-mode artifact validators, and gated approval flows that pause the milestone instead of aborting on grounding/discovery questions.
• EVAL-REVIEW system — /gsd eval-review command, frontmatter schema, pre-ship soft warning when EVAL-REVIEW status is incomplete, and registration in the catalog + ops dispatcher.
• Project-shape-aware discuss depth — discuss-phase questioning depth scales via the project-shape classifier; tiny apps cap research and auto-skip stale research blockers; deep research is opt-in and blocked while a marker is in flight.
• Approval-gate hardening — deep approval gates verified, opening interview question protected from approval abort, plain-text setup approvals gated, deep setup state guarded against phantom transitions.

Auto Pipeline & Dispatch

• Delegation-policy verdicts — dispatch actions are annotated with a per-tool background-safety policy verdict; the policy itself is codified instead of inferred per call.
• Reactive-execute default — auto-dispatch defaults to reactive-execute when ≥3 ready tasks are queued, replacing the always-sequential fallback.
• Proactive rate limiting (#2996) — min_request_interval_ms preference paces auto-mode requests; the interval is stamped at dispatch.
• Manifest-driven skill surfacing — auto-prompts surfaces manifest skills via recommendations + auto-match; planning-dispatch mode added to the unit manifest for slice plan/complete; runtime tools-policy enforced for planning units (#4934).
• Subagent telemetry — dispatch telemetry, stronger prompt guidelines, and model-override threading (?? consistently used for modelOverride).

MCP, Models & Cross-Platform

• Global MCP config — mcp-client reads ~/.gsd/mcp.json for user-level MCP server config.
• ask_user_questions over MCP — host elicitation tried before remote channel; multi-select array shape preserved; explicit cancellation handled; remote answers normalized into structuredContent.
• Model routing overhaul — cross-provider tier resolution, provider-agnostic profile-tier defaults, disabled-provider routing denylist, resolved tier model IDs normalized, and findModelForTier with behavioral tests.
• Ollama — configurable probe/request timeouts via env vars (clamped); cloud / long-variant context windows reported correctly.
• Windows fixes — home directory resolved correctly (#5015), Path env lookup repaired, Windows-safe env CLI shims, DEP0190 avoided in Claude CLI binary probes, tool-bootstrap skipped when tools are on PATH.
• Anthropic prompt-cache preserved (#5019) — pi-coding-agent and gsd no longer thrash the cache on dispatch.

Git, GitHub Sync & Reliability

• Integration-branch self-merge guard (#5024) — milestone refuses to self-merge when the integration branch equals the milestone branch; self-merge ref guard normalized.
• Slice-cadence safety — integration branch used for slice cadence, dirty worktree state preserved on merge, checked-out slice worktrees advance safely, slice PRs deferred until completion, slice-PR sync stays retryable on failure.
• Milestone-ID reservation — DB rows included in reservation; ghost IDs reused in nextMilestoneId to close gaps; ensurePreconditions guarded against phantom IDs (#4996); orphan milestone-dir doctor check (#4996); milestone-dir creation deferred until first artifact write.
• Auto-commit hygiene — task commits scoped to reported files, generated commit subjects sanitized, user hooks run on automated commits, milestone-tagged commits bound when .gsd/ is gitignored (#5033), startup blocked on git index.lock.
• GitHub sync — issues no longer closed before delivery, failed task closure / slice PR sync stay retryable, config cache scoped by project, safe git environment used.

Safety, Recovery & Hardening

• Policy-block pause through dispatch errors — pause state is preserved when dispatch errors out mid-policy-block.
• Skip-validation persistence — skip-validation state persists and gate rows are cleared on recover.
• Cancelled-gate hard block — redirected to ask_user_questions; false plain-text claim dropped from the message.
• Write-gate basePath required — process.cwd() defaults removed; basePath threaded through pre-existing tests.
• Atomic metrics writes — parallel-mode metrics.json writes merge atomically; ledger cache invalidated after prune; saveLedger aborts when lock not acquired; stale-lock detection adds PID stamp + async yield.
• Auto-worktree teardown — activeWorkspace guaranteed cleared on teardown failure; teardown try/finally broadened to cover chdir; cleanup steps mirrored on the abort path; warning emitted on resume when persisted worktree is missing.
• Empty-turn nudge — no longer auto-replies to user questions; deferred on mid-line approval prompts.
• Refuses project writes from $HOME — and surfaces real SQL errors from capture_thought instead of swallowing them.

VS Code & TUI

• Checkpoint tree view — registered in the VS Code extension; checkpoint file existence restored; RPC file-mutation events tracked; agent diff scoped to tracked files.
• TUI image paste — pasted images preserved on regular submit.
• Bundled /gsd slash command protected — core handler refuses to overwrite the bundled command.

See the full Changelog for the complete v2.79 entry and prior releases.

Documentation

Full documentation is in the docs/ directory:

User Guides

• Getting Started — install, first run, basic usage
• Auto Mode — autonomous execution deep-dive
• Configuration — all preferences, models, git, and hooks
• Custom Models — add custom providers (Ollama, vLLM, LM Studio, proxies)
• Token Optimization — profiles, context compression, complexity routing
• Cost Management — budgets, tracking, projections
• Git Strategy — worktree isolation, branching, merge behavior
• Parallel Orchestration — run multiple milestones simultaneously
• Working in Teams — unique IDs, shared artifacts
• Skills — bundled skills, discovery, custom authoring
• Commands Reference — all commands and keyboard shortcuts
• Troubleshooting — common issues, doctor, forensics, recovery
• Visualizer — workflow visualizer with stats and discussion status
• Remote Questions — route decisions to Slack or Discord when human input is needed
• Dynamic Model Routing — complexity-based model selection and budget pressure
• Web Interface — browser-based project management and real-time progress
• Migration from v1 — .planning → .gsd migration
• Docker Sandbox — run GSD auto mode in an isolated Docker container

Developer Docs

• Architecture — system design and dispatch pipeline
• CI/CD Pipeline — three-stage promotion pipeline (Dev → Test → Prod)
• E2E Testing — real-process CLI/runtime coverage and CI runner expectations
• Pipeline Simplification (ADR-003) — merged research into planning, mechanical completion
• VS Code Extension — chat participant, sidebar dashboard, RPC integration

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.

Migrating from v1

Note: Migration works best with a ROADMAP.md file for milestone structure. Without one, milestones are inferred from the phases/ directory.

If you have projects with .planning directories from the original Get Shit Done, you can migrate them to GSD-2's .gsd format:

# From within the project directory
/gsd migrate

# Or specify a path
/gsd migrate ~/projects/my-old-project

The migration tool:

• Parses your old PROJECT.md, ROADMAP.md, REQUIREMENTS.md, phase directories, plans, summaries, and research
• Maps phases → slices, plans → tasks, milestones → milestones
• Preserves completion state ([x] phases stay done, summaries carry over)
• Consolidates research files into the new structure
• Shows a preview before writing anything
• Optionally runs an agent-driven review of the output for quality assurance

Supports format variations including milestone-sectioned roadmaps with <details> blocks, bold phase entries, bullet-format requirements, decimal phase numbering, and duplicate phase numbers across milestones.

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:

Plan (with integrated research) → Execute (per task) → Complete → Reassess Roadmap → Next Slice
                                                                                      ↓ (all slices done)
                                                                              Validate Milestone → Complete Milestone

Plan scouts the codebase, researches relevant docs, and 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 — then runs configured verification commands (lint, test, etc.) with auto-fix retries. Complete writes the summary, UAT script, marks the roadmap, and commits with meaningful messages derived from task summaries. Reassess checks if the roadmap still makes sense given what was learned. Validate Milestone runs a reconciliation gate after all slices complete — comparing roadmap success criteria against actual results before sealing the milestone.

/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 the GSD database at the project root. It derives the next unit of work from authoritative SQLite state, 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 persists the result to the database, refreshes markdown projections such as STATE.md, and dispatches the next unit.

The database is authoritative for milestones, slices, tasks, requirements, decisions, summaries, and completion status. Markdown under .gsd/ is a rendered projection for review, prompts, and git-friendly history; it is not a runtime fallback unless you explicitly run a recovery/import command. In worktree mode, project-root DB state remains authoritative and worktree markdown projections are not synced back as state.

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. Context Mode — Context Mode is enabled by default and gives eligible auto-mode units guidance for preserving context. Agents are steered toward gsd_exec for noisy scans, builds, tests, and diagnostics; capped stdout/stderr and metadata are saved under .gsd/exec/ while only a short digest enters the conversation. gsd_exec_search lets agents reuse prior runs instead of repeating expensive checks, and gsd_resume reads a prior compaction snapshot from .gsd/last-snapshot.md when one exists. Opt out with context_mode.enabled: false to disable Context Mode guidance, snapshot injection, gsd_exec, gsd_exec_search, and gsd_resume; tune sandbox timeout/output caps and environment forwarding with context_mode.exec_timeout_ms, context_mode.exec_stdout_cap_bytes, context_mode.exec_digest_chars, and context_mode.exec_env_allowlist.

4. Git isolation — When git.isolation is set to worktree or branch, each milestone runs on its own milestone/<MID> branch (in a worktree or in-place). All slice work commits sequentially — no branch switching, no merge conflicts. When the milestone completes, it's squash-merged to main as one clean commit. The default is none (work on the current branch), configurable via preferences. If worktree is configured in a repo with no committed HEAD, GSD temporarily behaves as none until the first commit exists because git worktrees need a committed start point.

5. Crash recovery — Auto mode persists worker state, unit-dispatch state, and paused-session metadata in the project-root SQLite database. If the session dies, the next /gsd auto reconstructs the interrupted unit from DB-backed runtime state, reads the surviving session file, synthesizes a recovery briefing from every tool call that made it to disk, and resumes with full context. Parallel orchestrator IPC still lives under .gsd/parallel/, so multi-worker sessions survive crashes too. In headless mode, crashes trigger automatic restart with exponential backoff (default 3 attempts).

6. Provider error recovery — Transient provider errors (rate limits, 500/503 server errors, overloaded) auto-resume after a delay. Permanent errors (auth, billing) pause for manual review. The model fallback chain retries transient network errors before switching models.

7. Stuck and artifact detection — A sliding-window detector identifies repeated dispatch patterns (including multi-unit cycles). Missing expected artifacts use a separate bounded path: GSD retries artifact verification up to 3 times with failure context, then pauses auto mode with the missing artifact error instead of looping indefinitely.

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

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

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

11. Verification enforcement — Configure shell commands (npm run lint, npm run test, etc.) that run automatically after task execution. Failures trigger auto-fix retries before advancing. Auto-discovered checks from package.json run in advisory mode — they log warnings but don't block on pre-existing errors. Configurable via verification_commands, verification_auto_fix, and verification_max_retries preferences.

12. Milestone validation — After all slices complete, a validate-milestone gate compares roadmap success criteria against actual results before sealing the milestone.

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

/gsd and /gsd next — Step Mode

By default, /gsd runs in step mode: the same state machine as auto mode, but it pauses between units with a wizard showing what completed and what's next. You advance one step at a time, review the output, and continue when ready.

• 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, execute one task, or switch to auto.
• Mid-task → Resume from where you left off.

/gsd next is an explicit alias for step mode. You can switch from step → auto mid-session via the wizard.

Step mode 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 — step mode. Type /gsd and GSD executes one unit of work at a time, pausing between each with a wizard showing what completed and what's next. Same state machine as auto mode, but you stay in the loop. No project yet? It starts the discussion flow. Roadmap exists? It plans or executes the next 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 coordinate through the same project-root GSD runtime on local disk. The SQLite database is authoritative, .gsd/ markdown is refreshed from it, and your decisions in terminal 2 are picked up at the next phase boundary without stopping auto mode.

Headless mode — CI and scripts

gsd headless runs any /gsd command without a TUI. Designed for CI pipelines, cron jobs, and scripted automation.

# Run auto mode in CI
gsd headless --timeout 600000

# Create and execute a milestone end-to-end
gsd headless new-milestone --context spec.md --auto

# One unit at a time (cron-friendly)
gsd headless next

# Instant JSON snapshot (no LLM, ~50ms)
gsd headless query

# Force a specific pipeline phase
gsd headless dispatch plan

Headless auto-responds to interactive prompts, detects completion, and exits with structured codes: 0 complete, 1 error/timeout, 2 blocked. Auto-restarts on crash with exponential backoff. Use gsd headless query for instant, machine-readable state inspection — returns phase, next dispatch preview, and parallel worker costs as a single JSON object without spawning an LLM session. Pair with remote questions to route decisions to Slack or Discord when human input is needed.

Multi-session orchestration — headless mode supports DB-backed coordination across multiple GSD workers on the same machine. Worker registration, milestone leases, unit dispatch tracking, and command delivery live in .gsd/gsd.db, while .gsd/parallel/ remains a local runtime area for per-milestone locks and isolation artifacts.

First launch

On first run, GSD launches a branded setup wizard that walks you through LLM provider selection (OAuth or API key), then optional tool API keys (Brave Search, Context7, Jina, Slack, Discord). Every step is skippable — press Enter to skip any. If you have an existing Pi installation, your provider credentials (LLM and tool keys) are imported automatically. Run gsd config anytime to re-run the wizard.

Commands

What GSD Manages For You

Context Engineering

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

Git Strategy

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

main:
  docs(M001/S04): workflow documentation and examples
  fix(M001/S03): bug fixes and doc corrections
  feat(M001/S02): API endpoints and middleware
  feat(M001/S01): data model and type system

gsd/M001/S01 (deleted after merge):
  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 squash commit per milestone on main (or whichever branch you started from). The worktree is torn down after merge. Git bisect works. Individual milestones are revertable. Commit messages are generated from task summaries — no more generic "complete task" messages.

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

HTML Reports

After a milestone completes, GSD auto-generates a self-contained HTML report in .gsd/reports/. Each report includes project summary, progress tree, slice dependency graph (SVG DAG), cost/token metrics with bar charts, execution timeline, changelog, and knowledge base sections. No external dependencies — all CSS and JS are inlined, printable to PDF from any browser.

An auto-generated index.html shows all reports with progression metrics across milestones.

• Automatic — generated after milestone completion (configurable via auto_report preference)
• Manual — run /gsd export --html anytime

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:
    model: claude-opus-4-7
    fallbacks:
      - openrouter/z-ai/glm-5
      - openrouter/minimax/minimax-m2.5
  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
unique_milestone_ids: true
verification_commands:
  - npm run lint
  - npm run test
auto_report: true
---

Key settings:

Agent Instructions

Place an AGENTS.md file in any directory to provide persistent behavioral guidance for that scope. Pi core loads AGENTS.md automatically (with CLAUDE.md as a fallback) at both user and project levels. Use these files for coding standards, architectural decisions, domain terminology, or workflow preferences.

Note: The legacy agent-instructions.md format (~/.gsd/agent-instructions.md and .gsd/agent-instructions.md) is deprecated and no longer loaded. Migrate any existing instructions to AGENTS.md or CLAUDE.md.

Debug Mode

Start GSD with gsd --debug to enable structured JSONL diagnostic logging. Debug logs capture dispatch decisions, state transitions, and timing data for troubleshooting auto-mode issues.

Token Optimization

GSD includes a coordinated token optimization system that reduces usage by 40-60% on cost-sensitive workloads. Set a single preference to coordinate model tier selection, phase skipping, and context compression:

token_profile: budget # or balanced (default), quality

Complexity-based routing automatically classifies tasks as simple/standard/complex and routes to appropriate available models. Token profiles define provider-agnostic tier intentions, so simple docs tasks use a light-tier configured model and complex architectural work can use a heavy-tier configured model. The classification is heuristic (sub-millisecond, no LLM calls) and learns from outcomes via a persistent routing history.

Budget pressure graduates model downgrading as you approach your budget ceiling — 50%, 75%, and 90% thresholds progressively shift work to cheaper tiers.

See the full Token Optimization Guide for details.

Bundled Tools

GSD ships with 24 extensions, all loaded automatically:

Bundled Agents

Five specialized subagents for delegated work:

Working in teams

The best practice for working in teams is to ensure unique milestone names across all branches (by using unique_milestone_ids) and checking in the right .gsd/ artifacts to share valuable context between teammates.

Suggested .gitignore setup

# ── GSD: Runtime / Ephemeral (per-developer, per-session) ──────────────────
# Auto-mode dispatch tracker — prevents re-running completed units (includes archived per-milestone files)
.gsd/completed-units*.json
# State manifest — workflow state for recovery
.gsd/state-manifest.json
# Derived state projection — regenerated from the authoritative database
.gsd/STATE.md
# Per-developer token/cost accumulator
.gsd/metrics.json
# Raw JSONL session dumps — crash recovery forensics, auto-pruned
.gsd/activity/
# Unit execution records — dispatch phase, timeouts, and recovery tracking
.gsd/runtime/
# Git worktree working copies
.gsd/worktrees/
# Parallel runtime locks and per-milestone isolation artifacts
.gsd/parallel/
# SQLite database and WAL sidecars — authoritative runtime state, local only
.gsd/gsd.db*
# Daily-rotated event journal — structured event log for forensics
.gsd/journal/
# Doctor run history — diagnostic check results
.gsd/doctor-history.jsonl
# Workflow event log — structured event stream
.gsd/event-log.jsonl
# Generated HTML reports (regenerable via /gsd export --html)
.gsd/reports/
# Session-specific interrupted-work markers
.gsd/milestones/**/continue.md
.gsd/milestones/**/*-CONTINUE.md

Unique Milestone Names

Create or amend your .gsd/PREFERENCES.md file within the repo to include unique_milestone_ids: true e.g.

---
version: 1
unique_milestone_ids: true
---

With the above .gitignore set up, the .gsd/PREFERENCES.md file is checked into the repo ensuring all teammates use unique milestone names to avoid collisions.

Milestone names will now be generated with a 6 char random string appended e.g. instead of M001 you'll get something like M001-ush8s3

Migrating an existing git ignored .gsd/ folder

1. Ensure you are not in the middle of any milestones (clean state)
2. Update the .gsd/ related entries in your .gitignore to follow the Suggested .gitignore setup section under Working in teams (ensure you are no longer blanket ignoring the whole .gsd/ directory)
3. Update your .gsd/PREFERENCES.md file within the repo as per section Unique Milestone Names
4. If you want to update all your existing milestones use this prompt in GSD: I have turned on unique milestone ids, please update all old milestone ids to use this new format e.g. M001-abc123 where abc123 is a random 6 char lowercase alpha numeric string. Update all references in all .gsd file contents, file names and directory names. Validate your work once done to ensure referential integrity.
5. Commit to git

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
          ├─ headless.ts     Headless orchestrator (spawns RPC child, auto-responds, detects completion)
          ├─ onboarding.ts   First-run setup wizard (LLM provider + tool keys)
          ├─ wizard.ts       Env hydration from stored auth.json credentials
          ├─ 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/...     21 supporting extensions
              ├─ agents/            scout, researcher, worker, javascript-pro, typescript-pro
              └─ 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.
• DB-authoritative state — the project-root GSD database is the runtime source of truth. .gsd/ markdown files are rendered projections for review, prompt context, and git history. No in-memory state survives across sessions.

Requirements

• Node.js ≥ 22.0.0 (24 LTS 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)
• Tavily API key (web research — alternative to Brave)
• Google Gemini API key (web research via Gemini Search grounding)
• 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, Anthropic (Vertex AI), 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.

⚠️ Important: Using OAuth tokens from subscription plans outside their native applications may violate the provider's Terms of Service. In particular:

• Google Gemini — Using Gemini CLI or Antigravity OAuth tokens in third-party tools has resulted in Google account suspensions. This affects your entire Google account, not just the Gemini service. Use a Gemini API key instead.
• Claude Max — Anthropic's ToS may not explicitly permit OAuth use outside Claude's own applications.
• GitHub Copilot — Usage outside GitHub's own tools may be restricted by your subscription terms.

GSD supports API key authentication for all providers as the safe alternative. We strongly recommend using API keys over OAuth for Google Gemini.

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:
    model: claude-opus-4-7
    fallbacks:
      - openrouter/z-ai/glm-5
  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). Each phase accepts a simple model string or an object with model and fallbacks — if the primary model fails (provider outage, rate limit, credit exhaustion), GSD automatically tries the next fallback. GSD tracks cost per-model so you can see exactly where your budget goes.

Ecosystem

Star History

License

MIT License