Claude Code plugin packaging (--claude-plugin install)

[marcfargas]

Hi maintainers — pinging here rather than filing a fresh issue because the enhancement template has a pre-flight checkbox I can't honestly tick.

What I want to propose

An enhancement to the existing --claude install mode: a new --claude-plugin flag that swaps the on-disk layout for a Claude Code local marketplace (.claude-plugin/marketplace.json) + plugin tree, and registers it via claude plugin marketplace add / claude plugin install after emit. Same npx … install CLI surface, same /gsd:* command namespace, no marketplace publishing, no fork. --codex, --opencode, and the existing --claude mode are untouched.

By the enhancement template's own definitions this fits: I'm not adding new commands, workflows, or concepts — only re-targeting how --claude writes to disk.

What blocks me from filing directly

The enhancement template requires me to check:

I have searched existing issues — this has not already been proposed

It has, multiple times, in materially different shapes:

• GSD Plugin packaging for Claude Code marketplace #1883 (closed; redirected to discussions),
• Marketplace Installer Plugin for Claude Code #59, GSD Plugins #96 — earlier variants (closed)
• PR feat: add Claude Code marketplace plugin support #13 (closed; maintainer said revisit when upstream ${CLAUDE_PLUGIN_ROOT} bug fixed)
• PR feat: GSD Plugin System #118 (closed; was an internal-extension-system, different scope)
• Discussion Sharing gsd-plugin: a Claude Code plugin packaging of GSD - would upstream integration be useful? #2017 by @jnuyens — Sharing gsd-plugin (open; covers a downstream fork approach)

I can't honestly check the box. I also don't want to file as feature_request.yml, because by CONTRIBUTING.md's definitions it isn't one.

What block me from filing directly (2)

The enhancement template also requires me to check:

I have read the existing GSD commands and workflows and confirmed this feature does not duplicate existing behavior

Which would not be truthful. There is a current --claude install path, but it has several issues (see below) and this proposed approach avoids them.

What's different from prior art

PR #13 needed a SessionStart symlink hook to bridge @~/.claude/... references to the plugin cache path, which was rejected as too hacky.

This proposal reuses the installer's existing path-rewrite machinery (bin/install.js:copyWithPathReplacement) and rewrites references at install time to the marketplace+plugin layout. No symlink, no dependence on ${CLAUDE_PLUGIN_ROOT} (anthropics/claude-code#9354 still open), no marketplace publishing.

#2017 is a downstream fork; this proposal keeps one source of truth and adds --claude-plugin as an install-format flag.

Concrete bugs this would resolve as a side effect

The structural mechanism: in plugin mode the installer never calls writeSettings() on ~/.claude/settings.json. Claude Code itself writes the only required setting (extraKnownMarketplaces/enabledPlugins in project- or user-scope .claude/settings.json) via the claude plugin subprocess — sidestepping our settings-write code entirely.

• Codex on Windows: installer-generated SessionStart/PostToolUse hooks fail with exit code 1 #3426 — Windows settings.json corruption (root cause: our writeSettings())
• [BUG] Just ran /gsd-update and successfully updated to the latest version. But after restarting CC I'm getting ⚠ stale hooks — run /gsd-update. #2303 — "stale hooks" warning (hook scripts + VERSION co-located inside the plugin; desync impossible)
• npx install: gsd-sdk symlink never created when SHELL is Fish (getUserShellPath inherits npx PATH) #3091, Installer doesn't deploy sdk/ — model-catalog.cjs MODULE_NOT_FOUND on every gsd-tools invocation #3342 — --local SDK resolution gaps (plugin layout is self-contained)

Also, the current install method exposes GSD to all projects (on global install) with no easy way to enable/disable GSD. By leveraging the plugin system, enable/disable is a couple of keystrokes away.

Status

A working implementation lives on marcfargas:feat/claude-plugin-install that I wrote for my local use on Windows ARM

• my temp branch,
• code diff

Question

In summary: On the fly Claude Code plugin creation as a new install path. Is this approach preferred to the already rejected ones and acceptable?

[jnuyens]

Hi Marc — speaking up since I'm CC'd and I've spent the most time recently on the operational surface this would replace.

The proposal is technically sound and the bugs it'd fix (#3426, #2303, #3091, #3342) are real. The copyWithPathReplacement reuse is genuinely smart — re-targeting at install time rather than runtime is the cleanest dimension to vary on, and the "CC writes the settings, not the installer" mechanism elegantly sidesteps the entire writeSettings() blast radius.

