# pi-gstack

A Pi package that makes [Garry Tan's gstack](https://github.com/garrytan/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:

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

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

Basic standalone install:

```bash
pi install npm:pi-gstack
```

Recommended full-parity install for native Pi specialist agents:

```bash
pi install npm:pi-subagents
pi install npm:pi-gstack
```

Git install while testing unpublished changes:

```bash
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:

```text
/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:

```text
/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:

```text
/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:

```bash
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>.