Pinchtab: The 12 MB Go Browser API for AI Agents

Modern AI agents need a reliable, low‑cost way to read, interact with, and control web pages. Existing solutions such as Playwright, Puppeteer, or Browser Use often bring heavy runtimes, tight language bindings, or unnecessary overhead. Pinchtab solves the problem with a single, self‑contained Go binary that starts a headless Chrome instance, exposes a pure HTTP API, and is token‑efficient enough to make it attractive for large‑scale, read‑heavy workloads.

What is Pinchtab?

• Standalone HTTP server – no language SDK required; curl, Python, Rust, or any OpenAI agent can talk to it.
• 12 MB Go binary – built with go build, no external dependencies at runtime.
• Chrome under the hood – manages actual Chromium, but abstracts all the hard work behind a clean, structured API.
• Dual modes – headless for full‑automation pipelines and headed for human‑in‑the‑loop workflows.
• Built‑in stealth – automatically patches navigator.webdriver, spoofing User‑Agent and other flags.
• Session persistence – cookies and local–storage survive restarts; useful for multi‑step logins.
• Token‑efficient output – offers /text (~800 tokens) and ?filter=interactive (~3 600 tokens) snapshot modes, cutting cost when feeding LLMs.

The result is a browser tool that feels like an LLM plugin: quick to start, easy to use, and highly configurable.

Why Pinchtab beats the usual suspects

When you only need to read a page or click a button, Pinchtab’s text or interactive snapshot is 3–10× cheaper in tokens than a full screenshot with a vision model, translating into orders‑of‑magnitude savings for large‑scale scraping or monitoring.

Getting Started

1. Install

# From source
$ go install github.com/pinchtab/pinchtab@latest

# Or Docker (easiest)
$ docker run -d -p 9867:9867 --security-opt seccomp=unconfined pinchtab/pinchtab

The binary listens on port 9867 by default. Override with BRIDGE_PORT=9870 ./pinchtab.

2. Basic curl usage

# Check health
$ curl http://localhost:9867/health

# Read a page
$ curl http://localhost:9867/text?tabId=1

# Click a button by ref (IDs from snapshot)
$ curl -X POST http://localhost:9867/action \
  -d '{"kind":"click","ref":"e5"}'

All endpoints return clean JSON. See the API section below for details on query parameters and advanced options.

3. Headed Mode (human + agent)

$ BRIDGE_HEADLESS=false ./pinchtab

Open a browser window, log in, solve CAPTCHA, then from your agent use the same profile’s API (e.g. http://localhost:9869). Profiles live in ~/.pinchtab/profiles/<name>/ and persist across restarts.

4. Using the Dashboard

$ pinchtab dashboard
# open http://localhost:9867/dashboard in a browser
# create/import profiles, launch headed instances, stop them

The dashboard offers a simple UI for managing multiple profiles and instances.

Core API Overview

Snapshot query parameters

• filter=interactive – includes only buttons, links, inputs, reducing size.
• format=text – plain text tree, ~40–60 % fewer tokens than JSON.
• diff=true – returns only delta from the last snapshot.
• noAnimations=true – disables CSS animations for deterministic output.

Text query parameters

• mode=raw – raw inner‑text, otherwise removes ads/navigation via readability.

Advanced Features

Stealth Mode

Pinchtab offers two stealth levels: light (basic flags) and full (canvas/WebGL/font spoofing). Enable with BRIDGE_STEALTH=full. This is crucial when automating sites with strong bot detection.

Session Persistence

By default, Pinchtab writes cookies, local storage, and even open tabs into ~/.pinchtab. You can point the tool to a custom directory with BRIDGE_PROFILE=/my/profile. In headless mode you can also inject cookies via POST /cookies.

Image & Media Blocking

Set BRIDGE_BLOCK_IMAGES=true or BRIDGE_BLOCK_MEDIA=true to reduce bandwidth and speed up snapshots.

Custom Chrome Flags

Pass any Chrome flag with CHROME_FLAGS="--no-sandbox --disable-gpu". This can be handy on CI or limited resources.

Security Considerations

Pinchtab essentially hands an agent direct control over a real browser running your account data. Always:

1. Secure the HTTP endpoint with BRIDGE_TOKEN.
2. Run on a restricted network or behind a firewall.
3. Use throw‑away Chrome profiles for experimental agents.

The binary never sends your data outside your machine unless you do so yourself. Guard ~/.pinchtab as you would your passwords.

Quick Reference: Working with the Dashboard

# Start the dashboard
$ pinchtab dashboard
# In the UI
# 1. Import a profile (click "Import Profile")
# 2. Start a new instance (choose headed or headless)
# 3. Use the returned API URL in your agent

The dashboard also exposes POST /start/{id} and /stop/{id}, enabling programmatic lifecycle management.

Common Use‑Cases

Conclusion

Pinchtab is a pragmatic, open‑source solution that removes the friction of integrating a browser into AI workflows. Its small footprint, HTTP‑first interface, and token‑efficient output make it an ideal companion for next‑generation AI agents that need to read, interact with, and manipulate the web without the overhead of full browser frameworks. Give it a try – the 12 MB binary runs on your laptop, your server, or inside Docker, and the API feels like a new plugin for your favorite LLM.