Some operational traps I've hit maintaining gsd-plugin that --claude-plugin will also encounter, sharing so you don't rediscover them:

1. CLAUDE_PLUGIN_ROOT is not set in Bash tool environments by Claude Code. Verified empirically in CC 2.1.x — it's set for skill/agent dispatch contexts only. So any helper that reads it (getAgentsDir, state-project-load, model-catalog's candidate list) silently picks the wrong path when invoked from a workflow's bash block. Install-time path-rewriting sidesteps this if it rewrites every __dirname-relative traversal — worth auditing exhaustively. I just shipped a wrapper-env-export patch (bin/gsd-sdk exports CLAUDE_PLUGIN_ROOT + GSD_AGENTS_DIR before exec'ing node) as a single source of truth for this. Ref: jnuyens/gsd-plugin@94fe304.

2. SDK runtime deps must be bundled into dist/cli.js. I shipped a broken v2.42.0 that copied sdk/dist/ without node_modules/ — the bundled cli.js imported ws and @anthropic-ai/claude-agent-sdk from a missing dep tree. Hotfixed via tsc && esbuild --bundle --platform=node --format=esm --outfile=dist/cli.js --allow-overwrite with a createRequire shim banner. Plugin tree size: ~1.5 MB bundled vs ~81 MB if you ship node_modules/ raw. Ref: jnuyens/gsd-plugin@2683d16.

3. bin/lib/core.cjs::getAgentsDir() and bin/lib/model-catalog.cjs's 3-candidate resolver both bake in the upstream <root>/get-shit-done/bin/lib/ layout assumption. Flat-layout installs (which --claude-plugin will produce) need either an extra candidate prepended or a path-rewriter that knows about both. Patches: #PLUGIN-AGENTS-DIR, #PLUGIN-MODEL-CATALOG-PATH.

4. MCP stdio transport's LSP-style Content-Length: framing made the MCP server unreachable on Claude Code 2.x clients (issue #3 on my fork, fixed in v2.40.2). Generic to any distribution but worth pulling the fix into upstream while you're in there — external contributor (@Sovereigntymind) had a tested patch.

5. Plugin skills/ is a discovery surface. My tree has 83 skill descriptors mapping to plugin commands. Worth deciding whether --claude-plugin emits them, vs. routing through marketplace metadata — different UX implications for /plugin install gsd@gsd-plugin.

Two design questions:

• What's the update story? Re-running npx get-shit-done-cc@latest --claude-plugin to refresh breaks the auto-update UX Claude Code's /plugin marketplace update provides. Or does --claude-plugin register against a marketplace served from somewhere?
• How does it handle ws and @anthropic-ai/claude-agent-sdk at runtime? Vendor node_modules/, bundle into dist/cli.js, or rely on the user's npm? See trap Error: Bash command permission check failed when running /gsd:new-project #2.

What gsd-plugin carries beyond a fresh on-the-fly install. Some of these are extensions the fork has accumulated over 7 months that wouldn't naturally appear in a --claude-plugin emit — flagging them so the design conversation accounts for them:

