Installation Guide: Out With the Old, in With the New

[DivineStudio]

Open-GSD Developer Installation

This guide is for developers moving from the original GSD packages to the Open-GSD packages. The normal flow is simple: remove the old package with npm, manually clean up any old runtime artifacts, run the Open-GSD installer, then restart the target runtime.

Prerequisites: Node.js >=22, npm >=10, and whichever runtime you want GSD to install into.

What To Replace

Original package	Open-GSD replacement	Use
get-shit-done-cc	@opengsd/gsd-core	GSD v1 / GSD Core runtime installer
gsd-pi	@opengsd/gsd-pi	GSD Pi
@gsd-build/sdk	@opengsd/gsd-sdk	Standalone SDK, only if you explicitly installed it

Most users only need the first two rows. Do not install from the original package names for new setup work.

Install Open-GSD Core

Use this when you want GSD v1 / Core commands, skills, hooks, or agent files installed into a runtime such as Claude Code, Codex, Copilot, Gemini CLI, OpenCode, Cursor, or Windsurf.

Step 1 - Remove the old npm package with npm.
Do not run npx get-shit-done-cc --uninstall when migrating from the original package. npx executes code from the old package, which is unnecessary risk if you do not trust that package's current or future published scripts. Use npm uninstall because it removes the registered package and binary shims without intentionally launching the old GSD CLI.

npm uninstall -g get-shit-done-cc

Step 2 - Manually remove old runtime artifacts.
Skipping the old npx --uninstall command leaves the runtime files that package previously copied into AI tool config directories. Remove only GSD-owned paths and entries, and preserve user-authored files such as dev-preferences.md or USER-PROFILE.md if you have them.

Global and project-local installs usually used these runtime config directories:

Runtime	Global config directory	Project-local directory
Claude Code	~/.claude/	.claude/
Cursor	~/.cursor/	.cursor/
Gemini CLI	~/.gemini/	.gemini/
Codex	~/.codex/	.codex/
GitHub Copilot	~/.copilot/	.github/
Antigravity	~/.gemini/antigravity/	.agent/
Windsurf	~/.codeium/windsurf/	.windsurf/
Augment	~/.augment/	.augment/
Trae	~/.trae/	.trae/
Qwen Code	~/.qwen/	.qwen/
Hermes	~/.hermes/	.hermes/
CodeBuddy	~/.codebuddy/	.codebuddy/
Cline	~/.cline/	.cline/
OpenCode	~/.config/opencode/	.opencode/
Kilo Code	~/.config/kilo/	.kilo/

Remove these GSD-owned files and directories from each runtime directory that previously had GSD installed:

.gsd-profile
gsd-file-manifest.json
get-shit-done/
commands/gsd/
commands/gsd-*
skills/gsd-*
skills/gsd/
agents/gsd-*.md
agents/gsd-*.toml
hooks/gsd-statusline.js
hooks/gsd-check-update.js
hooks/gsd-check-update.cmd
hooks/gsd-context-monitor.js
hooks/gsd-prompt-guard.js
hooks/gsd-read-guard.js
hooks/gsd-read-injection-scanner.js
hooks/gsd-update-banner.js
hooks/gsd-workflow-guard.js
hooks/gsd-session-state.sh
hooks/gsd-validate-commit.sh
hooks/gsd-phase-boundary.sh
hooks/gsd-graphify-update.sh
hooks/lib/git-cmd.js
hooks/lib/gsd-graphify-rebuild.sh

Also inspect and remove GSD-managed references from these runtime config files when present:

Runtime	Config cleanup
Claude Code and compatible runtimes	Remove statusLine or hooks entries that call gsd-* hook scripts from settings.json.
Codex	Remove GSD sections from config.toml and GSD SessionStart entries from hooks.json.
GitHub Copilot	Remove the GSD block from copilot-instructions.md, or delete the file if it only contains GSD content.
OpenCode and Kilo Code	Remove permission.read or permission.external_directory entries that reference get-shit-done from opencode.json, opencode.jsonc, kilo.json, or kilo.jsonc.

If a runtime directory contains a package.json whose entire contents are exactly {"type":"commonjs"}, you can remove it. Leave any real package file with other fields in place.

Step 3 - Install the Open-GSD Core package.
With the old package removed and old runtime artifacts cleaned up, run the Open-GSD Core installer:

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

The installer prompts for the target runtime and whether the install should be global or project-local. After it finishes, restart the target runtime so it discovers the new files.

Install Open-GSD Pi

Use this when you want GSD Pi from Open-GSD.

First remove the original Pi package:

npm uninstall -g gsd-pi

If this machine previously used the unscoped gsd-pi package, you can also remove stale Pi metadata before installing the Open-GSD package. These files are not project content.

macOS / Linux:

rm -f ~/.gsd/.update-check ~/.gsd/agent/managed-resources.json

Windows PowerShell:

Remove-Item "$env:USERPROFILE\.gsd\.update-check" -Force -ErrorAction SilentlyContinue
Remove-Item "$env:USERPROFILE\.gsd\agent\managed-resources.json" -Force -ErrorAction SilentlyContinue

Then install Open-GSD Pi globally:

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

You can also launch the Pi installer with npx instead of installing the installer package globally:

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

The Pi installer still defaults to installing Pi globally. For a project-local Pi install, run it from the project root with --local:

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

