name: gstack version: 1.1.0 description: | Fast headless browser for QA testing and site dogfooding. Navigate any URL, interact with elements, verify page state, diff before/after actions, take annotated screenshots, check responsive layouts, test forms and uploads, handle dialogs, and assert element states. ~100ms per command. Use when you need to test a feature, verify a deployment, dogfood a user flow, or file a bug with evidence. allowed-tools:
_UPD=$(~/.claude/skills/gstack/bin/gstack-update-check 2>/dev/null || .claude/skills/gstack/bin/gstack-update-check 2>/dev/null || true)
[ -n "$_UPD" ] && echo "$_UPD" || true
If output shows UPGRADE_AVAILABLE <old> <new>: read ~/.claude/skills/gstack/gstack-upgrade/SKILL.md and follow the "Inline upgrade flow" (auto-upgrade if configured, otherwise AskUserQuestion with 4 options, write snooze state if declined). If JUST_UPGRADED <from> <to>: tell user "Running gstack v{to} (just updated!)" and continue.
Persistent headless Chromium. First call auto-starts (~3s), then ~100-200ms per command. Auto-shuts down after 30 min idle. State persists between calls (cookies, tabs, sessions).
_ROOT=$(git rev-parse --show-toplevel 2>/dev/null)
B=""
[ -n "$_ROOT" ] && [ -x "$_ROOT/.claude/skills/gstack/browse/dist/browse" ] && B="$_ROOT/.claude/skills/gstack/browse/dist/browse"
[ -z "$B" ] && B=~/.claude/skills/gstack/browse/dist/browse
if [ -x "$B" ]; then
echo "READY: $B"
else
echo "NEEDS_SETUP"
fi
If NEEDS_SETUP:
cd <SKILL_DIR> && ./setupbun is not installed: curl -fsSL https://bun.sh/install | bash$B <command>mcp__claude-in-chrome__* tools. They are slow and unreliable.# 1. Go to the page
$B goto https://app.example.com/login
# 2. See what's interactive
$B snapshot -i
# 3. Fill the form using refs
$B fill @e3 "test@example.com"
$B fill @e4 "password123"
$B click @e5
# 4. Verify it worked
$B snapshot -D # diff shows what changed after clicking
$B is visible ".dashboard" # assert the dashboard appeared
$B screenshot /tmp/after-login.png
$B goto https://yourapp.com
$B text # read the page — does it load?
$B console # any JS errors?
$B network # any failed requests?
$B js "document.title" # correct title?
$B is visible ".hero-section" # key elements present?
$B screenshot /tmp/prod-check.png
# Navigate to the feature
$B goto https://app.example.com/new-feature
# Take annotated screenshot — shows every interactive element with labels
$B snapshot -i -a -o /tmp/feature-annotated.png
# Find ALL clickable things (including divs with cursor:pointer)
$B snapshot -C
# Walk through the flow
$B snapshot -i # baseline
$B click @e3 # interact
$B snapshot -D # what changed? (unified diff)
# Check element states
$B is visible ".success-toast"
$B is enabled "#next-step-btn"
$B is checked "#agree-checkbox"
# Check console for errors after interactions
$B console
# Quick: 3 screenshots at mobile/tablet/desktop
$B goto https://yourapp.com
$B responsive /tmp/layout
# Manual: specific viewport
$B viewport 375x812 # iPhone
$B screenshot /tmp/mobile.png
$B viewport 1440x900 # Desktop
$B screenshot /tmp/desktop.png
# Element screenshot (crop to specific element)
$B screenshot "#hero-banner" /tmp/hero.png
$B snapshot -i
$B screenshot @e3 /tmp/button.png
# Region crop
$B screenshot --clip 0,0,800,600 /tmp/above-fold.png
# Viewport only (no scroll)
$B screenshot --viewport /tmp/viewport.png
$B goto https://app.example.com/upload
$B snapshot -i
$B upload @e3 /path/to/test-file.pdf
$B is visible ".upload-success"
$B screenshot /tmp/upload-result.png
$B goto https://app.example.com/form
$B snapshot -i
# Submit empty — check validation errors appear
$B click @e10 # submit button
$B snapshot -D # diff shows error messages appeared
$B is visible ".error-message"
# Fill and resubmit
$B fill @e3 "valid input"
$B click @e10
$B snapshot -D # diff shows errors gone, success state
# Set up dialog handling BEFORE triggering
$B dialog-accept # will auto-accept next alert/confirm
$B click "#delete-button" # triggers confirmation dialog
$B dialog # see what dialog appeared
$B snapshot -D # verify the item was deleted
# For prompts that need input
$B dialog-accept "my answer" # accept with text
$B click "#rename-button" # triggers prompt
# Import cookies from your real browser (opens interactive picker)
$B cookie-import-browser
# Or import a specific domain directly
$B cookie-import-browser comet --domain .github.com
# Now test authenticated pages
$B goto https://github.com/settings/profile
$B snapshot -i
$B screenshot /tmp/github-profile.png
$B diff https://staging.app.com https://prod.app.com
echo '[
["goto","https://app.example.com"],
["snapshot","-i"],
["fill","@e3","test@test.com"],
["fill","@e4","password"],
["click","@e5"],
["snapshot","-D"],
["screenshot","/tmp/result.png"]
]' | $B chain
# Element exists and is visible
$B is visible ".modal"
# Button is enabled/disabled
$B is enabled "#submit-btn"
$B is disabled "#submit-btn"
# Checkbox state
$B is checked "#agree"
# Input is editable
$B is editable "#name-field"
# Element has focus
$B is focused "#search-input"
# Page contains text
$B js "document.body.textContent.includes('Success')"
# Element count
$B js "document.querySelectorAll('.list-item').length"
# Specific attribute value
$B attrs "#logo" # returns all attributes as JSON
# CSS property
$B css ".button" "background-color"
The snapshot is your primary tool for understanding and interacting with pages.
-i --interactive Interactive elements only (buttons, links, inputs) with @e refs
-c --compact Compact (no empty structural nodes)
-d <N> --depth Limit tree depth (0 = root only, default: unlimited)
-s <sel> --selector Scope to CSS selector
-D --diff Unified diff against previous snapshot (first call stores baseline)
-a --annotate Annotated screenshot with red overlay boxes and ref labels
-o <path> --output Output path for annotated screenshot (default: /tmp/browse-annotated.png)
-C --cursor-interactive Cursor-interactive elements (@c refs — divs with pointer, onclick)
All flags can be combined freely. -o only applies when -a is also used.
Example: $B snapshot -i -a -C -o /tmp/annotated.png
Ref numbering: @e refs are assigned sequentially (@e1, @e2, ...) in tree order.
@c refs from -C are numbered separately (@c1, @c2, ...).
After snapshot, use @refs as selectors in any command:
$B click @e3 $B fill @e4 "value" $B hover @e1
$B html @e2 $B css @e5 "color" $B attrs @e6
$B click @c1 # cursor-interactive ref (from -C)
Output format: indented accessibility tree with @ref IDs, one element per line.
@e1 [heading] "Welcome" [level=1]
@e2 [textbox] "Email"
@e3 [button] "Submit"
Refs are invalidated on navigation — run snapshot again after goto.
| Command | Description |
|---|---|
back |
History back |
forward |
History forward |
goto <url> |
Navigate to URL |
reload |
Reload page |
url |
Print current URL |
| Command | Description |
|---|---|
accessibility |
Full ARIA tree |
forms |
Form fields as JSON |
html [selector] |
innerHTML of selector (throws if not found), or full page HTML if no selector given |
links |
All links as "text → href" |
text |
Cleaned page text |
| Command | Description | ||
|---|---|---|---|
click <sel> |
Click element | ||
cookie <name>=<value> |
Set cookie on current page domain | ||
cookie-import <json> |
Import cookies from JSON file | ||
cookie-import-browser [browser] [--domain d] |
Import cookies from Comet, Chrome, Arc, Brave, or Edge (opens picker, or use --domain for direct import) | ||
dialog-accept [text] |
Auto-accept next alert/confirm/prompt. Optional text is sent as the prompt response | ||
dialog-dismiss |
Auto-dismiss next dialog | ||
fill <sel> <val> |
Fill input | ||
header <name>:<value> |
Set custom request header (colon-separated, sensitive values auto-redacted) | ||
hover <sel> |
Hover element | ||
press <key> |
Press key — Enter, Tab, Escape, ArrowUp/Down/Left/Right, Backspace, Delete, Home, End, PageUp, PageDown, or modifiers like Shift+Enter | ||
scroll [sel] |
Scroll element into view, or scroll to page bottom if no selector | ||
select <sel> <val> |
Select dropdown option by value, label, or visible text | ||
type <text> |
Type into focused element | ||
upload <sel> <file> [file2...] |
Upload file(s) | ||
useragent <string> |
Set user agent | ||
viewport <WxH> |
Set viewport size | ||
| `wait <sel | --networkidle | --load>` | Wait for element, network idle, or page load (timeout: 15s) |
| Command | Description | |
|---|---|---|
| `attrs <sel | @ref>` | Element attributes as JSON |
| `console [--clear | --errors]` | Console messages (--errors filters to error/warning) |
cookies |
All cookies as JSON | |
css <sel> <prop> |
Computed CSS value | |
dialog [--clear] |
Dialog messages | |
eval <file> |
Run JavaScript from file and return result as string (path must be under /tmp or cwd) | |
is <prop> <sel> |
State check (visible/hidden/enabled/disabled/checked/editable/focused) | |
js <expr> |
Run JavaScript expression and return result as string | |
network [--clear] |
Network requests | |
perf |
Page load timings | |
storage [set k v] |
Read all localStorage + sessionStorage as JSON, or set to write localStorage |
| Command | Description | |
|---|---|---|
diff <url1> <url2> |
Text diff between pages | |
pdf [path] |
Save as PDF | |
responsive [prefix] |
Screenshots at mobile (375x812), tablet (768x1024), desktop (1280x720). Saves as {prefix}-mobile.png etc. | |
| `screenshot [--viewport] [--clip x,y,w,h] [selector | @ref] [path]` | Save screenshot (supports element crop via CSS/@ref, --clip region, --viewport) |
| Command | Description |
|---|---|
snapshot [flags] |
Accessibility tree with @e refs for element selection. Flags: -i interactive only, -c compact, -d N depth limit, -s sel scope, -D diff vs previous, -a annotated screenshot, -o path output, -C cursor-interactive @c refs |
| Command | Description |
|---|---|
chain |
Run commands from JSON stdin. Format: [["cmd","arg1",...],...] |
| Command | Description |
|---|---|
closetab [id] |
Close tab |
newtab [url] |
Open new tab |
tab <id> |
Switch to tab |
tabs |
List open tabs |
| Command | Description |
|---|---|
restart |
Restart server |
status |
Health check |
stop |
Shutdown server |
goto loads the page; then text, js, screenshot all hit the loaded page instantly.snapshot -i first. See all interactive elements, then click/fill by ref. No CSS selector guessing.snapshot -D to verify. Baseline → action → diff. See exactly what changed.is for assertions. is visible .modal is faster and more reliable than parsing page text.snapshot -a for evidence. Annotated screenshots are great for bug reports.snapshot -C for tricky UIs. Finds clickable divs that the accessibility tree misses.console after actions. Catch JS errors that don't surface visually.chain for long flows. Single command, no per-step CLI overhead.