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.

Screenshots

GSD runs as a terminal-first TUI with optional browser dashboard controls.

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

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. GSD stores project planning and runtime state in .gsd/.

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