After installation, routine upgrades use:

gsd upgrade

Project-Local Installs

Use project-local installs when the current repository should own its own GSD runtime files or Pi dependency.

From the project root, remove old local packages if they are present:

npm uninstall get-shit-done-cc gsd-pi @gsd-build/sdk

Then run the Open-GSD installer you need:

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

You do not have to run both commands. Use Core for GSD runtime installation, Pi for GSD Pi installation, or both when a project needs both.

Verify

Verify the behavior you installed, not just npm package metadata.

Core Runtime Install

After installing Open-GSD Core , restart the target runtime so it reloads its config directory. Then confirm the runtime can see the GSD surface you installed: commands, skills, hooks, or agent files, depending on the runtime and profile you selected.

A passing Core check means the target runtime discovers the Open-GSD files after restart and the GSD commands or skills are available from that runtime. A failed Core check means the runtime cannot see the installed files, still points at old GSD content, or reports config/hook errors during startup.

For file-level inspection, check the runtime directory you installed into and confirm it contains the expected GSD-owned files from the artifact list above.

Pi CLI Install

If Pi was installed globally, verify the installed CLI:

gsd --version
gsd --help

For a project-local Pi install, run the same checks from the project root through npm:

npm exec --call "gsd --version"
npm exec --call "gsd --help"

This passes when the commands print the Open-GSD Pi version/help and exit successfully. It fails if gsd is not on PATH, npm cannot find the local binary, the command still points to an older package, or the CLI crashes before printing output.

Optional Package Diagnostics

Use these only when you need to inspect npm package state. They are not the main verification path.

npm ls -g --depth=0 get-shit-done-cc
npm ls -g --depth=0 gsd-pi
npm ls -g --depth=0 @opengsd/gsd-core
npm ls -g --depth=0 @opengsd/gsd-pi

For project-local installs, run the same checks from the project root without -g. npm ls may exit non-zero or print a missing-package message for the original package names. That is expected after uninstalling them; the important result is that old package names do not appear in the package list you inspected.

If you need to check whether npm can fetch the Open-GSD installer packages, run their help commands:

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

These commands pass when installer help prints and the command exits successfully. They prove the packages are reachable and executable; they do not prove Core runtime files or the global Pi CLI are installed.

Advanced Reference

Package And Binary Matrix

Package	Primary binary names	Notes
@opengsd/gsd-core	gsd-core, gsd-sdk, gsd-tools	Main Open-GSD Core installer package.
@opengsd/gsd-pi	gsd, gsd-pi, gsd-cli	Open-GSD Pi package.
@opengsd/gsd-sdk	gsd-sdk	Optional standalone SDK package.

gsd-core is an npm package binary, not an environment variable. Most install docs should use npx --yes @opengsd/gsd-core@latest instead of relying on a globally installed binary.

GSD Core Environment Matrix

Use one of these runtime flags when you want to install GSD Core non-interactively for a specific environment.

Environment	Runtime flag
Claude Code	--claude
Antigravity	--antigravity
Augment	--augment
Cline	--cline
CodeBuddy	--codebuddy
Codex	--codex
GitHub Copilot	--copilot
Cursor	--cursor
Gemini CLI	--gemini
Hermes	--hermes
Kilo Code	--kilo
OpenCode	--opencode
Qwen Code	--qwen
Trae	--trae
Windsurf	--windsurf

Non-Interactive Core Installs

Use these forms in scripts or onboarding docs when you do not want the Core installer to prompt.

npx --yes @opengsd/gsd-core@latest --claude --global
npx --yes @opengsd/gsd-core@latest --codex --global
npx --yes @opengsd/gsd-core@latest --copilot --global
npx --yes @opengsd/gsd-core@latest --claude --local

Use --all --global only when the machine should receive every supported runtime surface:

npx --yes @opengsd/gsd-core@latest --all --global

Non-Interactive Pi Installs

npm install -g @opengsd/gsd-pi@latest
npx --yes @opengsd/gsd-pi@latest
npx --yes @opengsd/gsd-pi@latest --local

Useful Pi installer options:

Option	Use
--local	Install Pi into the current project instead of globally.
--skip-chromium	Skip Chromium download during install.
PLAYWRIGHT_SKIP_BROWSER_DOWNLOAD=1	Environment-variable form for skipping browser downloads.
--skip-rtk	Skip RTK installation.
GSD_SKIP_RTK_INSTALL=1	Environment-variable form for skipping RTK installation.
GSD_RTK_DISABLED=1	Disable RTK usage at runtime.

[trek-e]

https://github.com/open-gsd/gsd-core/blob/next/docs/cleanup-get-shit-done-cc.md

1.3.0 is in rc1 status (@next install vs @latest ) and has a new feature to help clean up the /gsd-update flag that was broken.

[briansumma]

Slightly confused. Is this still the same project that the community took over when TÂCHES went AWOL? opengsd/get-shit-done-redux?

[trek-e]

yes, the redux name was a 'knee jerk reaction' in an attempt to save the code as everything else taches had access too was disappearing, once we were able to figure things out and look around there was a finale rename. gsd-core is what get-shit-done-cc was and gsd-pi kept its name as the two were often confused on 'should I upgrade' when they weren't an upgrade but named gsd 1 / gsd 2.