GSD Pi

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.

Feature Roll-Up

• 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 --web when 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 Highlights

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.

Status

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.

Install

Recommended — guided installer:

npx @opengsd/gsd-pi@latest

For CI or scripted installs:

npx @opengsd/gsd-pi@latest --yes

Alternative — direct npm global install:

npm install -g @opengsd/gsd-pi@latest

If you want pnpm to own the global install, use pnpm's runner:

pnpm setup
exec $SHELL -l
pnpm dlx @opengsd/gsd-pi@latest

Source: open-gsd/gsd-pi.

Migrate From Older Installs

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 --version

If 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 --version

Windows 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 --version

After migration, routine upgrades use:

gsd upgrade

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

Uninstall

Remove the global package and optional local GSD state files.

macOS / Linux:

npm uninstall -g @opengsd/gsd-pi gsd-pi
rm -rf ~/.gsd

If 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 ~/.gsd

Windows PowerShell:

npm uninstall -g @opengsd/gsd-pi gsd-pi
Remove-Item "$env:USERPROFILE\.gsd" -Recurse -Force -ErrorAction SilentlyContinue

Quick Start

Need help choosing settings? Use the GSD Pi web configurator to build a configuration in your browser.

gsd

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

Common Session Commands

Start GSD from your shell:

gsd

Then use slash commands inside the GSD session:

/gsd config
/gsd auto
/gsd quick "Describe the task"
/gsd status

What GSD Pi Does

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

Repository Layout

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

Development

pnpm install --frozen-lockfile
pnpm run build
pnpm test

Before 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 parity

Versioning

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

Community

Join the GSD Discord community.

Star History

License

MIT