GSD Pi: a local-first coding agent that keeps project state in .gsd/

The problem GSD Pi targets: agent work that outlives one conversation

Long agent sessions fail in a predictable way. The model holds the plan in context, the context fills, and the thread of what was decided three hours ago gets summarized away. GSD Pi's answer is to stop treating the conversation as the source of truth. The README describes it as a local-first coding agent that plans, implements, verifies and tracks work from the command line, and the mechanism behind that claim is a project directory. Requirements, decisions, runtime notes, generated plans, summaries and validation evidence are written under .gsd/.

The intended user is an engineer who already works in a shell and wants an agent that can run for extended stretches without losing the thread. The README frames the goal as moving a project from idea to reviewed implementation with less manual coordination. That is a narrower audience than "anyone using AI to code". If your work is a single-file edit, the planning layer is overhead you will pay for and not use. The payoff appears when a task has milestones, slices and tasks, and when you need to come back tomorrow and know why a decision was made.

Milestones, slices, tasks: how the workflow and .gsd/ state fit together

The README describes a hierarchy: work is broken into milestones, slices and tasks. Auto mode then plans, implements, verifies and advances through that structure. This is the part worth understanding before you install, because it determines how much of your project layout the tool touches.

State lives in two places. Inside the project, .gsd/ holds planning and runtime state. Alongside it, sibling runtime directories such as .gsd-backups/ are gitignored. Those backups are migration snapshots: the README states that stale .gsd-backups/migrate-* snapshots are pruned after 30 days once the flat-phase .gsd/phases/ migration is complete. So the tool has a migration path for older project layouts, and it cleans up after itself on a timer rather than immediately.

Git handling is the second mechanism. GSD Pi is worktree-aware: implementation work happens in isolation while the main checkout stays reviewable. That is a real design decision with a real cost. Isolation means your normal working tree does not show the agent's edits as you work, so you review through Git rather than by watching files change. Model routing is the third piece. Providers can be API keys, OAuth providers, or external CLI providers such as Claude Code and Cursor Agent. For the cursor-agent provider, the README says the default model is composer-2.5 and that CURSOR_API_KEY is supported as an auth signal.

Surfaces differ too. The TUI is the default; gsd --web launches a browser control plane. Extensions add commands, tools, skills and UI integrations.

Installing GSD Pi and running a first session

The recommended install is the guided installer, run through npx. The README gives this as the primary path:

npx @opengsd/gsd-pi@latest

The installer walks through setup. For CI or scripted environments, the README shows the non-interactive form:

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

If you prefer a global install you own directly, the alternative is npm:

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

Note the package scope. GSD Pi installs from @opengsd/gsd-pi. An older unscoped gsd-pi package exists, and the README warns that its global binary can shadow the new one, so remove it first. The migration sequence the README gives is:

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

On Windows PowerShell the same cleanup uses Remove-Item on $env:USERPROFILE\.gsd\.update-check and $env:USERPROFILE\.gsd\agent\managed-resources.json before re-running the installer. The two verification commands matter: command -v gsd tells you which binary your shell will actually run, and gsd --version tells you which release it is. Run both after any migration.

Once installed, start a session from your shell:

gsd

Run the setup flow, pick a model provider, and open a project directory. Inside the session, slash commands drive the work. The README lists /gsd config and /gsd auto among the common session commands. Routine upgrades afterwards use gsd upgrade. If you would rather assemble settings in a browser first, the project points at a web configurator at pi.opengsd.net.

There is also a container path. The repository Dockerfile builds a runtime image on node:24-slim, installs git because GSD's git operations need it, sets WORKDIR /workspace, and sets the entrypoint to gsd with --help as the default command. The published image is ghcr.io/open-gsd/gsd-pi, and the package version is controlled by a GSD_VERSION build argument defaulting to latest. The same Dockerfile defines a runtime-local target that builds the current source rather than pulling from npm, used by tests/e2e/docker/ for PR-time smoke runs.

Where GSD Pi gets in the way

The engine constraint is Node. package.json declares engines.node as >=22.18.0. That is not a suggestion you can ignore on a shared build box running an older LTS line. The repository also declares pnpm@10.12.1 as its package manager, which matters if you intend to build from source rather than install the published package.

The second limitation is state proliferation. GSD Pi writes .gsd/ into your project and creates gitignored siblings. That is the whole point of the design, but it means the tool is not invisible. On a repository with strict review rules about untracked directories, or a monorepo where a stray .gsd/ at the wrong level confuses tooling, you will need to decide where the agent is allowed to run. The README does not describe a configuration option for relocating that directory.

The third is auto mode itself. Auto mode plans, implements, verifies and advances. The README does not document rollback for an auto-mode change. Worktree isolation limits the blast radius on your main checkout, but if you want a documented undo story before letting an agent advance through milestones unattended, the documentation does not provide one. Treat that as an open question to resolve in your own environment, not as a feature you can assume.

