gstack-pi

Browser automation + guided workflow orchestrator for the pi coding agent.

One extension, two layers:

• 60 native browser tools — headless Chromium via gstack, ~100ms/command
• Workflow orchestrator — /gstack command that guides you through develop, investigate, QA, ship, and review pipelines

Requirements

• pi >= 0.82.0
• For updates only: Bun >= 1.3.0 + Git Bash (Windows)

Installation

1. Clone with submodules

git clone --recurse-submodules https://github.com/YOUR_USER/gstack-pi ~/.pi/agent/extensions/gstack-pi

Pi auto-discovers extensions in ~/.pi/agent/extensions/. No settings.json changes needed.

The browse binary is pre-built and included in runtime/. The extension works immediately after cloning.

The source/ submodule (~69MB) contains the gstack repo. It's only needed for updates — you can skip it on first clone with --no-recurse-submodules and fetch it later when you want to update.

2. Verify

Open pi in any project. Type /gstack — you should see the workflow menu.

Usage

The /gstack command

/gstack              # Interactive menu (context-aware, sorted by git state)
/gstack ship         # Start a specific workflow directly
/gstack investigate  # Bug debugging pipeline

The menu adapts to your git context:

• Uncommitted changes → "investigate" and "review" float to top
• Ahead of remote → "ship" floats to top
• On main branch → "develop" floats to top

Workflows

Workflow	Phases	Use case
develop	understand → plan → implement → QA → review → ship	Full feature cycle
investigate	reproduce → root-cause → fix → verify → QA (optional)	Systematic debugging
qa	setup → browser test → report → fix (optional)	Browser-based QA
ship	pre-checks → review → test → push+PR → verify CI	Release pipeline
review	diff analysis → findings → fix (optional)	Code review
quick	single action picker	One-shot actions

Each phase runs either in the main agent context (analysis, verification) or delegates to a subagent (implementation, heavy testing). The orchestrator injects structured instructions and advances automatically when you call gstack_advance.

Automatic routing

The extension monitors your input and suggests workflows when it detects intent:

• "why is login broken" → suggests investigate
• "let's ship this" → suggests ship
• "build a new dashboard" → suggests develop
• "test the site" → suggests qa

Suggestions are advisory — the LLM asks before starting a workflow. Slash commands and short inputs are never intercepted.

Browser tools (60)

All registered as native pi tools, callable by the LLM automatically:

gstack_goto, gstack_snapshot, gstack_click, gstack_fill,
gstack_screenshot, gstack_text, gstack_html, gstack_console,
gstack_network, gstack_responsive, gstack_diff, gstack_is,
gstack_cookie_import_browser, gstack_pdf, ...

Full list: see tools.generated.ts (60 commands from the gstack browse CLI).

Skills (23)

Cherry-picked gstack skills remain available for direct invocation:

/skill:gstack-qa, /skill:gstack-review, /skill:gstack-ship,
/skill:gstack-investigate, /skill:gstack-spec, /skill:gstack-autoplan, ...

These coexist with the orchestrator. Use them when you want the raw gstack workflow without the guided pipeline.

Environment Variables

Variable	Purpose	Default
GSTACK_BINARY	Absolute path to the browse binary	Auto-resolved
GSTACK_ROOT	Root of a gstack installation (alternative binary source)	Not set
GSTACK_REPO	Path to gstack source (overrides submodule for scripts)	<extension>/source/

Binary resolution order

The extension searches for the browse binary in this order:

1. $GSTACK_BINARY (explicit override)
2. $GSTACK_ROOT/browse/dist/browse (standard gstack install)
3. <extension>/runtime/browse/dist/browse (built by update.sh)
4. ../../gstack/browse/dist/browse (dev sibling layout)

On Windows, .exe is appended automatically.

Updating

# Full update: pull gstack submodule, rebuild binary, sync skills + bin scripts
bash ~/.pi/agent/extensions/gstack-pi/update.sh

# Rebuild without pulling (local patches in source/)
bash ~/.pi/agent/extensions/gstack-pi/update.sh --skip-pull

# Update the submodule to latest upstream manually
cd ~/.pi/agent/extensions/gstack-pi/source && git pull origin main

