v1.38.5: `npx get-shit-done-cc@latest --global` (README's command) leaves `gsd-sdk` off-PATH; installer reports `✓ GSD SDK ready` despite secondary bin never being symlinked

[LiamSarsfield]

TL;DR

The README's documented install command (npx get-shit-done-cc@latest …) does not put gsd-sdk on PATH on a fresh install of get-shit-done-cc@1.38.5. The installer prints ✓ GSD SDK ready (sdk/dist/cli.js) and exits 0, but every subsequent /gsd-* command fails with command not found: gsd-sdk. Root cause: the fix/2441-sdk-decouple architecture relies on npm symlinking the in-package bin/gsd-sdk.js shim into the global bin dir, which only happens for npm install -g get-shit-done-cc — npx never creates that symlink for secondary bins.

Environment

Field	Value
GSD Version	1.38.5
Runtime	Claude Code
Operating System	macOS (Darwin 25.4.0)
Node.js Version	v24.14.1
Node manager	nvm
Shell	zsh
Installation Method	npx get-shit-done-cc@latest (fresh run)
npm global prefix	~/.nvm/versions/node/v24.14.1 (already on PATH)

Reproduce

Fresh shell, no prior global install of get-shit-done-cc:

$ which gsd-sdk
gsd-sdk not found

$ npx get-shit-done-cc@latest --claude --global
[...installer banner...]
  ✓ Installed 85 skills to skills/
  ✓ Installed get-shit-done
  ✓ Installed agents
  ✓ Wrote VERSION (1.38.5)
  ✓ Wrote package.json (CommonJS mode)
  ✓ Installed hooks (bundled)
  ✓ Wrote file manifest (gsd-file-manifest.json)
  ✓ GSD SDK ready (sdk/dist/cli.js)
  Done! Open a blank directory in Claude Code and run /gsd-new-project.

$ which gsd-sdk
gsd-sdk not found

$ ls $(npm config get prefix)/bin/ | grep -E "(gsd-sdk|get-shit-done-cc)"
# (no output)

$ /gsd-new-project   # in Claude Code
# workflow's first step: gsd-sdk query init.new-project
# → command not found: gsd-sdk

Expected: after the installer reports ✓ GSD SDK ready, gsd-sdk is callable from the user's shell. Actual: it isn't. The shim file is present in the npx cache (~/.npm/_npx/<hash>/node_modules/get-shit-done-cc/bin/gsd-sdk.js) but no symlink ever lands in npm's global bin dir.

Workaround that does work:

$ npm install -g get-shit-done-cc@latest
$ which gsd-sdk
/Users/<USER>/.nvm/versions/node/v24.14.1/bin/gsd-sdk

Root cause

npx <pkg> fetches the package into ~/.npm/_npx/<hash>/ and runs the package's primary bin once from that cache. It does not install the package globally and does not create symlinks for the package's secondary bins in npm's global bin dir. Only npm install -g <pkg> triggers npm's bin-linking behavior, which is what creates ~/.npm-global/bin/gsd-sdk → …/get-shit-done-cc/bin/gsd-sdk.js.

The --global flag in npx get-shit-done-cc --global is parsed by bin/install.js, not by npm — it tells the installer to write GSD configs to ~/.claude/ rather than ./.claude/. It has no effect on whether the npm package is installed globally.

Sources:

• npm Docs — Downloading and installing packages globally
• Replace global installations with npx

Secondary bug — README still recommends npx and claims the SDK is auto-installed

README hero command:

npx get-shit-done-cc@latest

README "Non-interactive Install" section:

# Claude Code
npx get-shit-done-cc --claude --global   # Install to ~/.claude/
npx get-shit-done-cc --claude --local    # Install to ./.claude/
# OpenCode
npx get-shit-done-cc --opencode --global # Install to ~/.config/opencode/
# ...

Followed by:

"The GSD SDK CLI (gsd-sdk) is installed automatically (required by /gsd-* commands). Pass --no-sdk to skip the SDK install, or --sdk to force a reinstall."

Both claims are now incorrect for the headline command path. The installer's own error path agrees: when SDK files are missing, it prints

Fix: install a version that ships sdk/dist/ globally:
npm install -g get-shit-done-cc@latest

(bin/install.js ~line 7217). The README and the installer's recommended-fix line currently disagree.

Tertiary bug — bin/gsd-sdk.js shim comment also claims npx creates the symlink

bin/gsd-sdk.js lines 4–9:

/**
 * bin/gsd-sdk.js — back-compat shim for external callers of `gsd-sdk`.
 *
 * When the parent package is installed globally (`npm install -g get-shit-done-cc`
 * or `npx get-shit-done-cc`), npm creates a `gsd-sdk` symlink in the global bin
 * directory pointing at this file. […]
 */

The "or npx get-shit-done-cc" clause is the architectural assumption that breaks the README path. npx does not create global symlinks; this comment encodes the incorrect mental model that produced both this bug and the README mismatch.

Quaternary bug — installSdkIfNeeded is verify-only and prints success when the bin is off-PATH

bin/install.js, installSdkIfNeeded (around line 7170): the function checks two things and prints ✓ GSD SDK ready when both pass:

1. fs.existsSync(sdkCliPath) — does sdk/dist/cli.js exist inside the package directory? (passes — it's in the npx cache)
2. maybeSuggestPathExport(globalBin, homedir) — is npm's global bin dir on PATH? (passes via nvm — only emits a warning when missing from PATH)

The function never executes anything equivalent to which gsd-sdk / command -v gsd-sdk / spawnSync('gsd-sdk', ['--version']). So the success message is a file-presence + PATH-shape signal, not a callability signal. Combined with the README's npx recommendation, this turns the failure mode silent: users see green checkmarks, then command not found on first /gsd-* invocation.

Comment in installAllRuntimes (bin/install.js ~line 7279) makes the assumption explicit:

// gsd-sdk reaches users via the parent package's bin/gsd-sdk.js shim, so no sub-install is needed.

True for npm install -g, false for npx.

Impact

Blocker for users following the README. Every /gsd-* command fails with command not found: gsd-sdk (or its programmatic equivalent — Exit code 127 from inside Claude Code's Bash tool). The user has no signal that the install was incomplete: the final installer message says Done! Open a blank directory in Claude Code and run /gsd-new-project, and /gsd-new-project fails on the first gsd-sdk query init.new-project line of its workflow.

Affected commands include at minimum: /gsd-new-project, /gsd-health, /gsd-quick, /gsd-plan-phase, /gsd-execute-phase, /gsd-progress, /gsd-set-profile, /gsd-discuss-phase, /gsd-resume-work. (Anything calling gsd-sdk query ….)

Suggested fix

Three non-exclusive directions, in order of effort:

(A) Update the README to recommend npm install -g get-shit-done-cc@latest as the headline install command, with npx reserved for one-shot tries that don't need GSD slash commands. Update bin/gsd-sdk.js's header comment to remove the "or npx get-shit-done-cc" clause. Lowest effort, highest correctness, but breaks muscle memory for existing users and existing tutorials.

(B) Add a real callability check at the end of installSdkIfNeeded: spawn gsd-sdk --help (or equivalent) with stdio: 'ignore' and a 5-second timeout. If it exits non-zero or ENOENT, print a loud red banner with remediation instructions instead of ✓ GSD SDK ready. This catches the npx case explicitly and converts the silent failure into a loud one. Recommended as a defense-in-depth addition regardless of (A) or (C).

(C) Have the installer detect the npx-cache execution context and shell out to npm install -g get-shit-done-cc@<thisVersion> itself. The installer already detects this context (see classifySdkInstall and ctx.npxCache branches in bin/install.js). Adding an opt-in / prompted npm install -g step would make the README's headline command Just Work. Risk: nested global installs are noisy and have permission issues on some systems (#2513-class problems); needs careful handling.

Personally I'd start with (A) + (B): documentation alignment plus a callability gate, both small and unambiguous. (C) is a bigger lift but is the only option that keeps the README's npx headline accurate.

Related

• gsd-sdk binary missing after install — --sdk flag documented but not implemented #2385 — gsd-sdk binary missing after install — --sdk flag documented but not implemented (closed; pre-decouple architecture)
• installer: escalate or recover when gsd-sdk is installed but off-PATH after #2386 #2441 — installer: escalate or recover when gsd-sdk is installed but off-PATH after fix(install): auto-install @gsd-build/sdk so gsd-sdk is on PATH #2386 (closed; assumed fixed by decouple, but the off-PATH escalation it called for never made it back into the new architecture — this issue is effectively a regression of installer: escalate or recover when gsd-sdk is installed but off-PATH after #2386 #2441's "Decide installer policy when SDK ends up off-PATH" todo)
• gsd-quick crashes with command not found: gsd-sdk when gsd-sdk CLI is not in PATH #2334 — /gsd-quick crashes with command not found: gsd-sdk (closed)
• installSdkIfNeeded: tsc-built dist/cli.js lands with mode 644 on fresh installs, leaving gsd-sdk non-executable #2453 — installSdkIfNeeded: tsc-built dist/cli.js lands with mode 644 (closed; different root cause)
• installer: gsd-sdk symlink points into /root/.npm/_npx/... after sudo install, unreachable for non-root users #2513 — gsd-sdk symlink points into /root/.npm/_npx/... after sudo install (wontfix; partial overlap)
• v1.38.3: workflow docs reference gsd-sdk query <noun> but shipped gsd-sdk only exposes run | auto | init #2647 — workflow docs reference gsd-sdk query <noun> but shipped binary lacks it (closed)
• Publish @gsd-build/sdk with query subcommand fix from main (npm latest 0.1.0 still missing it) #2685 — Publish @gsd-build/sdk with query subcommand fix from main (open; different code path — current 1.38.5 ships the shim in-package and no longer depends on @gsd-build/sdk)

Privacy Checklist

• I have reviewed all pasted output for PII (usernames, paths, API keys) and redacted where necessary.

[trek-e]

Triaged. Confirmed bug, reproduced reasoning against bin/install.js and bin/gsd-sdk.js shim header.

Root cause confirmed. The reporter's analysis is correct end-to-end:

1. npx <pkg> populates ~/.npm/_npx/<hash>/ and runs only the package's primary bin from that ephemeral cache. It does not register the package globally and does not create symlinks for bin map entries other than the one being executed. Per npm CLI source and docs, only npm install -g <pkg> invokes the bin-link step that materializes secondary bins (gsd-sdk here) into $(npm prefix -g)/bin/.
2. bin/gsd-sdk.js header comment explicitly encodes the wrong assumption ("or npx get-shit-done-cc"). That assumption silently propagates through installSdkIfNeeded.
3. installSdkIfNeeded performs presence + PATH-shape checks only — it never executes gsd-sdk to verify callability. The ✓ GSD SDK ready line is therefore a false positive in the npx-cache execution context.

Invariant violated. The post-install invariant should be: command -v gsd-sdk resolves to an executable on the user's PATH. The installer asserts a weaker invariant (file exists in package + global bin dir is on PATH) and treats the conjunction as proof of the stronger invariant. It is not — the missing link is the symlink itself.

Suggested fix direction. Reporter's (B) is the minimal correct gate: replace the file-presence assertion with a callability probe (spawnSync(process.execPath, [require.resolve('../sdk/dist/cli.js'), '--version'], { stdio: 'ignore', timeout: 5000 }) is fine — it tests the CLI works under Node, then a separate spawnSync('gsd-sdk', ['--version']) tests PATH resolution; only the second failing should downgrade the message). (A) (README correction) is the orthogonal lowest-cost fix and should ship in the same PR. (C) (auto npm install -g) introduces sudo/permission failure modes seen in #2513 and should be deferred behind a prompt.

Also relevant: bin/install.js ~L7170 (installSdkIfNeeded) and ~L7279 (installAllRuntimes comment) both need updating; the shim header at bin/gsd-sdk.js:4-9 needs the "or npx" clause removed.

Related history: this is a regression of the off-PATH escalation TODO from #2441 that did not survive the 2441 decouple. #2685 is a separate path (publishing @gsd-build/sdk standalone) and does not solve this.

Labels updated: bug, priority: high, area: installer. Not closing — ready for fix.

[github-actions]

Branch fix/2775-v1-38-5-npx-get-shit-done-cc-latest-glob created.

git fetch origin && git checkout fix/2775-v1-38-5-npx-get-shit-done-cc-latest-glob

[patrickclery]

Hit this on 1.38.5 today and want to add one more data point: /gsd-update itself reproduces this bug, so users who never touch the README's headline command also land in the broken state.

~/.claude/get-shit-done/workflows/update.md step run_update runs:

# If GLOBAL install:
npx -y get-shit-done-cc@latest "$RUNTIME_FLAG" --global

So the upgrade path (/gsd-update → npx -y get-shit-done-cc@latest --claude --global) has the same npx + installer-flag---global confusion as the README. Net effect: any user who installed once via npm install -g and later runs /gsd-update removes their working install — because npx doesn't refresh global bin symlinks and the previously-symlinked gsd-sdk may now point at a stale dist (or get clobbered, depending on which version was last globally installed). On a system that only used npx from day one, /gsd-update perpetuates the broken state forever.

Reproducer:

$ which gsd-sdk
gsd-sdk not found

# In Claude Code:
/gsd-update
# → installer banner, "✓ GSD SDK ready", "Done!"

$ which gsd-sdk
gsd-sdk not found

$ /gsd-add-phase whatever
# → Bash(gsd-sdk query init.phase-op "0")
# → Error: Exit code 127 — command not found: gsd-sdk

# Workaround (works):
$ npm install -g get-shit-done-cc@latest
$ which gsd-sdk
/Users/<USER>/.../bin/gsd-sdk

So the suggested fix in the original report extends to one more file: get-shit-done/workflows/update.md should run npm install -g get-shit-done-cc@<latest> (and let the package's postinstall or its bin/install.js handle the runtime wiring), not npx -y get-shit-done-cc@latest --global. Otherwise (B) (callability gate) is the only thing that catches the /gsd-update path, since (A) (README fix) doesn't reach users invoking the slash command.

Also: this issue is currently in state closed but the triage comment says "Not closing — ready for fix" and there's no PR linked. Was this closed accidentally? Happy to file a separate issue specifically scoped to /gsd-update if you'd prefer that over a comment here.

— Hit on Linux (Arch/CachyOS), Node v22.22.1, mise-managed npm prefix, zsh. Confirmed npm install -g get-shit-done-cc@latest resolves it cleanly.