Finally, the repository is starting a new development baseline at version 1.0.0 under the open-gsd/gsd-pi project, and older release history has been archived outside the active changelog. The last push was on 2026-09-17 and the most recent release listed is v1.20.0 on 2026-09-13, so the project is moving. But if you need to trace a behavior back through years of changelog entries, the README points you at a separate legacy release history document rather than the active CHANGELOG.md.

GSD Pi against a plain coding agent

The obvious alternative is a general-purpose coding agent used directly: you open a session, describe the task, and let it edit files. The difference is not capability, it is where the plan lives. A plain agent keeps the plan in the conversation. GSD Pi externalizes it into .gsd/ as requirements, decisions, plans, summaries and validation evidence, and adds a milestone/slice/task structure on top so auto mode has something to advance through. If you abandon a session midway with a plain agent, you reconstruct the intent from scrollback. With GSD Pi the intent is a file.

That trade has a cost the plain approach does not. You adopt a workflow vocabulary. You accept a state directory in your project. You accept that implementation happens in an isolated worktree, so reviewing means using Git rather than watching the tree. For a two-line fix, a plain agent session is faster and leaves nothing behind.

The comparison inside the project's own naming is worth flagging because it shows up in search: people ask how gsd pi differs from gsd core, or search for gsd-pi vs gsd. The documentation describes GSD Pi as a local-first coding agent that installs from @opengsd/gsd-pi, and it describes an older unscoped gsd-pi package that must be uninstalled so it does not shadow the new binary. It does not describe a separate product called gsd core. If you are trying to choose between the two names, the documentation only supports the package-rename reading: same lineage, new scope, and a migration path.

Maintenance, upgrades and what the MIT licence leaves you

Upgrade cost is low by design. After the initial install, routine upgrades are one command: gsd upgrade. The README also notes you can re-run npx @opengsd/gsd-pi@latest to launch the guided installer, which is the recommended path for new installs. Deeper recovery steps live in two documents the README links: Upgrade GSD Pi in docs/user-docs/getting-started.md, and Upgrade from older gsd-pi installs in docs/user-docs/troubleshooting.md. The existence of a dedicated troubleshooting section for the old package tells you the rename caused enough friction to warrant one.

Uninstall is explicit. On macOS and Linux, npm uninstall -g @opengsd/gsd-pi gsd-pi followed by rm -rf ~/.gsd. If you installed with pnpm, the README says to use pnpm for the pnpm-owned package: pnpm remove -g @opengsd/gsd-pi, then npm uninstall -g gsd-pi, then rm -rf ~/.gsd. Note that the second command is unconditional even in the pnpm path, because the old unscoped package may have been installed by npm. On Windows the equivalent is npm uninstall -g @opengsd/gsd-pi gsd-pi plus Remove-Item on $env:USERPROFILE\.gsd.

The licence is MIT, declared in both the repository LICENSE file and the license field of package.json. MIT is permissive: you can use, modify and redistribute the code, including in closed-source products, provided the copyright notice and permission notice are preserved. I am not a lawyer and this is not legal advice. What matters practically is that MIT gives you no patent grant and no trademark rights, and it places the compliance burden on you to keep the notice intact if you vendor the code. The npm package is published with publishConfig.access public and provenance true, so the published artifact carries a provenance attestation linking it to its build.

What to check before you point GSD Pi at a real repository

Start with a throwaway project. Run the guided installer, complete setup, and open a directory you do not care about. Watch what appears under .gsd/ and confirm it matches what you expect a planning artifact to contain. Then inspect the gitignored siblings, because .gsd-backups/ will exist and the 30-day pruning rule for stale migrate-* snapshots only applies after the flat-phase .gsd/phases/ migration completes. If you are adopting on a project that already has .gsd/phases/, that migration is the first thing the tool will do to you.

Decide your provider before you start. The routing layer accepts API keys, OAuth providers, and external CLI providers including Claude Code and Cursor Agent. Cursor Agent requires installing and authenticating the local cursor-agent CLI first, and the README notes composer-2.5 as its default model with CURSOR_API_KEY as an auth signal. A provider that is not authenticated will fail at the first request, not at setup.

If you plan to run the container instead of the global install, remember that the image sets WORKDIR /workspace and the entrypoint is gsd, so you mount your project there. The image installs git because GSD's git operations require it, and the version is pinned through the GSD_VERSION build argument. Pin that argument to a specific release rather than leaving it at latest if you want reproducible runs.

Editorial conclusion

Adopt GSD Pi if you want an agent that plans, implements and verifies against files under .gsd/ rather than a single long chat, and if you are comfortable with a Node >=22.18.0 global CLI. Do not adopt it if you want a hosted service with no local state, or if you need documented rollback of an auto-mode change, because the README does not describe one. Before committing a real repository, verify three things yourself: that `command -v gsd` resolves to the scoped @opengsd/gsd-pi binary and not an old unscoped gsd-pi install, that `gsd --version` matches the release you intended, and that .gsd/ plus its gitignored sibling directories are what you want written into your working tree.

Frequently asked questions

Official sources

1. License: MIT
2. open-gsd/gsd-pi on GitHub
3. Project website
4. README
5. Releases