mirror of https://github.com/garrytan/gstack.git synced 2026-05-02 11:45:20 +02:00

Files

T

Garry Tan 1694a87113 docs: add README and CLAUDE.md

README with open source install instructions (project-level and user-level),
copy-paste CLAUDE.md snippet for users, command reference, and architecture.
CLAUDE.md with dev workflow for contributors.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

2026-03-11 15:18:59 -07:00

4.9 KiB

Raw Permalink Blame History

gstack-browse

Fast headless browser for Claude Code. Persistent Chromium daemon with ~100ms commands.

Navigate pages, read content, click elements, fill forms, run JavaScript, take screenshots, inspect CSS/DOM, capture console/network logs. No MCP server, no Chrome extension — just a fast CLI that Claude calls via Bash.

Created by Garry Tan, President & CEO of Y Combinator and founder of Garry's List.

Why

Claude Code needs to browse the web — check deployments, read docs, verify UI changes, test forms. Existing options (MCP servers, Chrome extensions) are slow, flaky, or require complex setup.

gstack-browse is different:

Fast: persistent Chromium daemon, ~100ms per command after first call
Simple: single CLI binary, auto-starts on first use, auto-shuts down after 30 min
Reliable: no WebSocket fragility, no extension permissions, just HTTP to a local server
Zero config: clone, build, done

Install

Prerequisites

Bun v1.0+

Option A: Project-level (recommended for teams)

Install into your repo so every contributor gets it automatically:

cd your-repo
git submodule add https://github.com/garrytan/gstack-browse.git .claude/skills/gstack-browse
cd .claude/skills/gstack-browse
bun install && bun run build

Commit the submodule. Anyone who clones your repo gets the skill.

Option B: User-level (personal)

Install once, available across all your projects:

git clone https://github.com/garrytan/gstack-browse.git ~/.claude/skills/gstack-browse
cd ~/.claude/skills/gstack-browse
bun install && bun run build

Verify

# Project-level:
.claude/skills/gstack-browse/dist/browse --help

# User-level:
~/.claude/skills/gstack-browse/dist/browse --help

Teach Claude to use it

Add this to your project's CLAUDE.md so Claude knows the skill is available:

## Web browsing

Use gstack-browse for all web browsing tasks. It's a fast headless browser CLI.

```bash
# Set the path (project-level install):
B=.claude/skills/gstack-browse/dist/browse
# Or user-level install:
# B=~/.claude/skills/gstack-browse/dist/browse

# Navigate and read
$B goto https://example.com
$B text                          # cleaned page text
$B html "main"                   # innerHTML of element
$B links                         # all links as "text -> href"

# Interact
$B click "button.submit"
$B fill "#email" "test@test.com"
$B select "#country" "US"
$B wait ".loaded"                # wait for element (max 10s)

# Inspect
$B js "document.title"           # run JavaScript
$B css "body" "font-family"      # computed CSS
$B console                       # captured console messages
$B network                       # captured network requests
$B screenshot /tmp/page.png      # take screenshot

# Tabs
$B tabs                          # list open tabs
$B newtab https://other.com      # open new tab
$B tab 2                         # switch to tab

# Multi-step (single call)
echo '[["goto","https://example.com"],["fill","#email","test@test.com"],["click","#submit"]]' | $B chain
```

Navigate once, then query many times — goto loads the page, everything else runs against it instantly.

Quick reference

Category	Commands
Navigate	`goto <url>`, `back`, `forward`, `reload`, `url`
Read	`text`, `html [sel]`, `links`, `forms`, `accessibility`
Interact	`click <sel>`, `fill <sel> <val>`, `select <sel> <val>`, `hover <sel>`, `type <text>`, `press <key>`, `scroll [sel]`, `wait <sel>`, `viewport <WxH>`
Inspect	`js <expr>`, `eval <file>`, `css <sel> <prop>`, `attrs <sel>`, `console`, `network`, `cookies`, `storage`, `perf`
Visual	`screenshot [path]`, `pdf [path]`, `responsive [prefix]`
Compare	`diff <url1> <url2>`
Tabs	`tabs`, `tab <id>`, `newtab [url]`, `closetab [id]`
Server	`status`, `stop`, `restart`

See SKILL.md for the full command reference with examples.

Architecture

Claude Code ──Bash──> browse CLI ──HTTP──> Bun server ──Playwright──> Chromium
                         |                     |
                    thin client           persistent daemon
                  (sends commands)      (port 9400-9410, auto-start,
                                         30 min idle shutdown)

CLI reads /tmp/browse-server.json for server port + auth token
If no server running, CLI auto-starts one in the background (~3s)
All commands go over HTTP POST with bearer token auth
Chromium crash or idle timeout kills the server; next CLI call restarts it

Development

bun install              # install dependencies
bun test                 # run 40 integration tests
bun run dev <cmd>        # run CLI without compiling
bun run build            # compile to dist/browse

License

MIT

4.9 KiB Raw Permalink Blame History