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

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

• 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

macOS / Linux:

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

npm:

npm install -g pinchtab

Docker:

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

Terminal 1 — Start the server:

pinchtab

Terminal 2 — Control the browser:

# Navigate
pinchtab nav https://pinchtab.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"}'

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.

When an AI agent fetches arbitrary web pages, attackers can embed hidden instructions in the page content that attempt to override the agent's system prompt. PinchTab includes an optional, layered defense against this threat called IDPI (Indirect Prompt Injection defense).

Enable it in your config.json:

{
  "security": {
    "idpi": {
      "enabled": true,
      "allowedDomains": ["github.com", "*.github.com"],
      "strictMode": false,
      "scanContent": true,
      "wrapContent": false,
      "customPatterns": []
    }
  }
}

All fields default to false/empty — existing behaviour is completely unchanged unless you opt in.

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

An SMCP plugin in this repo lets AI agents control PinchTab via the Model Context Protocol (SMCP). One plugin exposes 15 tools (e.g. pinchtab__navigate, pinchtab__snapshot, pinchtab__action). No extra runtime deps (stdlib only). See plugins/README.md for setup (env vars and paths).

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

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

# 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

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.

MIT — Free and open source.

Get started: pinchtab.com/docs