PinchTab
Browser control for AI agents
12MB Go binary • HTTP API • Token-efficient

---

What is PinchTab?

PinchTab is a standalone HTTP server that gives AI agents direct control over a Chrome browser.

Key Features

• CLI or Curl — Control via command-line or HTTP API
• Token-efficient — 800 tokens/page with text extraction (5-13x cheaper than screenshots)
• Headless or Headed — Run without a window or with visible Chrome
• Multi-instance — Run multiple parallel Chrome processes with isolated profiles
• Self-contained — 12MB binary, no external dependencies
• Accessibility-first — Stable element refs instead of fragile coordinates
• ARM64-optimized — First-class Raspberry Pi support with automatic Chromium detection

---

Quick Start

Installation

macOS / Linux:

curl -fsSL https://pinchtab.com/install.sh | bash

npm:

npm install -g pinchtab

Docker:

docker run -d -p 9867:9867 pinchtab/pinchtab

Use It

Terminal 1 — Start the server:

pinchtab

Terminal 2 — Control the browser:

# Navigate
pinchtab nav https://example.com

# Get page structure
pinchtab snap -i -c

# Click an element
pinchtab click e5

# Extract text
pinchtab text

Or use the HTTP API directly:

# Navigate (returns tabId)
TAB=$(curl -s -X POST http://localhost:9867/instances \
  -d '{"profile":"work"}' | jq -r '.id')

# Get snapshot
curl "http://localhost:9867/instances/$TAB/snapshot?filter=interactive"

# Click element
curl -X POST "http://localhost:9867/instances/$TAB/action" \
  -d '{"kind":"click","ref":"e5"}'

---

Core Concepts

Instance — A running Chrome process. Each instance can have one profile.

Profile — Browser state (cookies, history, local storage). Log in once, stay logged in across restarts.

Tab — A single webpage. Each instance can have multiple tabs.

Read more in the Core Concepts guide.

---

Why PinchTab?

Aspect	PinchTab
Tokens performance	✅
Headless and Headed	✅
Profile	✅
Stealth mode	✅
Persistent sessions	✅
Binary size	✅
Multi-instance	✅
Remote Chrome	✅

---

Documentation

Full docs at pinchtab.com/docs

• Getting Started — Install and run
• Core Concepts — Instances, profiles, tabs
• Headless vs Headed — Choose the right mode
• API Reference — HTTP endpoints
• CLI Reference — Command-line commands
• Configuration — Environment variables

---

Examples

AI Agent Automation

# Your AI agent can:
pinchtab nav https://example.com
pinchtab snap -i  # Get clickable elements
pinchtab click e5 # Click by ref
pinchtab fill e3 "user@example.com"  # Fill input
pinchtab press e7 Enter              # Submit form

Data Extraction

# Extract text (token-efficient)
pinchtab nav https://example.com/article
pinchtab text  # ~800 tokens instead of 10,000

Multi-Instance Workflows

# Run multiple instances in parallel
pinchtab instances create --profile=alice --port=9868
pinchtab instances create --profile=bob --port=9869

# Each instance is isolated
curl http://localhost:9868/text?tabId=X  # Alice's instance
curl http://localhost:9869/text?tabId=Y  # Bob's instance

---

Development

Want to contribute? See DEVELOPMENT.md for setup instructions.

Quick start:

git clone https://github.com/pinchtab/pinchtab.git
cd pinchtab
./doctor.sh                 # Verifies environment, installs hooks/deps
go build ./cmd/pinchtab     # Build pinchtab binary

See CONTRIBUTING.md for contribution guidelines.

---

License

MIT — Free and open source.

---

Get started: pinchtab.com/docs