Skip to main content
GSD Core installs as a set of commands, agents, workflows, and hooks into the configuration directory of your AI coding runtime. The installer handles all runtime-specific adaptation automatically — you answer a few questions, and it writes the correct files to the correct paths.

​
Requirements

Before you begin, confirm your environment meets these prerequisites:
  • Node.js ≥ 22.0.0
  • npm ≥ 10.0.0
Check your versions with: 
node --version
npm --version
If you need to manage multiple Node.js versions, use nvm or fnm. GSD Core requires Node.js 22 for its native fetch support and ESM compatibility.

​
Run the installer

Run the installer with a single command: 
npx @opengsd/gsd-core@latest
The installer is interactive and will guide you through the setup. Do not copy files from agents/ or commands/ directly — the installer applies runtime-specific transformations that are required for each target environment.

​
Interactive installer walkthrough

1

Select your runtime

The installer prompts you to choose which AI coding runtime to target. Select the one you use — for example, Claude Code, Gemini CLI, Codex, or Cursor.If you use multiple runtimes, run the installer once per runtime, or pass --all to install for every supported runtime at once.
2

Choose installation scope

Choose between a global install (affects all projects on your machine) or a local install (affects only the current project directory).
  • Global is recommended for most users. Commands and agents are available in every project.
  • Local is useful when you need project-specific GSD configurations or want to keep GSD isolated to one repository.
3

Review what will be installed

The installer lists the files it will write — commands, agents, workflows, references, templates, and hooks — along with their destination paths. Review the list and confirm to proceed.
4

Hooks and permissions registered

For most runtimes, the installer registers GSD’s runtime hooks automatically:
  • Status line hook — displays model, task, directory, and context usage bar
  • Context monitor hook — injects agent-facing warnings when context runs low
  • Prompt guard hook — scans .planning/ writes for injection patterns
For Claude Code, the installer also pre-populates settings.json with the permissions GSD needs, eliminating first-run approval prompts.

​
Command prefixes by runtime

GSD Core ships the same commands to every runtime, but the invocation syntax differs. Use the correct prefix for your runtime:
Commands use the hyphen form:
/gsd-command-name
Examples:
/gsd-new-project
/gsd-plan-phase 1
/gsd-execute-phase 1

​
Runtime-specific install flags

If you prefer to skip the interactive prompts, pass runtime and scope flags directly: 
# Claude Code, global
npx @opengsd/gsd-core@latest --claude --global

# Gemini CLI, global
npx @opengsd/gsd-core@latest --gemini --global

# Codex, local
npx @opengsd/gsd-core@latest --codex --local

# Cursor, global
npx @opengsd/gsd-core@latest --cursor --global

# Cline, global
npx @opengsd/gsd-core@latest --cline --global

# All supported runtimes, global
npx @opengsd/gsd-core@latest --all --global

​
Verify the installation

After the installer completes, open your runtime and run: 
/gsd-new-project
If the command is recognized and begins asking you questions about your project, the installation succeeded.
For Gemini CLI users, run /gsd:new-project instead.

​
Start your first project

Once GSD Core is installed, run /gsd-new-project to begin. The command walks you through an interactive session to define your project, runs parallel research agents to understand your domain, generates a REQUIREMENTS.md and ROADMAP.md, and leaves you ready to start the phase loop. See the Quickstart guide for a complete walkthrough of your first project from install to shipped phase.

​
Updating GSD Core

To update to the latest stable release, run the same install command again — the installer is idempotent and backs up any locally modified files to gsd-local-patches/ before overwriting: 
npx @opengsd/gsd-core@latest
To install the release candidate channel instead, use your runtime’s update command: 
/gsd-update --next