gstack/skills/qa/references/legacy/open-gstack-browser.md

Host-neutral runtime bindings

These assignments select stable paths only; they do not install anything or grant consent:

GSTACK_HOME="${GSTACK_HOME:-$HOME/.gstack}"
GSTACK_ROOT="$GSTACK_HOME"
GSTACK_STATE_ROOT="$GSTACK_HOME"
GSTACK_BIN="$GSTACK_HOME/bin"
B="$GSTACK_BIN/browse"
D="$GSTACK_BIN/gstack-design"
P="$GSTACK_BIN/make-pdf"

$qa --mode Report --module open-gstack-browser — Launch GStack Browser

Launch GStack Browser — AI-controlled Chromium with the sidebar extension, anti-bot stealth, and custom branding. You see every action in real time.

SETUP (run this check BEFORE any browse command)

_ROOT=$(git rev-parse --show-toplevel 2>/dev/null)
B=""
[ -n "$_ROOT" ] && [ -x "$GSTACK_BIN/browse" ] && B="$GSTACK_BIN/browse"
[ -z "$B" ] && B="${GSTACK_HOME:-$HOME/.gstack}/bin/browse"
if [ -x "$B" ]; then
  echo "READY: $B"
else
  echo "NEEDS_SETUP"
fi

If NEEDS_SETUP:

1. Tell the user: "gstack browse needs a one-time build (~10 seconds). OK to proceed?" Then STOP and wait.
2. Read references/RUNTIME.md and follow its explicit capability bootstrap. Never assume a standard-installed skill directory contains ./setup.
3. If bun is not installed:

   if ! command -v bun >/dev/null 2>&1; then
     BUN_VERSION="1.3.10"
     BUN_INSTALL_SHA="bab8acfb046aac8c72407bdcce903957665d655d7acaa3e11c7c4616beae68dd"
     tmpfile=$(mktemp)
     curl -fsSL "https://bun.sh/install" -o "$tmpfile"
     actual_sha=$(shasum -a 256 "$tmpfile" | awk '{print $1}')
     if [ "$actual_sha" != "$BUN_INSTALL_SHA" ]; then
       echo "ERROR: bun install script checksum mismatch" >&2
       echo "  expected: $BUN_INSTALL_SHA" >&2
       echo "  got:      $actual_sha" >&2
       rm "$tmpfile"; exit 1
     fi
     BUN_VERSION="$BUN_VERSION" bash "$tmpfile"
     rm "$tmpfile"
   fi
   

Step 0: Pre-flight cleanup

Before connecting, kill any stale browse servers and clean up lock files that may have persisted from a crash. This prevents "already connected" false positives and Chromium profile lock conflicts.

# Kill any existing browse server
if [ -f "$(git rev-parse --show-toplevel 2>/dev/null)/.gstack/browse.json" ]; then
  _OLD_PID=$(cat "$(git rev-parse --show-toplevel)/.gstack/browse.json" 2>/dev/null | grep -o '"pid":[0-9]*' | grep -o '[0-9]*')
  [ -n "$_OLD_PID" ] && kill "$_OLD_PID" 2>/dev/null || true
  sleep 1
  [ -n "$_OLD_PID" ] && kill -9 "$_OLD_PID" 2>/dev/null || true
  rm -f "$(git rev-parse --show-toplevel)/.gstack/browse.json"
fi
# Clean Chromium profile locks (can persist after crashes)
_PROFILE_DIR="${GSTACK_HOME:-$HOME/.gstack}/chromium-profile"
for _LF in SingletonLock SingletonSocket SingletonCookie; do
  rm -f "$_PROFILE_DIR/$_LF" 2>/dev/null || true
done
echo "Pre-flight cleanup done"

Step 1: Connect

$B connect

This launches GStack Browser (rebranded Chromium) in headed mode with:

• A visible window you can watch (not your regular Chrome — it stays untouched)
• The gstack sidebar extension auto-loaded via launchPersistentContext
• Anti-bot stealth patches (sites like Google and NYTimes work without captchas)
• Custom user agent and GStack Browser branding in Dock/menu bar
• A sidebar agent process for chat commands

The connect command auto-discovers the extension from the gstack install directory. It always uses port 34567 so the extension can auto-connect.

After connecting, print the full output to the user. Confirm you see Mode: headed in the output.

If the output shows an error or the mode is not headed, run $B status and share the output with the user before proceeding.

Step 2: Verify

$B status