The script also detects new upstream features (skills, tools, bin scripts) not yet included in the extension and prints them:

╔══════════════════════════════════════════════════════════╗
║  NEW FEATURES AVAILABLE UPSTREAM — update extension!    ║
╚══════════════════════════════════════════════════════════╝

  [skill] gstack-canary
  [tool]  gstack_handoff
  [bin]   gstack-analytics

To include new skills: add them to SKILLS= in update.sh. To include new tools: run bun run scripts/gen-tools.ts.

Regenerating tools

When gstack adds new browse commands:

cd ~/.pi/agent/extensions/gstack-pi
bun run scripts/gen-tools.ts

This regenerates tools.generated.ts and lib/commands.generated.ts from source/browse/src/commands.ts.

Architecture

gstack-pi/
├── index.ts                 Entry: registers tools + orchestrator
├── tools.generated.ts       60 browser tool registrations (auto-generated)
├── lib/
│   ├── browse.ts            Binary resolution + subprocess spawn
│   ├── commands.ts          Allowlist re-export
│   ├── commands.generated.ts  Allowed command set (auto-generated)
│   └── schemas.ts           TypeBox parameter schemas
├── orchestrator/
│   ├── index.ts             Registers /gstack, gstack_advance, input router
│   ├── types.ts             Workflow, Phase, State interfaces
│   ├── state.ts             State machine (persist via pi appendEntry)
│   ├── git.ts               Git context detection
│   ├── workflows.ts         6 workflow definitions (data-driven)
│   ├── templates.ts         Phase instruction builders
│   ├── executor.ts          Phase execution + skip logic
│   ├── command.ts           /gstack command handler
│   └── router.ts            Input intent detection (transform, never block)
├── source/                  Git submodule → garrytan/gstack
├── runtime/                 Built by update.sh (gitignored)
│   ├── browse/dist/         Compiled browse binary + server bundle
│   └── bin/                 9 essential gstack helper scripts
├── skills/                  23 cherry-picked SKILL.md files
├── scripts/
│   ├── gen-tools.ts         Regenerate tools from source/ commands
│   └── sync-skills.ts       Re-sync skills with path rewriting
├── test/
│   └── orchestrator.test.ts Unit tests (state machine, workflows, intents)
├── update.sh                Pull submodule + build + deploy + feature detection
└── .gitignore               Excludes runtime/ (built artifacts)

How the orchestrator works

/gstack (command)  ──┐
                     ├──→ State Machine ──→ Phase Executor ──→ sendUserMessage()
input router ────────┘         ↑                                    │
                               │                                    ↓
                     gstack_advance ←──── LLM executes phase ←── instructions

1. User starts a workflow via /gstack or the router suggests one
2. The orchestrator injects phase instructions into the LLM context
3. The LLM executes (using browser tools, subagents, bash, etc.)
4. The LLM calls gstack_advance with a summary
5. The state machine advances to the next phase
6. Repeat until all phases complete

State persists across session reloads via pi's appendEntry (not sent to LLM context).

Token overhead

	Per-session fixed	Per-phase
Browser tools	~180 tokens (tool descriptions)	0
Orchestrator	~150 tokens (gstack_advance)	~600-1000 (instructions)
Skills (if loaded)	~7300 tokens each	0

Security

• Browse binary spawned with shell: false (no shell injection)
• Command allowlist: only the 60 registered commands can execute
• Output capped at 32,000 chars per tool call
• cookie-import-browser requires explicit user confirmation
• Input router never blocks (action: "handled" is never returned)

Troubleshooting

Problem	Fix
"gstack browse binary not found"	Run update.sh or set GSTACK_BINARY
"server-node.mjs not found" (Windows)	Run bash browse/scripts/build-node-server.sh in the gstack repo
/gstack not showing in pi	Ensure the extension is in ~/.pi/agent/extensions/gstack-pi/ with index.ts at root
Subagent phases fail	Ensure ~/.pi/agent/agents/ has scout.md, planner.md, worker.md, reviewer.md
Skills not loading	Pi requires "skills": ["./skills"] in a package.json, or project .pi/settings.json

License

MIT