gstack/open-gstack-browser/SKILL.md.tmpl

---
name: open-gstack-browser
version: 0.2.0
description: |
  Launch GStack Browser — AI-controlled Chromium you can watch in real time.
  Opens a visible browser window where you see every action as it happens.
  Anti-bot stealth built in.
  Use when asked to "open gstack browser", "launch browser", "connect chrome",
  "open chrome", "real browser", "launch chrome", or "control my browser".
voice-triggers:
  - "show me the browser"
triggers:
  - open gstack browser
  - launch chromium
  - show me the browser
allowed-tools:
  - Bash
  - Read
  - AskUserQuestion

---

{{PREAMBLE}}

# /open-gstack-browser — Launch GStack Browser

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

{{BROWSE_SETUP}}

## 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.

```bash
# 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="$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

```bash
$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)
- A persistent profile (cookies and storage survive across runs)
- Anti-bot stealth patches (sites like Google and NYTimes work without captchas)
- Custom user agent and GStack Browser branding in Dock/menu bar

The `connect` command always uses port **34567**.

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

```bash
$B status
```

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

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

## Step 3: Verify the window is visible

Use AskUserQuestion:

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

Options:
- A) I can see the browser window — let's go!
- B) Something went wrong

If B:

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

Run a quick demo so the user sees Claude drive the browser:

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

Wait 2 seconds, then:

```bash
$B snapshot -i
```

Tell the user: "Watch the browser window — the `goto` navigates and `snapshot`
reads the page. Every command Claude runs happens in the visible window."

## Step 5: 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-review`, `/benchmark`) and watch
>   every action happen in the visible Chrome window
> - No cookie import needed — the Playwright browser shares its own session
>
> **Control the browser directly:**
> - **Browse commands** — `$B goto <url>`, `$B click <sel>`, `$B fill <sel> <val>`,
>   `$B snapshot -i` — all visible in the Chrome window
>
> **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-review` takes screenshots in the real browser — same pixels you see
> - `/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.