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, with configurable defaults and per-phase model preferences.
- 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.
- Claude Opus 4.8 support — Add the latest Claude model option to the generated model catalog.
- Better
/gsdobservability — Add/gsd usageand/gsd contextcommands for inspecting session usage and context state. - Sharper skill scoping — Scope the skill catalog per unit, trim duplicate prompt surfaces, and apply unit-context manifest policy during auto-mode dispatch.
- Improved guided installs — Redesign the
npx @opengsd/gsd-pi@latestflow so first-time and scripted installs are clearer and more reliable. - Smoother auto-mode progress — Improve requirements backlog handling, completion summaries, quick branch inference, cleanup logic, and milestone closeout behavior.
- Cloud MCP gateway runtime — Add the local cloud MCP gateway runtime with persisted auth state.
- More reliable installs — Resolve native engine packages to the matching release version across npm installs and Docker images.
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. GSD stores project planning and runtime state in .gsd/.
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