pi-gstack

A Pi package that makes Garry Tan's gstack skills available inside Pi.

The package is an extension, not a static vendored copy. On first load it clones gstack into Pi's data directory, rewrites the SKILL.md files for Pi, and exposes the generated skills through Pi's resources_discover hook.

What it does

• Clones upstream gstack into ~/.pi/agent/gstack-pi/repo by default.
• Generates Pi-compatible skills into ~/.pi/agent/gstack-pi/skills.
• Sanitizes frontmatter to Pi's Agent Skills format.
• Rewrites hardcoded global ~/.claude/skills/gstack and project .claude/skills/gstack references to the Pi-managed gstack checkout.
• Namespaces skills as gstack-* by default, for example /skill:gstack-qa, /skill:gstack-review, /skill:gstack-ship.
• Adds Pi-native compatibility tools for upstream Claude Code workflows: AskUserQuestion, Agent/Task, TodoWrite, ExitPlanMode, and gstack_safety.
• Implements Pi-native safety enforcement for gstack-careful, gstack-freeze, gstack-guard, and gstack-unfreeze using Pi extension hooks.
• Suppresses upstream Claude Code team-mode/vendored-install migrations in generated skills so Pi never tries to remove the Pi-managed checkout or create .claude project scaffolding.
• Does not install or symlink anything into ~/.claude. It may create a Bun shim at ~/.pi/agent/bin/bun during /gstack-build so gstack binaries can find Bun from Pi's PATH.

Install

From a local checkout while developing:

pi install /absolute/path/to/pi-gstack

Or after you publish/push this repo, choose one install track.

Basic standalone install:

pi install npm:pi-gstack

Recommended full-parity install for native Pi specialist agents:

pi install npm:pi-subagents
pi install npm:pi-gstack

Git install while testing unpublished changes:

pi install git:github.com/salarsayyad/pi-gstack

Restart Pi or run /reload after install. pi-gstack works without pi-subagents; installing pi-subagents improves review/ship/autoplan workflows that use independent specialist agents.

Commands

This package adds three Pi commands:

Command	Purpose
/gstack-status	Show the gstack checkout path, generated skill count, Bun/shim status, build freshness, subagent support, active safety modes, and binary status.
/gstack-sync [ref]	Clone/update gstack and regenerate Pi skills. ref can be a branch, tag, or ref that git fetch origin <ref> can resolve. Marks the build stale when the upstream commit changes.
/gstack-build	Run gstack's Bun build, verify/install Playwright Chromium, codesign compiled binaries on Apple Silicon when possible, write build metadata, and regenerate Pi skills.

Use

With the default namespaced mode:

/skill:gstack-office-hours
/skill:gstack-plan-ceo-review
/skill:gstack-review
/skill:gstack-qa https://staging.example.com
/skill:gstack-ship

Run /gstack-status to see every path and whether the compiled gstack binaries are present.

Browser/design workflows

Many gstack skills work as pure methodology prompts. Browser, design, and PDF workflows need gstack's compiled binaries. Install Bun, then run:

/gstack-build

That command runs gstack's own build in the Pi-managed checkout. It can take a few minutes because gstack builds several Bun binaries and may install Playwright's Chromium. On macOS/Linux, upstream gstack's compiled browser helper still launches parts of the browser server with bun; /gstack-build tries to create ~/.pi/agent/bin/bun as a shim to the discovered Bun binary so those helpers work from Pi's PATH.

Compatibility behavior

pi-gstack now maps the most important Claude Code-specific gstack primitives into Pi:

Upstream gstack primitive	Pi behavior
AskUserQuestion	A real Pi custom tool that uses Pi UI dialogs when available, or returns a direct question fallback in print mode.
Agent / Task	A hardened compatibility fallback that runs a focused child pi --no-session -p process with inherited model/thinking, read-only tools by default, a generated context packet, bounded concurrency, structured report instructions, and retained debug artifacts. If pi-subagents is installed, generated skills also tell the model to prefer native Pi subagents for higher-fidelity specialist work. If child Pi is unavailable, the tool asks the current agent to complete the task inline.
TodoWrite	A lightweight compatibility tool that records the provided todo snapshot in the tool result.
ExitPlanMode	A no-op compatibility tool that terminates the tool loop with a Pi-specific plan-mode note.
Claude Code safety hooks	gstack_safety plus Pi tool_call hooks enforce destructive-command confirmation and freeze boundaries.

