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@latest

GSD 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 forces RTK_TELEMETRY_DISABLED=1 for all managed invocations. Set GSD_RTK_DISABLED=1 to 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.

What's New in v2.82

State Reconciliation & Drift Detection (ADR-017)

• Unified drift-detection framework — a new state-reconciliation layer replaces ad-hoc recovery checks. Each drift kind (stale worker, unregistered milestone, roadmap divergence, missing completion timestamp, merge-state, stale render) is owned by a focused detector + idempotent repair handler registered in a single registry, with a cap=2 retry contract that ensures repair-then-retry settles cleanly.
• Stale session locks no longer block resume — when a /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.
• Unregistered milestones get imported automatically — if you scaffold a milestone directory (with 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 and DB stay in sync — divergence between 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.
• Missing completion timestamps backfill from disk — entities marked complete in the DB but with a null 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).
• Parallel spawns reconcile before fanning out — /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.

Worktree Lifecycle Refactor (ADR-016 — final phases)

• Phase 2 complete — the worktree-manager module finished absorbing fs primitives, git-CLI primitives, worktree-manager helpers, cache/preferences/paths, and the final 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.
• Phase 3 closes strict-closure residuals — dead defensive 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.

Auto-Mode Reliability

• 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 retries back off properly — a new 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.
• Auto-loop exit paths are journaled end-to-end — post-unit finalize stops, all unit-end iteration exits, and the run-unit failsafe now journal cleanly. Auto-timeout recovery journaling completes its handoff record. The run-unit failsafe also defers when a recovery is already in flight to avoid double-firing.
• Ghost completions and stale telemetry are guarded — auto-mode no longer stops on ghost completions before a milestone stop has actually fired, and unmerged-exit telemetry is gated on active worktrees so closed sessions don't generate noise.
• Session-switch hygiene — completed-content aborts that fire while the session is switching are ignored instead of being misclassified as user aborts. Auto-commit skips .gitignored task key files so the working tree stays clean across slices.

TUI & Operator Experience

• Operations console redesign — the auto-mode dashboard, notification overlay, parallel-monitor overlay, health widget, header renderer, and welcome screen were all rebuilt against a new shared 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.
• Milestone completion rollup — at the boundary between milestones, auto-mode now renders a 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.

v2.81 highlights

• Worktree safety is fail-closed — write/edit operations enforce the worktree-isolation contract; lifecycle and projection split into dedicated modules; milestone merge closeout is harder to wedge.
• Memory, context, and token control — artifact integrity fingerprints, time-decay memory ranking, safer FTS5 fallback, request-time tool scoping, leaner workflow prompts, and more accurate session/context token accounting.
• TUI polish — compact tool output with targets, refreshed chat/tool cards, adaptive refresher layouts, stable welcome/header lifecycle, and bottom-anchored auto-mode rendering.
• Reliability, tests, and CI — auto-mode recovery and session handoff hardened, broad E2E coverage expansion (real-process MCP, fake LLM, native ABI, Docker, Windows), and a faster, less-noisy CI gate setup.

v2.80 highlights

• DB-authoritative context — UOK contracts moved through database-backed runtime state, auto-run context mode was wired end-to-end, and planned slices recover after artifact writes.
• Auto, deep mode, and gates — deep queued milestones continue, deep project milestones register cleanly, depth-verification regressions were closed, and task commits respect the milestone completion guard.
• MCP, post-exec, and cross-platform hardening — post-exec import fallback handling, React Router +types imports, gsd_exec write gating, project-save behavior, and home-directory fallback behavior were tightened.
• Reliability and review hardening — auto orchestration contracts, cancellation context preservation, recovery stop lifecycle events, trace correlation, cleanup-on-throw, and phase-result guards were improved.

v2.79 highlights

• DB-backed runtime coordination — workers, leases, dispatches, command queue, locks, paused-session state, and stuck-state recovery moved into gsd.db
• Workspace/worktree isolation — GsdWorkspace and MilestoneScope handles, symlink-safe canonicalization, worktree-scoped DB/metrics, cwd anchoring, and gsd worktree {list, merge, clean, remove}
• Deep planning mode — /gsd new-project --deep, research dispatch units, EVAL-REVIEW, project-shape-aware questioning, and approval-gate hardening
• Auto pipeline upgrades — delegation-policy verdicts, reactive-execute default, proactive rate limiting, manifest-driven skill surfacing, and subagent telemetry
• MCP/model/cross-platform fixes — global MCP config, ask_user_questions over MCP, provider-agnostic model routing, Ollama timeouts, Windows fixes, and Anthropic prompt-cache preservation
• Git and recovery reliability — self-merge guards, safer slice cadence, milestone-ID reservation, auto-commit hygiene, retryable GitHub sync, atomic metrics writes, and stronger teardown handling
• VS Code and TUI polish — checkpoint tree view, image paste preservation, and bundled /gsd slash command protection

v2.78 highlights

• Slice-cadence worktree collapse (#4765) — git.collapse_cadence: "milestone" | "slice" shrinks the orphan window per-slice; pair with git.milestone_resquash: true to collapse to one milestone commit
• Worktree telemetry (#4764) — journal events + summarizeWorktreeTelemetry; /gsd forensics worktree section with worktree-orphan and worktree-unmerged-exit anomalies
• Worktree-aware canonical milestone root (#4761) — resolveCanonicalMilestoneRoot routes validators through the live worktree
• Bootstrap orphan audit (#4762) — in-progress milestones with commits ahead of main are no longer skipped
• Unified component system — skills, agents, pipelines, and marketplace as one component model wired through runtime, dispatch, and telemetry
• UnitContextManifest v2 (#4924, #4934) — typed manifest with declarative tools-policy and typed computed artifacts; CI-guarded
• Composer migration phase 3 (#4782) — complete-slice, research-milestone, run-uat, reassess-roadmap build context through the manifest composer
• Milestone scope classifier + pipeline variants (#4781) — auto picks a pipeline variant from milestone shape
• Per-unit-type skill manifest resolver (#4779) — skills wire into specific unit types instead of being globally on
• Single-writer-v3 control plane — durable-state writer gaps closed
• Extensions framework — gsd extensions install / update / uninstall / list / info / validate; topological load order; cmux↔gsd decoupling via cmux-events; extracted @gsd-extensions/google-search
• GPT-5.5 Codex support + xhigh thinking level; auth mode in /model; permission granularity picker; headless auto default → bypassPermissions (#4657)
• Major git-safety pass — TOCTOU ancestry guard, atomic sync-lock with PID-verified stale override, .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
• Atomic .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 canonicalized

v2.77 highlights

• Context Mode — dispatch builds task-ready context automatically (artifacts, prior session, milestone/slice signals, execution metadata); enabled by default for new projects
• Sandboxed execution tools — `gsd_exec_sea