GSD Pi is a local-first coding agent for planning, implementing, verifying, and tracking project work from the command line.
It combines a terminal agent, project workflow tools, worktree-aware Git automation, and optional UI integrations so a project can move from idea to reviewed implementation with less manual coordination.
- Guided terminal agent — Start with
gsd, configure providers, and run planned or quick coding sessions from your shell. - Autonomous project workflow — Break work into milestones, slices, and tasks, then let auto mode plan, implement, verify, and advance.
- Worktree-aware Git automation — Keep implementation work isolated while preserving a reviewable main checkout.
- Local project memory — Store project requirements, decisions, runtime notes, generated plans, summaries, and validation evidence under
.gsd/. - Multi-provider model routing — Use the provider your team already has, including API keys, OAuth providers, and external CLI providers such as Claude Code and Cursor Agent.
- Extension surface — Add project-specific commands, tools, skills, and UI integrations through bundled or community extensions.
- Terminal and web surfaces — Use the TUI by default, or launch
gsd --webwhen a visual control plane fits the work better than a terminal.
See CHANGELOG.md for release-by-release fixes and Legacy Release History for archived history before the open-gsd/gsd-pi baseline.
Latest release: v1.10.0
- pi-ai: Add Meta Muse Spark 1.1 to the model catalog.
- gsd: Surface cacheRetention as a settable prompt-cache TTL preference.
- models: Add GPT-5.6 as a first-class model.
- models: Add Grok 4.5 as a first-class xAI model.
- agent-core: Pin compaction summarization reasoning to low, bound degenerate-chunk retry.
- gsd: Filter superseded context injections from provider payload.
- gsd: Stop advertising alias tool schemas on model-facing surfaces.
- gsd: Cap execute-task and discuss-slice inlined context; provider-aware budgets.
This repository is starting a new development baseline at version 1.0.0 under the open-gsd/gsd-pi project.
Older release history has been archived outside the active changelog so new work can be reviewed from a clean project surface.
Recommended — guided installer:
npx @opengsd/gsd-pi@latestFor CI or scripted installs:
npx @opengsd/gsd-pi@latest --yesAlternative — direct npm global install:
npm install -g @opengsd/gsd-pi@latestIf you want pnpm to own the global install, use pnpm's runner:
pnpm setup
exec $SHELL -l
pnpm dlx @opengsd/gsd-pi@latestSource: open-gsd/gsd-pi.
GSD Pi now installs from the scoped package @opengsd/gsd-pi. If you previously installed the older unscoped gsd-pi package, remove it first so the old global binary does not shadow the new package.
Recommended migration with the guided npx installer:
npm uninstall -g gsd-pi @opengsd/gsd-pi
rm -f ~/.gsd/.update-check ~/.gsd/agent/managed-resources.json
npx @opengsd/gsd-pi@latest
command -v gsd
gsd --versionIf the old package was installed with sudo npm install -g, use sudo npm uninstall -g gsd-pi for the old package removal.
To migrate from old npm globals to a pnpm-owned global install:
npm uninstall -g gsd-pi @opengsd/gsd-pi
rm -f ~/.gsd/.update-check ~/.gsd/agent/managed-resources.json
pnpm setup
exec $SHELL -l
pnpm dlx @opengsd/gsd-pi@latest
command -v gsd
gsd --versionWindows PowerShell with the guided npx installer:
npm uninstall -g gsd-pi @opengsd/gsd-pi
Remove-Item "$env:USERPROFILE\.gsd\.update-check" -Force -ErrorAction SilentlyContinue
Remove-Item "$env:USERPROFILE\.gsd\agent\managed-resources.json" -Force -ErrorAction SilentlyContinue
npx @opengsd/gsd-pi@latest
where.exe gsd
gsd --versionAfter migration, routine upgrades use:
gsd upgradeYou can also run npx @opengsd/gsd-pi@latest to launch the guided installer (recommended for new installs). For deeper recovery steps, see Upgrade GSD Pi and Upgrade from older gsd-pi installs.
Remove the global package and optional local GSD state files.
macOS / Linux:
npm uninstall -g @opengsd/gsd-pi gsd-pi
rm -rf ~/.gsdIf you installed GSD with pnpm, use pnpm for the pnpm-owned package. If pnpm reports that its global bin directory is not on PATH, run pnpm setup, restart your shell, then retry.
pnpm remove -g @opengsd/gsd-pi
npm uninstall -g gsd-pi
rm -rf ~/.gsdWindows PowerShell:
npm uninstall -g @opengsd/gsd-pi gsd-pi
Remove-Item "$env:USERPROFILE\.gsd" -Recurse -Force -ErrorAction SilentlyContinueNeed help choosing settings? Use the GSD Pi web configurator to build a configuration in your browser.
gsdRun the setup flow, choose your preferred model provider, and open a project directory. Cursor Agent users can choose the cursor-agent provider after installing and authenticating the local cursor-agent CLI; its default model is composer-2.5, and CURSOR_API_KEY is supported as an auth signal. GSD stores project planning and runtime state in .gsd/, with gitignored sibling runtime directories such as .gsd-backups/ for migration snapshots. Stale .gsd-backups/migrate-* snapshots are pruned after 30 days once the flat-phase .gsd/phases/ migration is complete.
For a full first-run walkthrough, see Getting Started With gsd-pi.
Start GSD from your shell:
gsdThen use slash commands inside the GSD session:
/gsd config
/gsd auto
/gsd quick "Describe the task"
/gsd status
- Plans work into milestones, slices, and tasks.
- Runs coding sessions with project context and verification steps.
- Uses Git worktrees to isolate implementation work.
- Tracks project state in a local database with markdown projections for review.
- Supports extension-based tools and provider integrations.
- Produces artifacts such as plans, summaries, validation notes, and reports.
| Path | Purpose |
|---|---|
src/ |
Core runtime resources and bundled extensions |
packages/ |
Workspace packages used by the CLI, agent, TUI, RPC, and native bridge |
native/ |
Native engine packaging and platform binaries |
studio/ |
Desktop studio app |
web/ |
Web UI and API surface |
docs/ |
User and developer documentation |
scripts/ |
Build, release, migration, and maintenance scripts |
pnpm install --frozen-lockfile
pnpm run build
pnpm testBefore opening a pull request, run:
pnpm run verify:fast # CI fast-gates locally (scans + policy)
pnpm run verify:pr # Fast loop: build + typecheck + unit tests
pnpm run verify:merge # Before PR review: full CI blocking parityThe active public baseline starts at 1.0.0.
Historical tags and archived refs may exist for traceability, but active release notes should be written from this baseline forward.
Join the GSD Discord community.
MIT