Confirm the output shows Mode: headed. Read the port from the state file:

cat "$(git rev-parse --show-toplevel 2>/dev/null)/.gstack/browse.json" 2>/dev/null | grep -o '"port":[0-9]*' | grep -o '[0-9]*'

The port should be 34567. If it's different, note it — the user may need it for the Side Panel.

Also find the extension path so you can help the user if they need to load it manually:

_EXT_PATH=$($GSTACK_BIN/gstack runtime path extension 2>/dev/null || true)
echo "EXTENSION_PATH: ${_EXT_PATH:-NOT FOUND}"

Step 3: Guide the user to the Side Panel

Use AskUserQuestion:

Chrome is launched with gstack control. You should see Playwright's Chromium (not your regular Chrome) with a golden shimmer line at the top of the page.

The Side Panel extension should be auto-loaded. To open it:

1. Look for the puzzle piece icon (Extensions) in the toolbar — it may already show the gstack icon if the extension loaded successfully
2. Click the puzzle piece → find gstack browse → click the pin icon
3. Click the pinned gstack icon in the toolbar
4. The Side Panel should open on the right showing a live activity feed

Port: 34567 (auto-detected — the extension connects automatically in the Playwright-controlled Chrome).

Options:

• A) I can see the Side Panel — let's go!
• B) I can see Chrome but can't find the extension
• C) Something went wrong

If B: Tell the user:

The extension is loaded into Playwright's Chromium at launch time, but sometimes it doesn't appear immediately. Try these steps:

1. Type chrome://extensions in the address bar
2. Look for "gstack browse" — it should be listed and enabled
3. If it's there but not pinned, go back to any page, click the puzzle piece icon, and pin it
4. If it's NOT listed at all, click "Load unpacked" and navigate to:
   • Press Cmd+Shift+G in the file picker dialog
   • Paste this path: {EXTENSION_PATH} (use the path from Step 2)
   • Click Select

After loading, pin it and click the icon to open the Side Panel.

If the Side Panel badge stays gray (disconnected), click the gstack icon and enter port 34567 manually.

If C:

1. Run $B status and show the output
2. If the server is not healthy, re-run Step 0 cleanup + Step 1 connect
3. If the server IS healthy but the browser isn't visible, try $B focus
4. If that fails, ask the user what they see (error message, blank screen, etc.)

Step 4: Demo

After the user confirms the Side Panel is working, run a quick demo:

$B goto https://news.ycombinator.com

Wait 2 seconds, then:

$B snapshot -i

Tell the user: "Check the Side Panel — you should see the goto and snapshot commands appear in the activity feed. Every command Claude runs shows up here in real time."

Step 5: Sidebar chat

After the activity feed demo, tell the user about the sidebar chat:

The Side Panel also has a chat tab. Try typing a message like "take a snapshot and describe this page." A sidebar agent (a child Claude instance) executes your request in the browser — you'll see the commands appear in the activity feed as they happen.

The sidebar agent can navigate pages, click buttons, fill forms, and read content. Each task gets up to 5 minutes. It runs in an isolated session, so it won't interfere with this Claude Code window.

Step 6: What's next

Tell the user:

You're all set! Here's what you can do with the connected Chrome:

Watch Claude work in real time:

• Run any gstack skill (/qa, $design --mode Implement --module design-review, $qa --mode Report --module benchmark) and watch every action happen in the visible Chrome window + Side Panel feed
• No cookie import needed — the Playwright browser shares its own session

Control the browser directly:

• Sidebar chat — type natural language in the Side Panel and the sidebar agent executes it (e.g., "fill in the login form and submit")
• Browse commands — $B goto <url>, $B click <sel>, $B fill <sel> <val>, $B snapshot -i — all visible in Chrome + Side Panel

Window management:

• $B focus — bring Chrome to the foreground anytime
• $B disconnect — close headed Chrome and return to headless mode

What skills look like in headed mode:

• /qa runs its full test suite in the visible browser — you see every page load, every click, every assertion
• $design --mode Implement --module design-review takes screenshots in the real browser — same pixels you see
• $qa --mode Report --module benchmark measures performance in the headed browser

Then proceed with whatever the user asked to do. If they didn't specify a task, ask what they'd like to test or browse.

Upstream judgment port: PR #679

Match the user language

User-language rule

Write questions, progress updates, reports, and artifacts in the language used by the user. Source material, code identifiers, commands, and quotations may remain in their original language when translating them would reduce accuracy.