• Auto-resume across /compact — PreCompact hook writes .planning/HANDOFF.json; next SessionStart auto-invokes /gsd:resume-work so Claude continues at the same phase/plan/task with zero manual intervention.
• PostToolUse periodic checkpoint — bridges CC's microcompact gap (60s mtime throttle, source=auto-postool). Catches sessions that get silently compacted without PreCompact firing.
• Rate-limit fallback Stop hook — tails the session transcript on Stop, surfaces the /exit + gsd-resume-at HH:MM no-token recovery path inline when the rate-limit pattern is detected.
• /gsd:resume-at — schedules a future resume without consuming tokens; ships a bin/gsd-resume-at shell wrapper.
• workspace.json SessionStart integration (#5/#6) — optional read of .agents/agents.workspace.json with strict major-version gating, prompt-injection sanitization, DoS guards. First external substantive contribution (@qmarcelle).
• Install-smoke CI running on every push + tag in a clean debian:trixie container — caught the v2.42.0 missing-deps regression on the first run.
• MCP stdio framing regression test (tests/mcp-stdio-framing.test.cjs) — fails exit-1 against the buggy v2.40.1 code; serves as a permanent fence.
• Plugin-marketplace discovery via davepoon/buildwithclaude (a Claude-ecosystem hub repo).

Some of these are pure plugin-architecture-only (PreCompact hook patterns; the /plugin install UX). Others (rate-limit Stop hook, workspace.json read, postool checkpoint) are mechanical and could plausibly migrate upstream behind --claude-plugin if the project wants them. Happy to break them out into separate PRs against upstream if any look interesting independent of the install-mode question.

On gsd-plugin specifically: my preference is that the two coexist rather than --claude-plugin obsoleting the fork. The traps in (1-5) are paid tuition that the fork has already socialised; the extras above are 7 months of plugin-shape-specific work. --claude-plugin as a first-party path serves the "stay on the official installer" cohort well, while gsd-plugin continues to serve the "auto-update via /plugin marketplace update" cohort. If you prefer to obsolete the fork I'll plan a graceful sunset, but I'd rather not unless that's the explicit upstream call.

Happy to share concrete patch diffs or do a focused review of marcfargas:feat/claude-plugin-install against the trap list — cross-referencing would tell us whether it covers the same surface or has gaps to close.

— Jasper

[marcfargas]

Thanks Jasper — this is exactly the second pair of eyes the proposal needed, and the trap list is concrete in a way only someone who's actually shipped a plugin build can produce.

Before going point-by-point: I want to be upfront that I've deliberately narrowed this discussion to "is --claude-plugin an acceptable install-format flag?" and left a lot of adjacent ground out. Several things you raised are real and worth doing — they're just not what I'm trying to get a green light on here. I'll flag those explicitly below rather than dodging them.

On the operational traps

1. CLAUDE_PLUGIN_ROOT unset in Bash tool envs. Confirmed. The branch sidesteps the runtime read entirely: copyWithPathReplacement rewrites @~/.claude/... references at install time, and the only place ${CLAUDE_PLUGIN_ROOT} appears in emitted output is inside hooks/hooks.json — which Claude Code expands itself at hook-launch (the upstream #9354 regression is command-markdown-only, doesn't apply to hook manifests).

2. SDK runtime deps bundling. Genuinely good to know — the v2.42.0 regression is the kind of thing I'd otherwise have walked into. Current branch ships the existing sdk/dist/ layout unchanged, so it inherits whatever --local does today, but plugin mode amplifies the cost (the whole tree lives under one install root). I guess if a bundle step is warranted I'd rather do that as a separate PR sequenced ahead, not bolted into the install-format change.

3. bin/lib/ resolvers. As above — not present upstream, so the flat-layout assumption breakage you flagged is fork-specific. Re-checking on the branch to confirm.

4. MCP stdio Content-Length: framing. Doesn't apply — upstream GSD doesn't ship an MCP server, so there's no surface for the bug or the fix to land on.

5. Skill descriptors as discovery surface. --claude-plugin emits whatever lives under get-shit-done/ today; the format of marketplace metadata isn't something this proposal touches (no marketplace at all — see the update-story answer below). Worth its own discussion if/when GSD does publish a marketplace.

Design questions

• Update story. Intentionally none beyond npx get-shit-done-cc@latest --claude-plugin. The proposal explicitly avoids registering against a hosted marketplace — that would introduce a totally separate install path and distribution channel for little gain. The cohort --claude-plugin serves is "I want the official installer, and I also want enable/disable + the bug-fixes that fall out of skipping writeSettings()". Auto-update UX is something they explicitly give up; that's a feature, not an omission.
• Runtime deps. See trap 2 — the branch inherits today's sdk/dist/ shape, and tightening that is on my radar but I'd handle it ahead of merge, not as part of this PR.

The 7-months-of-gsd-plugin list

Everything you listed (auto-resume across /compact, postool checkpoint, rate-limit Stop hook, /gsd:resume-at, workspace.json SessionStart, install-smoke CI, MCP framing regression test, buildwithclaude listing) — I deliberately left out of this discussion because each is a feature/process question on its own terms, not a property of where bytes land on disk. I don't want to entangle them with the install-format decision: if --claude-plugin is rejected, all those matters are still worth on their own. So my preference is that each one becomes its own upstream issue or PR — and I think they'd land better that way.

Coexistence

Strong agree. The framing proposed matches yours: --claude-plugin for the "stay on the official installer" cohort, gsd-plugin for the "auto-update via /plugin marketplace update" cohort. No interest in obsoleting the fork — the patches you've socialised are real value, and the update-via-marketplace UX is something this proposal explicitly doesn't try to replicate. If the project leadership later decides one path should sunset, that's a separate conversation that should involve you directly.

Cross-review offer

Yes please. The most useful artifact for me would be a diff or list — "here are the __dirname traversals / env reads / path assumptions that bit me", ordered by how likely they are to bite a flat-layout emit. If you run that against the branch (or want me to push a refreshed comparison link), gaps would shake out fast. Either format works.