What GSD Pi Does
GSD Pi is a local-first coding agent operated from the terminal. It coordinates an entire project lifecycle—planning, implementation, verification, and tracking—from a single command-line interface, reducing the friction of switching between separate tools.
The agent can:
- Plan work into milestones, slices, and tasks.
- Run coding sessions with project context and built-in verification.
- Use Git worktrees to isolate experimental changes.
- Track state in a local database and produce markdown overviews.
- Support extension-based tools and provider integrations.
- Generate artefacts like plans, summaries, and validation notes.
All plans, conversations, and runtime state live inside a .gsd/ directory, staying fully on your machine.
Getting Started
Install the package globally from npm:
npm install -g @opengsd/gsd-pi@latest
The binary gsd becomes available.
If you previously used the older unscoped gsd-pi, follow the migration steps below first.
On first run with gsd, an interactive setup flow lets you choose a model provider, open a project directory, and initialise configuration.
Alternatively, use the web configurator at https://pi.opengsd.net/ to build a configuration in your browser before ever launching the CLI.
All state is stored in .gsd/ at your project root.
A detailed walkthrough exists in the repository’s docs/user-docs/getting-started.md.
Practical Usage
Start GSD inside any project:
gsd
Control the agent with slash commands. Common examples:
/gsd config # review or change configuration /gsd auto # let the agent work autonomously on the current plan /gsd quick "Describe the task" /gsd status # show project and session status
A typical workflow:
1.
Open your project with gsd.
2.
Plan the work into milestones and slices.
3.
Begin coding sessions where the agent creates a Git worktree, implements changes, runs verification, and produces a summary.
4.
Review artefacts and project state tracked in .gsd/.
The agent understands your file structure, coordinating multi-step implementation with minimal oversight.
Configuration and Options
- Setup flow – on first launch,
gsdinteractively guides you through provider selection and project initialisation. - Web configurator – build your configuration at
https://pi.opengsd.net/before ever running the CLI. - In‑session config – use
/gsd configto adjust settings after initial setup. - State storage – all planning data, agent sessions, and artefacts live in the
.gsd/directory inside your project root.
No environment variables or external configuration files are documented in the README.
Known Constraints
The README does not list unsupported use cases, edge cases, or known bugs. The project is at version 1.0.0 under a new development baseline. Older release history has been archived, so information about pre‑1.0 limitations is not part of the current documentation.
Migration from Older Installs
GSD Pi is now published as @opengsd/gsd-pi.
If you previously installed the unscoped gsd-pi package, you must remove it and clean up residual files before upgrading.
This prevents the old binary from shadowing the new one.
After migration you can use the built-in gsd upgrade command for future updates.
Alternatively, launch the installer directly:
npx @opengsd/gsd-pi@latest
If problems occur, consult docs/user-docs/troubleshooting.md#upgrade-from-older-gsd-pi-installs.
npm uninstall -g gsd-pi rm -f ~/.gsd/.update-check ~/.gsd/agent/managed-resources.json npm install -g @opengsd/gsd-pi@latest which gsd gsd --version
npm uninstall -g gsd-pi Remove-Item "$env:USERPROFILE\.gsd\.update-check" -Force -ErrorAction SilentlyContinue Remove-Item "$env:USERPROFILE\.gsd\agent\managed-resources.json" -Force -ErrorAction SilentlyContinue npm install -g @opengsd/gsd-pi@latest where.exe gsd gsd --version
