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@latestGSD now provisions a managed RTK binary on supported macOS, Linux, and Windows installs to compress shell-command output in
bash,async_bash,bg_shell, and verification flows. GSD forcesRTK_TELEMETRY_DISABLED=1for all managed invocations. SetGSD_RTK_DISABLED=1to disable the integration.
📋 NOTICE: New to Node on Mac? If you installed Node.js via Homebrew, you may be running a development release instead of LTS. Read this guide to pin Node 24 LTS and avoid compatibility issues.
/gsd auto process is SIGKILL'd, sleep-killed, or otherwise crashes, the auto.lock file is left behind with a dead PID. Previously you had to wait out a 30-minute stale window before /gsd would resume. The new stale-worker drift handler verifies the PID is alive and clears orphaned locks proactively on startup.ROADMAP.md/CONTEXT.md/SUMMARY.md) but never re-imported, dispatch couldn't see it. The unregistered-milestone handler now imports those rows idempotently before dispatch.ROADMAP.md (parsed slice sequence + depends declarations) and the corresponding DB slice rows is detected per-milestone and reconciled via importer upserts plus an explicit syncSliceDependencies pass.completed_at are now backfilled from SUMMARY.md mtime, deterministically and idempotently. Tasks are checked independently of their parent slice status (a bug in the first cut nested task iteration behind slice completion)./gsd parallel start and slice-parallel-dispatch now run reconciliation at the parent before spawning auto-loop workers, so workers don't independently race on shared drift. Gate failures surface a typed exit reason (slice-parallel-reconciliation-failed) and a user-visible message instead of a confused hang.gitServiceFactory. Lifecycle verbs are now first-class: adoptOrphanWorktree, adoptSessionRoot, resumeFromPausedSession, and restoreToProjectRoot are explicit entry points, and the stop-path routes through restoreToProjectRoot instead of ad-hoc cleanup. mergeMilestoneStandalone was extracted and mergeMilestoneToMain was privatized.s.basePath = s.originalBasePath fallbacks were removed from both auto.ts stop-path catch blocks (the verb assigns basePath before any throwable work, so the fallback was unreachable). The public WorktreeLifecycleDeps interface dropped 15 @deprecated optional fields; the active dep bag is now three fields (gitServiceFactory, worktreeProjection, mergeMilestoneToMain). Test fixtures move to a dedicated WorktreeLifecycleTestOverrides type.complete-slice closeout is read-only — the closeout prompt is no longer allowed to write project files, removing a class of races where closeout edits could fight with the next slice's setup. Write-gate planning and prompt contracts were updated to enforce this.verification-retry-policy.ts adds bounded exponential backoff and runs stuck detection between attempts, so transient verification failures (slow tools, flaky LLM calls) no longer spin in tight retry loops..gitignored task key files so the working tree stays clean across slices.render-kit. The result is a more consistent visual language across overlays, with refreshed reference designs (docs/dev/tui-recommended-design.html, tui-render-options.html) and expanded test coverage for the new components.CompletionDashboardSnapshot summarizing success criteria results, definition-of-done results, requirement outcomes, deviations, follow-ups, key decisions, key files, lessons learned, total cost, total tokens, cache hit rate, and slice progress. You no longer have to scroll back through the transcript to see what a milestone actually delivered.See the full Changelog for the complete v2.82 entry and prior releases.
+types imports, gsd_exec write gating, project-save behavior, and home-directory fallback behavior were tightened.gsd.dbGsdWorkspace and MilestoneScope handles, symlink-safe canonicalization, worktree-scoped DB/metrics, cwd anchoring, and gsd worktree {list, merge, clean, remove}/gsd new-project --deep, research dispatch units, EVAL-REVIEW, project-shape-aware questioning, and approval-gate hardeningask_user_questions over MCP, provider-agnostic model routing, Ollama timeouts, Windows fixes, and Anthropic prompt-cache preservation/gsd slash command protectiongit.collapse_cadence: "milestone" | "slice" shrinks the orphan window per-slice; pair with git.milestone_resquash: true to collapse to one milestone commitsummarizeWorktreeTelemetry; /gsd forensics worktree section with worktree-orphan and worktree-unmerged-exit anomaliesresolveCanonicalMilestoneRoot routes validators through the live worktreecomplete-slice, research-milestone, run-uat, reassess-roadmap build context through the manifest composergsd extensions install / update / uninstall / list / info / validate; topological load order; cmux↔gsd decoupling via cmux-events; extracted @gsd-extensions/google-searchxhigh thinking level; auth mode in /model; permission granularity picker; headless auto default → bypassPermissions (#4657).git/index.lock 5-min gate, env overlay strip, rebase/cherry-pick/revert detection, working-tree stash before reset --hard, unborn-branch worktree guard, user hooks + commit.gpgsign on auto-commits.gsd/ state writes; compaction correctness fix (#4665); write-gate hardening (#4950); auto state-machine non-retriable policy errors (#4973), baseline restoration (#4961, #4966); slice + crash recovery; empty-turn recovery shape canonicalizedgsd_exec_search, gsd_resume, and sandboxed tool-output paths for context-mode flowsmemories table is now authoritative; structured_fields adds typed metadata; decisions and KNOWLEDGE patterns/lessons are memory-backed projections after the cutover/gsd extract-learnings — extracts decisions, lessons, patterns, and surprises into LEARNINGS.md.gsd/extensions/ (#3338)/gsd languagecomplete-milestone failure (#4175)/gsd auto bootstrap (#4122)/api/show (#4017)gsd.db blocked via hooks (#3674)bypassPermissions with safe built-ins pre-authorizedsubagent_model preference wired through to dispatch prompt buildersbefore_model_select hook, and task metadata extractioncache_control breakpoints added to tool definitions for improved prompt cachingsecure_env_collect tool uses MCP form elicitation to collect secrets without exposing values in tool outputisError: truederiveStateFromDb god function extracted into composable, testable helpersFull documentation is in the docs/ directory:
.planning → .gsd migrationThe 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:
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 | Worktree isolation, sequential commits, 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 |
| Verification | Manual | Automated verification commands with auto-fix retries |
| Reporting | None | Self-contained HTML reports with metrics and dep graphs |
| Parallel execution | None | Multi-worker parallel milestone orchestration |
Note: Migration works best with a
ROADMAP.mdfile for milestone structure. Without one, milestones are inferred from thephases/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:
PROJECT.md, ROADMAP.md, REQUIREMENTS.md, phase directories, plans, summaries, and research[x] phases stay done, summaries carry over)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.
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.
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 before the task closeout commit or snapshot is published. Failed or incomplete verification blocks execute-task closeout. 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.
When progressive planning is enabled, the first slice is fully planned up front while later slices may appear in M###-ROADMAP.md with a `[sketch]` badge. A sketch slice has an approved title, dependency shape, demo line, and scope boundary, but it has not yet been expanded into task plans; auto mode runs refine-slice just before execution to turn the sketch into a full slice plan using the latest prior-slice summaries.
/gsd auto — The Main EventThis 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, summaries, and completion status. Durable decisions and project knowledge are stored in the memories table: decisions are architecture memories, and KNOWLEDGE patterns/lessons are pattern/gotcha memories. 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, artifact/projection writes are rendered under the active worktree-local .gsd/, while the project-root DB remains authoritative runtime state.
KNOWLEDGE.md is hybrid: rules remain file-canonical, while patterns and lessons are stored in the memories table and rendered back into KNOWLEDGE.md on the next session-start projection. Existing pattern and lesson rows are backfilled into memories before projection, so newly captured patterns and lessons may appear in memory-backed prompt context before the file view refreshes.
What happens under the hood:
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."
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.
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.
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.
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).
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.
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.
Timeout supervision — Soft timeout warns the LLM to wrap up. Idle watchdog detects stalls. Hard timeout starts recovery and only pauses auto mode if durable progress cannot be made. Runtime progress is recorded under .gsd/runtime/, and journal events close out unit, finalize, and iteration phases for later forensics.
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.
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.
Verification enforcement — Configure simple executable commands (npm run lint, npm run test, etc.) that run automatically after task execution. Verification commands must not use shell composition or control syntax such as pipes, redirects, semicolons, backticks, or command substitution. Failures trigger auto-fix retries before advancing. Execute-task commits and snapshots are deferred until verification passes; failed or incomplete verification blocks closeout instead of publishing changes. Auto-discovered checks from package.json and Python pytest project markers (python-project) 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.
Milestone validation — After all slices complete, a validate-milestone gate compares roadmap success criteria against actual results before sealing the milestone.
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 ModeBy 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.
.gsd/ directory → Start a new project. Discussion flow captures your vision, constraints, and preferences./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.
npm install -g gsd-pi
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
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.
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.
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.
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.
| Command | What it does |
|---|---|
/gsd | Step mode — executes one unit at a time, pauses between each |
/gsd next | Explicit step mode (same as bare /gsd) |
/gsd auto | Autonomous mode — researches, plans, executes, commits, repeats |
/gsd new-project [--deep] | Bootstrap a project with staged project-level discovery |
/gsd quick | Execute a quick task with GSD guarantees, skip 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 rethink | Conversational project reorganization |
/gsd mcp | MCP server status and connectivity |
/gsd status | Progress dashboard |
/gsd brief <mode> | Generate a visual HTML brief (diagram, plan, diff, recap, table, slides) |
/gsd queue | Queue/reorder future milestones (pending, queued, or legacy planned; safe during auto mode) |
/gsd prefs | Model selection, timeouts, budget ceiling |
/gsd migrate | Migrate a v1 .planning directory to .gsd format |
/gsd help | Categorized command reference for all GSD subcommands |
/gsd mode | Switch workflow mode (solo/team) with coordinated defaults |
/gsd workflow | Unified workflow plugins — list, run <name>, install, info, validate |
/gsd start <template> | Launch a bundled or custom workflow template (bugfix, release, etc.) |
/gsd forensics | Full-access GSD debugger for auto-mode failure investigation |
/gsd cleanup | Archive phase directories from completed milestones |
/gsd doctor | Runtime health checks — issues surface across widget, visualizer, and reports |
/gsd keys | API key manager — list, add, remove, test, rotate, doctor |
/gsd logs | Browse activity, debug, and metrics logs |
/gsd export --html | Generate HTML report for current or completed milestone |
/worktree (/wt) | Git worktree lifecycle — create, switch, merge, remove |
/gsd worktree (/gsd wt) | TUI worktree management — list, merge, clean, remove with safety checks |
/voice | Toggle real-time speech-to-text (macOS, Linux) |
/exit | Graceful shutdown — saves session state before exiting |
/kill | Kill GSD process immediately |
/clear | Start a new session (alias for /new) |
Ctrl+Alt+G | Toggle dashboard overlay |
Ctrl+Alt+V | Toggle voice transcription |
Ctrl+Alt+B | Show background shell processes |
Alt+V | Paste clipboard image (macOS) |
gsd config | Re-run the setup wizard (LLM provider + tool keys) |
gsd update | Update GSD to the latest version |
gsd headless [cmd] | Run /gsd commands without TUI (CI, cron, scripts) |
gsd headless query | Instant JSON snapshot — state, next dispatch, costs (no LLM) |
gsd --continue (-c) | Resume the most recent session for the current directory |
gsd --worktree (-w) | Launch an isolated worktree session for the active milestone |
gsd sessions | Interactive session picker — browse and resume any saved session |
Every dispatch is carefully constructed. The LLM never wastes tool calls on orientation.
| Artifact | Purpose |
|---|---|
gsd.db | Authoritative runtime state for hierarchy and completion |
PROJECT.md | Living doc — what the project is right now |
REQUIREMENTS.md | Project-level capability contract and out-of-scope list |
DECISIONS.md | Projected register of memory-backed architectural decisions |
KNOWLEDGE.md | Hybrid knowledge projection: manual Rules plus memory-backed Patterns/Lessons |
RUNTIME.md | Runtime context — API endpoints, env vars, services (v2.39) |
runtime/research-decision.json | Deep-mode marker for project research vs skip |
research/*.md | Optional deep-mode project research: stack, features, architecture, pitfalls |
STATE.md | Quick-glance dashboard rendered from the database |
M001-ROADMAP.md | Milestone plan with slice checkboxes, risk levels, dependencies, and `[sketch]` badges for slices awaiting refine-slice |
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 |
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.
Every task has must-haves — mechanically checkable outcomes:
The verification ladder: static checks → command execution → behavioral testing → human review (only when the agent genuinely can't verify itself).
.gsd/KNOWLEDGE.md remains the human-readable register for durable project knowledge, but the memory store is now authoritative for generated Patterns and Lessons. On startup, GSD backfills existing ## Patterns and ## Lessons Learned rows into gsd.db memories, then rewrites KNOWLEDGE.md as a hybrid projection: the manual ## Rules section is preserved from the file, while Patterns and Lessons are rendered from the backfilled memory rows.
Keep hand-authored operating rules in ## Rules or add them with /gsd knowledge rule. Patterns and Lessons that agents discover are retrieved through the memory system for prompts and projected back into KNOWLEDGE.md for review, reports, and git history.
Ctrl+Alt+G or /gsd status opens a real-time overlay showing:
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.
auto_report preference)/gsd export --html anytimeGSD 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:
| Setting | What it controls |
|---|---|
models.* | Per-phase model selection — string for a single model, or {model, fallbacks} for automatic failover |
planning_depth | light / deep — opt into staged project discovery before milestone planning |
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 |
skill_staleness_days | Skills unused for N days get deprioritized (default: 60, 0 = disabled) |
unique_milestone_ids | Uses unique milestone names to avoid clashes when working in teams of people |
git.isolation | none (default), worktree, or branch — enable worktree or branch isolation for milestone work. worktree requires a committed HEAD; zero-commit repos temporarily run as none |
git.manage_gitignore | Set false to prevent GSD from modifying .gitignore |
context_mode.enabled | Context Mode is default-on; set false to disable prompt guidance, snapshot injection, gsd_exec, gsd_exec_search, and gsd_resume |
context_mode.exec_timeout_ms | Timeout for sandboxed gsd_exec runs (default: 30000) |
context_mode.exec_stdout_cap_bytes | Persisted stdout cap for gsd_exec output (default: 1048576) |
context_mode.exec_digest_chars | Trailing stdout characters returned to the agent context (default: 300) |
context_mode.exec_env_allowlist | Environment variables forwarded to sandboxed gsd_exec runs in addition to PATH and HOME |
verification_commands | Array of simple executable commands to run after task execution (e.g., ["npm run lint", "npm run test"]); avoid pipes, redirects, semicolons, backticks, and command substitution |
verification_auto_fix | Auto-retry on verification failures (default: true) |
verification_max_retries | Max retries for verification failures (default: 2) |
phases.require_slice_discussion | Pause auto-mode before each slice for human discussion review |
auto_report | Auto-generate HTML reports after milestone completion (default: true) |
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.mdformat (~/.gsd/agent-instructions.mdand.gsd/agent-instructions.md) is deprecated and no longer loaded. Migrate any existing instructions toAGENTS.mdorCLAUDE.md.
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.
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
| Profile | Savings | What It Does |
|---|---|---|
budget | 40-60% | Light/standard tier defaults, skip research/reassess, minimal context inlining |
balanced | 10-20% | Standard tier for core work, light tier for simple work, standard context |
quality | 0% | Heavy tier for planning, standard tier for core work, full context |
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.
GSD ships with 24 extensions, all loaded automatically:
| Extension | What it provides |
|---|---|
| GSD | Core workflow engine, auto mode, commands, dashboard |
| Browser Tools | Playwright-based browser with form intelligence, intent-ranked element finding, semantic actions, PDF export, session state persistence, network mocking, device emulation, structured extraction, visual diffing, region zoom, test code generation, and prompt injection detection |
| Search the Web | Brave Search, Tavily, or Jina page extraction |
| Google Search | Gemini-powered web search with AI-synthesized answers |
| Context7 | Up-to-date library/framework documentation |
| Background Shell | Long-running process management with readiness detection |
| Async Jobs | Background bash commands with job tracking and cancellation |
| Subagent | Delegated tasks with isolated context windows |
| GitHub | Full-suite GitHub issues and PR management via /gh command |
| Mac Tools | macOS native app automation via Accessibility APIs |
| MCP Client | Native MCP server integration via @modelcontextprotocol/sdk |
| Voice | Real-time speech-to-text transcription (macOS, Linux — Ubuntu 22.04+) |
| 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 |
| Remote Questions | Route decisions to Slack/Discord when human input is needed in headless/CI mode |
| Universal Config | Discover and import MCP servers and rules from other AI coding tools |
| AWS Auth | Automatic Bedrock credential refresh for AWS-hosted models |
| Ollama | First-class local LLM support via Ollama |
| Claude Code CLI | External provider extension for Claude Code CLI |
| cmux | Claude multiplexer integration — desktop notifications, sidebar metadata, visual subagent splits |
| GitHub Sync | Auto-sync milestones to GitHub Issues, PRs, and Milestones |
| LSP | Language Server Protocol — diagnostics, definitions, references, hover, rename |
| TTSR | Tool-triggered system rules — conditional context injection based on tool usage |
Five 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 |
| JavaScript Pro | JavaScript-specialized execution and debugging |
| TypeScript Pro | TypeScript-specialized execution and debugging |
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.
# ── 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, timeout recovery progress, and finalize 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 unit/finalize/iteration 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
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
.gsd/ folder.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).gsd/PREFERENCES.md file within the repo as per section Unique Milestone NamesI 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.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.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.npm update -g takes effect immediately. Bundled extensions and agents are synced to ~/.gsd/agent/ on every launch, not just first run..gsd/ markdown files are rendered projections for review, prompt context, and git history. KNOWLEDGE.md keeps rules file-canonical and projects patterns/lessons from memories at session start. No in-memory state survives across sessions.Optional:
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.
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.
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 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.
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.
| Project | Description |
|---|---|
| GSD2 Config Utility | Standalone configuration tool for managing GSD preferences, providers, and API keys |
The original GSD showed what was possible. This version delivers it.
npm install -g gsd-pi && gsd
FAQs
GSD — Get Shit Done coding agent
The npm package gsd-pi receives a total of 4,278 weekly downloads. As such, gsd-pi popularity was classified as popular.
We found that gsd-pi demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
pnpm 11.5 now recognizes npm staged publish approvals in release metadata, preventing those releases from being mistaken for lower-trust package publishes.
Security News
Federal audit finds NIST lacked a plan to clear the NVD backlog, wasted funds on duplicate work, and delayed use of CISA data.
Research
/Security News
A mini Shai-Hulud campaign compromised Red Hat Cloud Services npm packages to steal developer and CI/CD secrets during installation.