msd-core/docs/how-to/install-on-your-runtime.md

How to install GSD Core on your runtime

Install GSD Core (@opengsd/gsd-core) into the AI coding runtime you use every day. This guide gives you the standard installer path for each supported runtime, then covers the manual path for machines without Node.js.

What you need: Node.js 18+ and npm (or npx). If you do not have Node.js, jump to Installing without Node.js.

---

Why the installer is required

GSD Core ships agent and command files in Claude Code's native frontmatter format. Each supported runtime expects a different schema, directory layout, and command-invocation syntax. The installer performs the necessary transformations — for example, converting tool lists and colour values for OpenCode, writing TOML agent entries for Codex, and rewriting every command body from hyphen form (/gsd-update) to colon form (/gsd:update) for Gemini CLI.

Do not copy files from agents/ or commands/ directly. Doing so bypasses the transformations and produces schema-validation errors or missing commands.

---

Standard install

Run the installer from any directory. It prompts for your runtime and whether to install globally (all projects) or locally (this project only).

npx @opengsd/gsd-core@latest

That is the only command you need for a fresh install or to re-run the installer after switching runtimes.

---

Per-runtime instructions

Claude Code

npx @opengsd/gsd-core@latest --claude --global

Skills land in ~/.claude/. Commands appear as /gsd-* slash commands in your next Claude Code session. Restart Claude Code to pick them up.

Override the install directory:

CLAUDE_CONFIG_DIR=~/.claude-alt npx @opengsd/gsd-core@latest --claude --global

Hook coverage

GSD registers the following Claude Code hook events automatically on install:

Event	Hook	Purpose
SessionStart	gsd-check-update.js, gsd-session-state.sh	Update check, session orientation
PostToolUse	gsd-context-monitor.js, gsd-read-injection-scanner.js, gsd-phase-boundary.sh, gsd-graphify-update.sh	Context monitoring, read-time scan, phase boundary detection
PreToolUse	gsd-prompt-guard.js, gsd-read-guard.js, gsd-workflow-guard.js, gsd-worktree-path-guard.js, gsd-validate-commit.sh	Prompt guard, read-before-edit, workflow + worktree safety, commit validation
SubagentStop	gsd-context-monitor.js	Context headroom tracking after subagent completion
Stop	gsd-context-monitor.js	Context headroom tracking before model stop
PreCompact	gsd-context-monitor.js	Context awareness before conversation compaction
FileChanged (matcher: config.json)	gsd-config-reload.js	Hot-reloads .planning/config.json context mid-session when you edit your GSD config — no session restart required

The FileChanged hook is always-on and a no-op when .planning/config.json does not exist in the project. Editing that file while a session is running injects an additionalContext summary of the new configuration so the agent picks up model overrides, workflow toggles, and hook settings immediately.

---

Claude Code — native plugin install

GSD Core ships a .claude-plugin/plugin.json manifest, which enables installation and lifecycle management through the Claude Code plugin system. This path is additive — the npm installer above remains fully supported, and the two approaches differ in namespace and lifecycle only.

Install paths

Option A — marketplace or git install (once listed):

claude plugin install gsd-core

Option B — zero-friction skills-dir load: Claude Code automatically discovers any directory under ~/.claude/skills/ that contains a .claude-plugin/plugin.json as a plugin. To use gsd-core this way, place (or symlink) the gsd-core package directory there:

# Example: place the package under ~/.claude/skills/gsd-core/
# Claude Code loads it as gsd-core@skills-dir on the next session start.
# No explicit install step required.

Command namespace

Plugin commands are namespaced as /gsd-core:<command> — for example, /gsd-core:plan-phase. This is distinct from the classic npm/file-copy installer, which exposes commands as /gsd:<command>. Use whichever namespace corresponds to your install method.

Lifecycle

claude plugin enable gsd-core
claude plugin disable gsd-core
claude plugin update gsd-core

Hooks

The plugin wires gsd-core's always-on guard and update hooks automatically via hooks/hooks.json. No manual hook registration is required.

Prerequisites

The gsd-tools binary (installed as part of the @opengsd/gsd-core npm package) must be available on your PATH for gsd commands to execute their backing logic. The plugin delivers the command, agent, and hook surface; the npm package delivers the runtime CLI.