Safety shortcuts:

/skill:gstack-careful
/skill:gstack-freeze path/to/dir
/skill:gstack-guard path/to/dir
/skill:gstack-unfreeze

careful asks before dangerous bash commands such as recursive deletes, force pushes, hard resets, database drops, kubectl delete, and Docker destructive operations. freeze blocks edit and write outside the selected directory. guard combines both. These are guardrails, not a security sandbox; shell commands can still have side effects that a path hook cannot fully reason about.

Native subagent recommendation

pi-gstack intentionally does not auto-install pi-subagents. Instead it tells users at the right moments:

• /gstack-status always reports whether pi-subagents is available and shows pi install npm:pi-subagents when missing.
• On first interactive load, pi-gstack shows a one-time tip if pi-subagents is missing.
• On first Agent/Task fallback use, the tool result explains that the fallback is supported and shows the native subagent install command.

The standalone fallback is intentionally viable: child agents inherit the parent model/thinking when possible, run with read,bash,grep,find,ls by default, receive a compact git/session context packet, return a structured markdown report, and write artifacts under ~/.pi/agent/gstack-pi/agent-runs for debugging.

Configuration

Set these environment variables before starting Pi if you want different behavior:

Variable	Default	Meaning
GSTACK_PI_HOME	~/.pi/agent/gstack-pi	Where this package stores the gstack checkout and generated skills.
GSTACK_PI_REPO	https://github.com/garrytan/gstack.git	Upstream repo URL.
GSTACK_PI_REF	main	Initial ref to clone/fetch.
GSTACK_PI_PREFIX	true	Use gstack-* skill names. Set 0/false for short names like /skill:qa.
GSTACK_PI_AUTO_CLONE	true	Set 0/false to prevent first-start automatic clone.
GSTACK_PI_AGENT_TIMEOUT_MS	600000	Timeout for the Agent/Task compatibility child Pi process.
GSTACK_PI_AGENT_MODEL	parent model	Override child Pi model, for example google/gemini-3-pro.
GSTACK_PI_AGENT_THINKING	parent thinking	Override child Pi thinking level.
GSTACK_PI_AGENT_TOOLS	read,bash,grep,find,ls	Tool allowlist for child Pi fallback agents. Keep read-only by default for specialist reviews.
GSTACK_PI_AGENT_CONTEXT_MODE	packet	Context strategy for fallback agents. Currently uses a compact context packet.
GSTACK_PI_AGENT_CONCURRENCY	3	Maximum concurrent fallback child Pi processes.

Pi's own PI_CODING_AGENT_DIR is respected when computing the default data path.

Notes and limitations

• gstack was authored for Claude Code. This adapter now provides compatibility tools for the major Claude Code primitives, but some upstream wording may still say "Claude".
• Agent/Task works standalone through pi-gstack's hardened child-Pi fallback. For richer native Pi orchestration, install pi-subagents with pi install npm:pi-subagents.
• careful/freeze/guard enforce Pi tool-level guardrails, but they are not a sandbox and cannot prove every shell side effect is safe.
• Pair-agent/sidebar flows in upstream gstack may still require external CLIs such as claude, gh, ngrok, or browser credentials depending on the skill.
• gstack's own telemetry/config lives under ~/.gstack, per upstream behavior. Review upstream gstack before enabling telemetry.
• This package runs code on startup and clones an external repository. Pi packages and extensions run with your user permissions, so review the source before installing.

Development smoke test

If you have a gstack checkout locally:

npm run smoke -- /path/to/gstack

The smoke test generates Pi skill wrappers in a temp directory and verifies that the expected number of skills is produced.

License

MIT for this wrapper. gstack is MIT licensed upstream: https://github.com/garrytan/gstack.