Node.js (node) must also be available on your PATH. The plugin's always-on guard hooks (wired in hooks/hooks.json) are invoked as node "${CLAUDE_PLUGIN_ROOT}/hooks/<script>". Some Claude Code distributions ship as a standalone binary and do not expose a node executable on PATH; in those environments the plugin's hooks will not run. Verify with node --version before relying on the plugin hooks.

---

Gemini CLI

npx @opengsd/gsd-core@latest --gemini --global

Skills land in ~/.gemini/. The installer rewrites all command bodies to Gemini's colon namespace (/gsd:update, /gsd:config, etc.). Restart Gemini CLI after install.

The installer also enriches the generated TOML commands with two native Gemini custom-command features:

• {{args}} interpolation — every command that references arguments inline is emitted with Gemini's {{args}} placeholder (translated from Claude's $ARGUMENTS), so flags and free-text you type after the command name are interpolated into the prompt body rather than ignored.
• !{...} live-state injection — /gsd:progress injects the current contents of .planning/STATE.md via a fixed !{cat .planning/STATE.md 2>/dev/null} shell block, giving Gemini live project state without relying on session memory. The shell block contains no interpolated input, so there is no injection risk; Gemini still shows its standard confirmation dialog the first time the command runs in a session.

Override the install directory:

GEMINI_CONFIG_DIR=~/.gemini-alt npx @opengsd/gsd-core@latest --gemini --global

Hook coverage

GSD registers the following hook events automatically on install:

Event	Hook	Purpose
SessionStart	gsd-check-update.js, gsd-session-state.sh	Update check, session orientation
BeforeTool	gsd-prompt-guard.js, gsd-read-guard.js, gsd-workflow-guard.js, gsd-worktree-path-guard.js, gsd-validate-commit.sh	Prompt guard, read-before-edit, workflow + worktree safety, commit validation
AfterTool	gsd-context-monitor.js, gsd-read-injection-scanner.js, gsd-phase-boundary.sh, gsd-graphify-update.sh	Context monitoring, read-time scan, phase boundary detection
BeforeAgent	gsd-context-monitor.js	Context headroom awareness before the agent begins planning each prompt
AfterAgent	gsd-context-monitor.js	Context headroom tracking after each agent turn's final response
BeforeModel	gsd-context-monitor.js	Per-turn context injection before each LLM call

hooksConfig.enabled: false warning. If your Gemini settings.json contains hooksConfig.enabled: false, the Gemini CLI silently disables all hook execution — GSD hooks are registered but will never run. The installer detects this and emits a warning. To enable hooks, set hooksConfig.enabled: true in ~/.gemini/settings.json (or the directory matching your GEMINI_CONFIG_DIR).

---

Gemini CLI — native extension install (#775)

GSD also ships a gemini-extension.json extension manifest, so you can manage GSD through Gemini's own extension lifecycle and see it in gemini extensions list:

gemini extensions install https://github.com/open-gsd/gsd-core   # install
gemini extensions update gsd-core                                # update
gemini extensions uninstall gsd-core                             # remove
gemini extensions link /path/to/gsd-core                         # dev: symlink a checkout

The extension loads GSD's operating context (GEMINI.md) into every session and gives you the discoverable install/update/remove lifecycle. The /gsd:* slash commands, agents, and hooks are installed separately by npx @opengsd/gsd-core --gemini --global (above). The two paths are complementary and additive — neither replaces the other, and slash-command projection into the extension is a planned follow-up.

---

OpenCode

npx @opengsd/gsd-core@latest --opencode --global

The installer writes three surfaces under ~/.config/opencode/ (XDG) or ~/.opencode/: flat slash commands in command/, file-based subagents in agents/, and on-demand skills in skills/<name>/SKILL.md. It converts agent frontmatter to OpenCode's schema — removing the tools: field and converting colour values to hex — and emits each skill with spec-compliant frontmatter (name matching the skill directory plus a description). Skills are loaded on demand via OpenCode's native skill tool; commands remain invokable as /gsd-*. See Installing without Node.js — OpenCode transformations if you need to understand what changes.

Override the install directory:

OPENCODE_CONFIG_DIR=~/.config/opencode-alt npx @opengsd/gsd-core@latest --opencode --global

---

Kilo

npx @opengsd/gsd-core@latest --kilo --global

The installer writes the same three surfaces under ~/.config/kilo/ (XDG) or ~/.kilo/ as for OpenCode — flat commands in command/, subagents in agents/, and skills in skills/<name>/SKILL.md — since Kilo derives from OpenCode and shares its config schema and skill layout.

Override the install directory:

KILO_CONFIG_DIR=~/.config/kilo-alt npx @opengsd/gsd-core@latest --kilo --global

---

Codex

npx @opengsd/gsd-core@latest --codex --global

Skills land in ~/.codex/skills/gsd-*/SKILL.md. Agents are written with per-agent TOML entries in config.toml. Restart Codex (or run codex --reload) after install.

Minimum supported version: Codex CLI 0.130.0. Earlier versions had additional skill-root scanning that can produce duplicate listings.

Hook coverage

GSD registers the following Codex hook events automatically on install (requires Codex CLI 0.137.0+ for the stable hook-event schema):

Event	Hook	Purpose
SessionStart	gsd-check-update.js	Update check at session open; Windows installs also emit a commandWindows field pointing to the .cmd shim so Codex picks the correct executor on Windows without requiring per-OS config regeneration
SubagentStart	gsd-context-monitor.js	Inject context / GSD_AGENT_NAME awareness at subagent open
Stop	gsd-context-monitor.js	Context headroom tracking before model stop
PostToolUse	gsd-context-monitor.js	Mirror the context-monitor coverage available in Claude Code

All registered hooks are managed by GSD and are removed cleanly on --uninstall.

---

Kimi CLI

Support boundary — legacy kimi-cli vs Kimi Code. This integration targets the legacy/Python kimi-cli custom-agent contract. The kimi --agent-file <configRoot>/agents/gsd.yaml launch shown below is accepted by kimi-cli. The newer npm Kimi Code (@moonshot-ai/kimi-code, e.g. 0.11.0) does not accept --agent-file; it discovers skills through fixed skill roots and --skills-dir. The generated /skill:gsd-* skills work in both, but the custom-agent (--agent-file) surface is specific to legacy kimi-cli. For Kimi Code, point it at the installed skills root with --skills-dir <configRoot>/skills instead of using --agent-file.

npx @opengsd/gsd-core@latest --kimi --global

Skills land in Kimi's first existing generic user skills root:

• ~/.config/agents/skills/gsd-*/SKILL.md when ~/.config/agents/skills already exists, or when neither generic root exists yet
• ~/.agents/skills/gsd-*/SKILL.md when ~/.agents/skills already exists and ~/.config/agents/skills does not

Start a new Kimi CLI session after install, then invoke GSD skills with /skill:gsd-*, for example:

/skill:gsd-new-project

The installer also writes the GSD custom agent definition to the same selected config root: <configRoot>/agents/gsd.yaml with its prompt at <configRoot>/agents/gsd.md; subagents land under <configRoot>/agents/subagents/gsd-*.yaml and <configRoot>/agents/subagents/gsd-*.md.

Kimi custom agents do not auto-activate just because the files exist. Launch Kimi with the generated agent file when you want the GSD agent surface:

kimi --agent-file ~/.config/agents/agents/gsd.yaml

If your machine already uses ~/.agents/skills and does not have ~/.config/agents/skills, GSD installs there instead and the launch command becomes:

kimi --agent-file ~/.agents/agents/gsd.yaml

Kimi also discovers user skills from the brand-specific ~/.kimi-code directory. If your Kimi setup is already centered on ~/.kimi-code, install there explicitly:

npx @opengsd/gsd-core@latest --kimi --global --config-dir ~/.kimi-code

Then launch the generated agent from that directory:

kimi --agent-file ~/.kimi-code/agents/gsd.yaml

For brand-specific scripted installs, use:

KIMI_CONFIG_DIR=~/.kimi-code npx @opengsd/gsd-core@latest --kimi --global

Avoid arbitrary KIMI_CONFIG_DIR roots unless your Kimi configuration also adds the matching skills/ directory to Kimi's extra skill directories. GSD can write files there, but Kimi will not auto-discover skills outside its documented generic and brand-specific roots without that Kimi-side configuration.

--kimi --local is intentionally deferred and guarded in v1; use the global install path above for Kimi CLI.

---

GitHub Copilot

npx @opengsd/gsd-core@latest --copilot --global

Skills land in ~/.copilot/. GSD installs as agent .md files and repository instruction files.

GSD also wires Copilot's lifecycle hooks and instruction files:

• AGENTS.md (local installs) — written at the repository root, which GitHub Copilot CLI reads as primary instructions, alongside copilot-instructions.md.
• Lifecycle hook — a sessionStart hook config is written to .github/hooks/gsd-session.json (local) or ~/.copilot/hooks/gsd-session.json (global). It is a self-contained inline command hook (no separate hook script to install), so it can never reference a missing script. The hook is advisory-only: at session start it surfaces whether the project has a .planning/ workflow.

Both are removed (and any user-authored content preserved) on --uninstall.

Override the install directory:

COPILOT_CONFIG_DIR=~/.copilot-alt npx @opengsd/gsd-core@latest --copilot --global

---

Cursor

npx @opengsd/gsd-core@latest --cursor --global

Skills land in ~/.cursor/. GSD installs skills, agents, and rule references.

Override the install directory:

CURSOR_CONFIG_DIR=~/.cursor-alt npx @opengsd/gsd-core@latest --cursor --global

---

Windsurf / Devin Desktop

Windsurf has rebranded to Devin Desktop. Both runtime names are accepted — use either --windsurf or --devin-desktop.

npx @opengsd/gsd-core@latest --windsurf --global
# or equivalently:
npx @opengsd/gsd-core@latest --devin-desktop --global

Global skills land in ~/.codeium/windsurf/ (unchanged). Local workspace installs write to .devin/skills/ (Devin Desktop's preferred location, #1085); the legacy .windsurf/skills/ layout is still recognized for backward-compat. GSD installs skills, agents, and workspace rules.

Override the install directory:

WINDSURF_CONFIG_DIR=~/.codeium/windsurf-alt npx @opengsd/gsd-core@latest --windsurf --global

---

Cline

GSD gives Cline both skills (≥ v3.48.0) and the .clinerules/ directory integration — no custom slash commands are registered.

# Global install (all projects — skills + rules directory)
npx @opengsd/gsd-core@latest --cline --global

# Local install (this project only — rules directory only)
npx @opengsd/gsd-core@latest --cline --local

GSD writes the .clinerules/ directory form:

• .clinerules/gsd.md — the GSD rule file. Cline loads every .md/.txt file in the .clinerules/ directory automatically; no custom slash commands are registered.
• .clinerules/hooks/PreToolUse — a lifecycle hook (Cline v3.36+). It is an executable script that receives the tool-call context as JSON on stdin and returns a JSON decision (cancel / errorMessage / contextModification). The GSD hook guards .planning/ artifacts from direct edits and otherwise allows the operation; it fails open, so a hook error never blocks you. Cline runs hooks on macOS and Linux only.

Global install additionally:

• Emits each GSD command as ~/.cline/skills/<name>/SKILL.md. Cline ≥ v3.48.0 loads skills from ~/.cline/skills/ automatically — no configuration needed.
• Merges GSD instructions into ~/.agents/AGENTS.md, the cross-tool global instruction file Cline reads. The block is marker-delimited, so your own AGENTS.md content (and other tools' entries) is preserved, and --uninstall strips only the GSD block.

Local install writes the .clinerules/ directory into the current project only. No skills directory is created for local scope.

Cline's global hook directory (~/Documents/Cline/Rules/Hooks/) is not yet populated by the installer — project-scope hooks (.clinerules/hooks/) and the global AGENTS.md instruction target cover the common cases.

---

CodeBuddy

npx @opengsd/gsd-core@latest --codebuddy --global

GSD installs four surfaces. Slash command definitions land in ~/.codebuddy/commands/gsd-*.md and appear as /gsd-help, /gsd-phase, /gsd-ship, etc. in the / menu. Subagents land in ~/.codebuddy/agents/gsd-*.md. Skills land in ~/.codebuddy/skills/gsd-*/SKILL.md — emitted with user-invocable: false so they stay out of the / menu (the commands surface is the sole / entry point) and remain available for model invocation. CodeBuddy hooks are written to settings.json. No mcp.json is written: GSD ships no MCP server.

---

Qwen Code

Qwen Code uses the same open skills standard as Claude Code 2.1.88+.

npx @opengsd/gsd-core@latest --qwen --global

Skills land in ~/.qwen/skills/gsd-*/SKILL.md.

GSD's main-loop skills are emitted with Qwen's optional numeric priority frontmatter field so the most-used workflows surface first in the /skills TUI list. Higher values sort earlier (per Qwen's skills spec), so core commands such as /skills for new-project (100), plan-phase (90), and execute-phase (85) appear above utility skills, which are left unset (default 0). This affects only the /skills list order — slash-command completion and /help remain alphabetical.

Override the install directory:

QWEN_CONFIG_DIR=~/.qwen-alt npx @opengsd/gsd-core@latest --qwen --global

Hook coverage

Qwen Code supports 15 hook events. GSD registers the following events automatically on install:

Event	Hook	Purpose
SessionStart	gsd-check-update.js, gsd-session-state.sh	Update check, session orientation
PostToolUse	gsd-context-monitor.js, gsd-read-injection-scanner.js, gsd-phase-boundary.sh, gsd-graphify-update.sh	Context monitoring, read-time scan, phase boundary detection
PreToolUse	gsd-prompt-guard.js, gsd-read-guard.js, gsd-workflow-guard.js, gsd-worktree-path-guard.js, gsd-validate-commit.sh	Prompt guard, read-before-edit, workflow + worktree safety, commit validation
SubagentStop	gsd-context-monitor.js	Context headroom tracking after subagent completion
Stop	gsd-context-monitor.js	Context headroom tracking before model stop
PreCompact	gsd-context-monitor.js	Context awareness before conversation compaction

---

Augment Code

npx @opengsd/gsd-core@latest --augment --global

Skills land in ~/.augment/skills/ and slash command definitions land in ~/.augment/commands/. GSD installs skills, agents, and commands (/gsd-phase, /gsd-ship, etc.). No hook or statusline ownership.

---

Antigravity

npx @opengsd/gsd-core@latest --antigravity --global

The installer auto-detects the Antigravity config directory (~/.gemini/antigravity, ~/.gemini/antigravity-ide, or ~/.gemini/antigravity-cli). Uses Gemini-compatible settings policy.

Override the install directory:

ANTIGRAVITY_CONFIG_DIR=~/.gemini/antigravity-alt npx @opengsd/gsd-core@latest --antigravity --global

---

Trae

npx @opengsd/gsd-core@latest --trae --global

Skills land in ~/.trae/. GSD installs skills, agents, and rule references.

---

Local vs global install

All examples above use --global, which installs GSD once for your user account. To scope an install to a single project, replace --global with --local:

npx @opengsd/gsd-core@latest --claude --local

A local install writes into the .claude/ directory at your project root. Local install settings take precedence over global ones when both exist.

---

Installing prerelease editions (Next / Nightly / Insiders / Preview)

Prerelease editions of runtimes (Windsurf Next / Devin Desktop Next, Cursor Nightly, VS Code Insiders, Codex preview channels, etc.) read from a sibling config directory. Set the matching *_CONFIG_DIR env var before running the installer:

WINDSURF_CONFIG_DIR=~/.codeium/windsurf-next npx @opengsd/gsd-core@latest --windsurf --global

Select the corresponding stable runtime in the installer prompt. GSD does not enumerate prerelease editions as separate named runtimes — they are best-effort via this env-var mechanism and are not separately tested in release CI.

---

Installing without Node.js

If you cannot run npx (for example, on a Windows machine without Node.js), you have two options.

Option A — Use a machine that has Node.js. Any machine with Node.js will do: WSL, a Linux VM, a CI runner, or a Docker container. Run the installer there, then copy the output directory to your target machine. For OpenCode:

npx @opengsd/gsd-core@latest --opencode --global
# Then copy ~/.config/opencode/agents/ to the Windows machine

Option B — Manually transform the source files. The agent source files live in agents/ in the GSD Core repository and are in Claude Code's native frontmatter format. Each runtime expects a different shape. For the exact field transformations per runtime, see Manual install / no-Node.js setup in the User Guide, which covers the OpenCode transformations in full detail and points to the installer's convert*Frontmatter functions for other runtimes.

---

After install

Restart your runtime to pick up new commands and agents. Then start your first project:

/gsd-new-project

If the command is not found after restart, verify the install directory matches the runtime's expected config path. The prerelease-editions section above covers the most common mismatch.

---

Related

• Your first project
• Update GSD Core
• Configuration
• Docs index