High-performance browser automation bridge and multi-instance orchestrator with advanced stealth injection and real-time dashboard.
docs: slim down README - focus on essentials, link to official docs at pinchtab.com/docs; exclude root markdown files from linting
Marioe352ba90f4b4
diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yamlindex 03c393fd..9548a12a 100644--- a/.pre-commit-config.yaml+++ b/.pre-commit-config.yaml@@ -17,9 +17,14 @@ repos:hooks:- id: markdownlintargs: ['--config', '.markdownlint.json']- # Exclude test files and auto-generated docs+ # Exclude test files, auto-generated docs, and repo rootexclude: |(?x)^(tests/.*\.md|- \.github/.*\.md+ \.github/.*\.md|+ README\.md|+ CONTRIBUTING\.md|+ CODE_OF_CONDUCT\.md|+ SECURITY\.md|+ RELEASE\.md)$diff --git a/README.md b/README.mdindex 3b8512e5..36f4af02 100644--- a/README.md+++ b/README.md@@ -1,603 +1,179 @@<p align="center">- <img src="assets/pinchtab-headless.png" alt="pinchtab" width="200"/>+ <img src="assets/pinchtab-headless.png" alt="PinchTab" width="200"/></p><p align="center"><strong>Browser control for AI agents.</strong><br/>- 12MB Go binary. Zero config. Accessibility-first.<br/><br/>- π¦ <em>PINCH! PINCH!</em>+ 12MB Go binary β’ HTTP API β’ Token-efficient+</p>++<p align="center">+ <a href="https://pinchtab.com/docs"><strong>π Full Documentation</strong></a>+ β’+ <a href="https://github.com/pinchtab/pinchtab/releases/latest">Latest Release</a></p><p align="center"><a href="https://github.com/pinchtab/pinchtab/releases/latest"><img src="https://img.shields.io/github/v/release/pinchtab/pinchtab?style=flat-square&color=FFD700" alt="Release"/></a>- <a href="https://github.com/pinchtab/pinchtab/actions/workflows/ci.yml"><img src="https://img.shields.io/github/actions/workflow/status/pinchtab/pinchtab/ci.yml?branch=main&style=flat-square&label=CI" alt="CI"/></a>+ <a href="https://github.com/pinchtab/pinchtab/actions/workflows/go-verify.yml"><img src="https://img.shields.io/github/actions/workflow/status/pinchtab/pinchtab/go-verify.yml?branch=main&style=flat-square&label=Build" alt="Build"/></a><img src="https://img.shields.io/badge/Go-1.25+-00ADD8?style=flat-square&logo=go&logoColor=white" alt="Go 1.25+"/>- <a href="https://github.com/pinchtab/pinchtab/blob/main/LICENSE"><img src="https://img.shields.io/github/license/pinchtab/pinchtab?style=flat-square&color=888" alt="License"/></a>- <a href="https://github.com/pinchtab/pinchtab/releases"><img src="https://img.shields.io/github/downloads/pinchtab/pinchtab/total?style=flat-square&color=00ff88&label=downloads" alt="Downloads"/></a>- <img src="https://img.shields.io/badge/binary-12MB-FFD700?style=flat-square" alt="12MB"/>- <a href="https://x.com/pinchtabdev"><img src="https://img.shields.io/badge/follow-@pinchtabdev-000?style=flat-square&logo=x&logoColor=white" alt="X/Twitter"/></a>+ <a href="LICENSE"><img src="https://img.shields.io/badge/license-Apache%202.0-blue?style=flat-square" alt="License"/></a></p>----## Why--Most agent browser tools (OpenClaw, Playwright MCP, Browser Use) are tightly coupled β they only work inside their own framework. If you switch agents or want to script something in bash, you're out of luck.+## What is PinchTab?-PinchTab is a standalone HTTP server. Any agent, any language, even `curl`:+PinchTab is a **standalone HTTP server** that gives AI agents direct control over a Chrome browser. Instead of being locked into a specific framework, you can use PinchTab from anywhere β your AI agent, bash scripts, curl, Python, Go, Node.js, or any language.-```bash-# Read a page β 800 tokens instead of 10,000-curl localhost:9867/text?tabId=X--# Click a button by ref from the last snapshot-curl -X POST localhost:9867/action -d '{"kind":"click","ref":"e5"}'-```+### Key Features-| | PinchTab | OpenClaw Browser |-|---|---|---|-| **Tokens per page** | **~800** (`/text`) / ~3,600 (interactive) | ~10,000+ (full snapshot) |-| Interface | HTTP β any agent, any language | Internal only |-| A11y snapshots | β | β |-| Element interaction | β | β |-| Stealth mode | β | β |-| Session persistence | β | β |-| Self-contained binary | β 12MB | β |+- **HTTP API** β Works with any agent, language, or tool+- **Token-efficient** β 800 tokens/page with text extraction (5-13x cheaper than screenshots)+- **Stateful** β Sessions persist across server restarts+- **Stealth mode** β Bypass bot detection on major sites+- **Multi-instance** β Run multiple parallel Chrome processes with isolated profiles+- **Self-contained** β 12MB binary, no external dependencies+- **Accessibility-first** β Stable element refs (e0, e1...) instead of fragile coordinates-- **5-13x cheaper** than screenshots or full snapshots for read-heavy tasks ([real measurements](#token-efficiency--real-numbers))-- **Plain HTTP API** β not locked to any agent framework-- **Self-contained** β 12MB binary, launches its own Chrome, zero config-- **Stealth mode** β bypasses bot detection on major sites-- **Persistent sessions** β log in once, stays logged in across restarts+----## Installation+## Quick Start-### One-liner (macOS/Linux)+### Installation+**macOS / Linux:**```bashcurl -fsSL https://pinchtab.com/install.sh | bash```-Then:-```bash-pinchtab # Start the server-# In another terminal:-pinchtab nav https://httpbin.org # Navigate-pinchtab snap # Get snapshot-```--**Requirements:**-- Node.js 18+ (for npm install)-- macOS or Linux--**Troubleshooting:**--**Command not found / PATH issue:**-```bash-# npm -g may be in an unusual location-npm config get prefix # Find where global packages go-export PATH="$(npm config get prefix)/bin:$PATH"-```--**Permission denied (EACCES):**-```bash-# Option 1: Use nvm (recommended, fresh Node install)-curl https://github.com/nvm-sh/nvm/raw/master/install.sh | bash-nvm install node-npm install -g pinchtab--# Option 2: User prefix (no sudo)-npm install -g --prefix ~/.local pinchtab-export PATH="$HOME/.local/bin:$PATH" # Add to ~/.bashrc or ~/.zshrc--# Option 3: Change npm prefix globally-mkdir ~/.npm-global && npm config set prefix '~/.npm-global'-export PATH=~/.npm-global/bin:$PATH # Add to ~/.bashrc or ~/.zshrc-```--### npm (manual)--```bash-npm install -g pinchtab-pinchtab --version-```--## Quick Start--### CLI Quick Mode (NEW - Beginner Friendly)-+**npm:**```bash-# Installnpm install -g pinchtab--# One terminal:-pinchtab # Start server (keep running)--# Another terminal:-pinchtab quick https://example.com # Navigate + analyze page automatically-```--The `quick` command combines navigation and page analysis, showing you clickable elements and suggesting next actions.--### Docker (easiest)--```bash-docker run -d -p 9867:9867 --security-opt seccomp=unconfined pinchtab/pinchtab-curl http://localhost:9867/health-```--### With your AI agent--> Install PinchTab and set it up for browser automation.--Your agent can clone, build, and configure PinchTab using the [OpenClaw skill](skill/pinchtab/SKILL.md). Just ask.--### Manual--```bash-# Build-go build -o pinchtab ./cmd/pinchtab--# Headless mode (default) β no window, pure automation (best for token-efficient API flows)-./pinchtab--# Headed mode β visible window for operator-in-the-loop flows-BRIDGE_HEADLESS=false ./pinchtab-```--### Run Modes--| Mode | Command | Notes |-|---|---|---|-| Headless (default) | `./pinchtab` | Launches managed Chrome without UI |-| Headed | `BRIDGE_HEADLESS=false ./pinchtab` | Launches managed Chrome with visible window |-| Dashboard / orchestrator | `./pinchtab dashboard` | Runs control plane only (profiles + instances), no browser in dashboard process |-| Remote CDP | `CDP_URL=http://localhost:9222 ./pinchtab` | Connects to an existing Chrome instead of launching one |--Common runtime options:--```bash-# Custom port-BRIDGE_PORT=9870 ./pinchtab--# Custom profile directory-BRIDGE_PROFILE=/path/to/profile ./pinchtab--# Enable API auth-BRIDGE_TOKEN=your-secret-token ./pinchtab```-### Headless Mode--<img src="assets/pinchtab-headless.png" width="64" alt="PinchTab" />--Chrome runs invisibly in the background β no window, pure API. Best for servers, CI, Docker, and unattended automation. Token savings come from using `/text` and filtered snapshot formats (`/snapshot?filter=interactive&format=compact`) rather than vision/screenshot-heavy flows.-+**Docker:**```bash-./pinchtab+docker run -d -p 9867:9867 pinchtab/pinchtab```-All core API flows are validated in headless mode.--### Remote Chrome via CDP_URL--Instead of launching your own Chrome, connect to an existing instance:+### Use It+**Terminal 1 β Start the server:**```bash-# Start Chrome with debugging enabled (localhost only)-chrome --remote-debugging-port=9222 &--# Get the WebSocket URL-CDP_URL=$(curl http://localhost:9222/json/version | jq -r '.webSocketDebuggerUrl')--# Connect PinchTab to it-export CDP_URL-./pinchtab-```--**Use cases:**-- π€ **Multi-agent resource sharing** β All agents share one Chrome (save 1.3GB per agent)-- π§ͺ **Integration testing** β Multiple test scripts use the same browser and session-- π³ **Docker/containers** β Chrome in one container, PinchTab in another--**β οΈ Security:** Chrome's DevTools Protocol has no authentication. Only expose the CDP port locally or via SSH tunnel. See **[docs/cdp-url-shared-chrome.md#security](docs/cdp-url-shared-chrome.md#security)** for details.--See **[docs/cdp-url-shared-chrome.md](docs/cdp-url-shared-chrome.md)** for detailed setup and use cases.--### Headed Mode (operator-in-the-loop)--<img src="assets/pinchtab-headed.png" width="128" alt="PinchTab headed mode" />--Headed mode is for mixed human + agent workflows:--- Human signs in, solves captchas/2FA, validates page state-- Agent continues through HTTP API against the same profile-- Team can watch automation behavior in real time--See **[docs/headed-mode-guide.md](docs/headed-mode-guide.md)** for use cases of the headed mode.--You can run headed mode in two ways:--1. Single local instance:-```bash-BRIDGE_HEADLESS=false ./pinchtab-```--2. Dashboard-managed profiles (recommended for headed ops):-```bash-./pinchtab dashboard-```-Open `http://localhost:9867/dashboard` and:-- create/import profiles-- launch headed instances per profile/port-- stop profiles gracefully-- open Live popup for a specific running profile-- inspect Info (status, tabs, feed summary, logs)--When a profile is launched, your agent targets that profile instance URL (for example `http://localhost:9868`), not the dashboard URL.--Helper command to resolve a running profile URL from dashboard state:--```bash-pinchtab connect <profile-name>-# -> http://localhost:<profile-port>-```--Recommended human + agent flow:--```bash-# human operator-pinchtab dashboard-# create/import profile, then launch it from the dashboard--# agent process-PINCHTAB_BASE_URL="$(pinchtab connect <profile-name>)"-curl "$PINCHTAB_BASE_URL/health"-```--### First-Time Login--PinchTab keeps persistent profiles. Default single-instance profile: `~/.pinchtab/chrome-profile/`.-Dashboard-managed profiles: `~/.pinchtab/profiles/<profile-name>/`.--In headed mode, log into sites in the visible Chrome window once; cookies and local storage persist across restarts. In headless mode, either copy an existing profile or inject cookies via `POST /cookies`.--## Features--- π² **Accessibility-first** β structured tree with stable refs (`e0`, `e1`...) for click, type, read-- π― **Smart filters** β `?filter=interactive` returns only buttons/links/inputs (~75% fewer tokens)-- π±οΈ **Direct actions** β click, type, fill, press, focus, hover, select, scroll by ref or CSS selector-- π΅οΈ **Stealth mode** β patches `navigator.webdriver`, spoofs UA, hides automation flags-- πΎ **Session persistence** β cookies, auth, tabs survive restarts-- π« **Resource blocking** β Skip downloads for faster, leaner browsing:- - Images: `BRIDGE_BLOCK_IMAGES` or `--block-images`- - Media: `BRIDGE_BLOCK_MEDIA` (images + video + audio)- - Ads/tracking: `BRIDGE_BLOCK_ADS` or `--block-ads` (100+ domains)-- π¬ **Animation disabling** β freeze CSS animations/transitions for consistent snapshots (`BRIDGE_NO_ANIMATIONS` or `?noAnimations=true`)-- π **Text extraction** β readability mode (strips nav/ads) or raw `innerText`-- π **Smart diff** β `?diff=true` returns only changes since last snapshot-- π **Text format** β `?format=text` for indented tree (~40-60% fewer tokens than JSON)-- β‘ **JS evaluation** β escape hatch for anything the API doesn't cover-- πΈ **Screenshots** β JPEG with quality control for visual verification--## Full API--| Method | Endpoint | Description |-|--------|----------|-------------|-| `GET` | `/health` | Connection status |-| `GET` | `/tabs` | List open tabs |-| `GET` | `/snapshot` | Accessibility tree (primary interface) |-| `GET` | `/screenshot` | JPEG screenshot (opt-in) |-| `GET` | `/pdf` | PDF export of current page |-| `GET` | `/text` | Readable page text (readability or raw) |-| `POST` | `/navigate` | Go to URL |-| `POST` | `/action` | Click, type, fill, press, focus, hover, select, scroll |-| `POST` | `/evaluate` | Execute JavaScript |-| `POST` | `/tab` | Open/close tabs |-| `POST` | `/tab/lock` | Lock tab for exclusive agent access |-| `POST` | `/tab/unlock` | Release tab lock |-| `POST` | `/upload` | Set files on `<input type=file>` elements |-| `GET` | `/download` | Download URL using browser session |--### Query Parameters (snapshot)-| Param | Description |-|-------|-------------|-| `tabId` | Target tab (default: first tab) |-| `filter=interactive` | Only buttons, links, inputs |-| `depth=N` | Max tree depth |-| `diff=true` | Return only added/changed/removed nodes since last snapshot |-| `format=text` | Indented plain text instead of JSON (~40-60% fewer tokens) |-| `format=compact` | One-line-per-node format (56-64% fewer tokens than JSON) |-| `selector=CSS` | Scope tree to a CSS selector subtree (e.g. `?selector=main`) |-| `maxTokens=N` | Truncate output to ~N tokens |-| `noAnimations=true` | Disable CSS animations before capture |-| `output=file` | Save snapshot to disk instead of returning |-| `path=/custom/path` | Custom file path (with `output=file`) |--### Query Parameters (screenshot)-| Param | Description |-|-------|-------------|-| `tabId` | Target tab (default: first tab) |-| `quality=N` | JPEG quality (default: 80) |-| `noAnimations=true` | Disable CSS animations before capture |-| `output=file` | Save screenshot to disk instead of returning |--### Query Parameters (pdf)-| Param | Type | Default | Description |-|-------|------|---------|-------------|-| `tabId` | string | first tab | Target tab |-| **Layout** | | | |-| `paperWidth` | float | 8.5 | Paper width in inches |-| `paperHeight` | float | 11.0 | Paper height in inches |-| `landscape` | bool | false | Landscape orientation |-| `marginTop` | float | 0.4 | Top margin in inches |-| `marginBottom` | float | 0.4 | Bottom margin in inches |-| `marginLeft` | float | 0.4 | Left margin in inches |-| `marginRight` | float | 0.4 | Right margin in inches |-| **Content** | | | |-| `scale` | float | 1.0 | Print scale (0.1β2.0) |-| `pageRanges` | string | all | Pages to export (e.g., `1-3,5`) |-| `preferCSSPageSize` | bool | false | Honor CSS @page size |-| **Header/Footer** | | | |-| `displayHeaderFooter` | bool | false | Show header and footer |-| `headerTemplate` | string | β | HTML for header (supports `<span class=date/title/url/pageNumber/totalPages>`) |-| `footerTemplate` | string | β | HTML for footer (same format as header) |-| **Accessibility** | | | |-| `generateTaggedPDF` | bool | false | Generate accessible/tagged PDF |-| `generateDocumentOutline` | bool | false | Embed document outline |-| **Output** | | | |-| `output=file` | string | JSON | Save to disk instead of returning base64 |-| `path=/custom/path` | string | auto | Custom file path (with `output=file`) |-| `raw=true` | bool | false | Return raw PDF bytes instead of JSON |--### Query Parameters (text)-| Param | Description |-|-------|-------------|-| `tabId` | Target tab (default: first tab) |-| `mode=raw` | Raw `innerText` instead of readability extraction |--## CLI--The same `pinchtab` binary doubles as a CLI client with helpful guidance for beginners.--### Quick Start Workflow--```bash-# Terminal 1: Start server (keep running)pinchtab--# Terminal 2: Use CLI commands-pinchtab quick https://example.com # NEW: Navigate + analyze in one command```-### Guided Error Messages--If you forget to start the server:+**Terminal 2 β Control the browser:**```bash-$ pinchtab snap-β PinchTab server is not running on http://localhost:9867--To start the server:- pinchtab # Run in foreground (recommended for beginners)- pinchtab & # Run in background- pinchtab --port 9868 # Use different port-```+# Navigate+pinchtab nav https://example.com-### Smart Suggestions+# Get page structure+pinchtab snap -i -c-After navigation, get helpful next steps:-```bash-$ pinchtab nav https://example.com+# Click an element+pinchtab click e5-π‘ Next steps:- pinchtab snap # See page structure- pinchtab screenshot # Capture visual- pinchtab click <ref> # Click an element- pinchtab pdf -o output.pdf # Save as PDF+# Extract text+pinchtab text```-### Full Command List-+Or use the HTTP API directly:```bash-# Quick start-pinchtab quick <url> # Navigate + analyze page--# Navigation & interaction-pinchtab nav https://httpbin.org/html # Navigate-pinchtab snap -i -c # Snapshot (interactive, compact)-pinchtab click e5 # Click element by ref-pinchtab type e12 hello world # Type into element-pinchtab press Enter # Press key--# Content extraction-pinchtab text # Extract readable text-pinchtab ss -o page.jpg # Screenshot-pinchtab pdf -o page.pdf --landscape # Export PDF (many options available)-pinchtab eval "document.title" # Run JavaScript--# Tab management-pinchtab tabs # List tabs-pinchtab tabs new https://httpbin.org # Open new tab-pinchtab health # Check server-```+# Navigate (returns tabId)+TAB=$(curl -s -X POST http://localhost:9867/instances \+ -d '{"profile":"work"}' | jq -r '.id')-Short aliases: `nav`, `snap`, `ss`, `eval`, `tab`. Config via `PINCHTAB_URL` and `PINCHTAB_TOKEN` env vars. Pipe output with `jq`:+# Get snapshot+curl "http://localhost:9867/instances/$TAB/snapshot?filter=interactive"-```bash-pinchtab text | jq .text-pinchtab snap -i -c | jq '.[] | select(.name | contains("Login"))'+# Click element+curl -X POST "http://localhost:9867/instances/$TAB/action" \+ -d '{"kind":"click","ref":"e5"}'```-Full help: `pinchtab help`+----## Configuration+## Core Concepts-### Core runtime+**Instance** β A running Chrome process. Each instance can have one profile.-| Variable | Default | Description |-|----------|---------|-------------|-| `BRIDGE_BIND` | `127.0.0.1` | Bind address β localhost only by default. Set to `0.0.0.0` for network access |-| `BRIDGE_PORT` | `9867` | HTTP server port |-| `BRIDGE_TOKEN` | *(none)* | Bearer token for auth (recommended when using `BRIDGE_BIND=0.0.0.0`) |-| `BRIDGE_HEADLESS` | `true` | Run Chrome headless (no window) |-| `BRIDGE_PROFILE` | `~/.pinchtab/chrome-profile` | Chrome profile directory |-| `BRIDGE_STATE_DIR` | `~/.pinchtab` | State/session storage |-| `BRIDGE_NO_RESTORE` | `false` | Skip restoring tabs from previous session |-| `BRIDGE_STEALTH` | `light` | Stealth level: `light` (basic) or `full` (canvas/WebGL/font spoofing) |-| `BRIDGE_MAX_TABS` | `20` | Max open tabs (0 = unlimited) |-| `BRIDGE_BLOCK_IMAGES` | `false` | Block image loading |-| `BRIDGE_BLOCK_MEDIA` | `false` | Block all media (images + fonts + CSS + video) |-| `BRIDGE_BLOCK_ADS` | `false` | Block ads and tracking domains (100+ patterns) |-| `BRIDGE_NO_ANIMATIONS` | `false` | Disable CSS animations/transitions globally |-| `BRIDGE_TIMEZONE` | *(none)* | Force browser timezone (IANA tz, e.g. `Europe/Rome`) |-| `BRIDGE_CHROME_VERSION` | `144.0.7559.133` | Chrome version string used by fingerprint rotation profiles |-| `BRIDGE_USER_AGENT` | (none) | Custom User-Agent string; also overrides Sec-Ch-Ua client hints via CDP |-| `BRIDGE_TIMEOUT` | `15` | Action timeout (seconds) |-| `BRIDGE_NAV_TIMEOUT` | `30` | Navigation timeout (seconds) |-| `BRIDGE_CONFIG` | `~/.pinchtab/config.json` | Path to config JSON file |-| `CHROME_BINARY` | *(auto)* | Path to Chrome/Chromium binary |-| `CHROME_FLAGS` | *(none)* | Extra Chrome flags (space-separated) |-| `CDP_URL` | *(none)* | Connect to existing Chrome instead of launching |-| `BRIDGE_NO_DASHBOARD` | `false` | Disable embedded dashboard/orchestrator endpoints on instance processes |+**Profile** β Browser state (cookies, history, local storage). Log in once, stay logged in across restarts.-### Dashboard mode (`./pinchtab dashboard`)+**Tab** β A single webpage. Each instance can have multiple tabs.-| Variable | Default | Description |-|----------|---------|-------------|-| `PINCHTAB_AUTO_LAUNCH` | `false` | Auto-launch a default profile instance at dashboard startup |-| `PINCHTAB_DEFAULT_PROFILE` | `default` | Profile name used by auto-launch |-| `PINCHTAB_DEFAULT_PORT` | `9867` | Port used by auto-launch |-| `PINCHTAB_HEADED` | *(unset)* | If set, auto-launched instance is headed; unset means headless |-| `PINCHTAB_DASHBOARD_URL` | `http://localhost:$BRIDGE_PORT` | CLI helper base URL for `pinchtab connect` |+**Ref** β Stable element reference (e0, e1, e2...) from the accessibility tree. Use refs to click, type, fill inputs.-## Headed Mode: Human + Agent Workflows+Read more in the [Core Concepts](https://pinchtab.com/docs/core-concepts) guide.-Headed mode lets humans and agents share the same browser session. Human logs in, handles 2FA and CAPTCHAs. Agent takes over via HTTP API β same cookies, same session. Profiles persist across restarts, so you log in once and automate forever.+----The dashboard exposes `POST /start/{id}` and `POST /stop/{id}` for easy profile lifecycle management β agents can spin up a profile, do their work, and shut it down with three API calls.+## Why PinchTab?-See **[docs/headed-mode-guide.md](docs/headed-mode-guide.md)** for the full walkthrough with real examples.+| Aspect | PinchTab | OpenClaw Browser | Playwright |+|--------|----------|-----------------|-----------|+| **Interface** | HTTP (any agent) | Framework-locked | Framework-locked |+| **Tokens/page** | ~800 (text) | ~10,000+ | N/A |+| **Stealth mode** | β | β | β |+| **Persistent sessions** | β | β | β |+| **Binary size** | β 12MB | β | β |+| **Multi-instance** | β | β | β |-## Identifying PinchTab Chrome Instances+----Need to distinguish PinchTab's Chrome from your regular browser? Use `CHROME_BINARY` to point at a renamed Chrome copy, `CHROME_FLAGS` to tag instances in `ps`, or rely on the separate profile directory that's already built-in.+## Documentation-See **[docs/identifying-instances.md](docs/identifying-instances.md)** for the full guide with examples.+Full docs at **[pinchtab.com/docs](https://pinchtab.com/docs)**-## Chrome Lifecycle & Orchestration+- **[Getting Started](https://pinchtab.com/docs/getting-started)** β Install and run+- **[Core Concepts](https://pinchtab.com/docs/core-concepts)** β Instances, profiles, tabs+- **[Headless vs Headed](https://pinchtab.com/docs/headless-vs-headed)** β Choose the right mode+- **[API Reference](https://pinchtab.com/docs/api-reference)** β HTTP endpoints+- **[CLI Reference](https://pinchtab.com/docs/cli-reference)** β Command-line commands+- **[Configuration](https://pinchtab.com/docs/configuration)** β Environment variables-PinchTab doesn't just run Chrome β it manages hardened, detection-resistant instances with pre-flight stealth injection, automatic lock file cleanup, retry logic, and per-tab context lifecycle management.+----See **[docs/chrome-lifecycle.md](docs/chrome-lifecycle.md)** for the full deep dive covering allocator strategy, launch flag hardening, instance orchestration, and tab management.+## Examples-## Architecture+### AI Agent Automation+```bash+# Your AI agent can:+pinchtab nav https://example.com+pinchtab snap -i # Get clickable elements+pinchtab click e5 # Click by ref+pinchtab fill e3 "[email protected]" # Fill input+pinchtab press e7 Enter # Submit form```-βββββββββββββββ HTTP :9867 ββββββββββββββββ βββββββββββ-β Any Agent β βββββββββββββββΊ β PinchTab β ββ CDP βββΊ β Chrome β-β (OpenClaw, β snapshot, act, β β β β-β PicoClaw, β navigate, eval β stealth + β β your β-β curl, β β sessions + β β tabs β-β scripts) β β a11y tree β β β-βββββββββββββββ ββββββββββββββββ βββββββββββ-```--See **[docs/pinchtab-architecture.md](docs/pinchtab-architecture.md)**--## Why Not Screenshots?--| | Screenshots | Accessibility Tree |-|---|---|---|-| **Tokens** | ~2,000/image | ~200-500/page |-| **Speed** | Render β encode β transfer | Instant structured data |-| **Reliability** | Vision model guesses coordinates | Deterministic refs |-| **LLM requirement** | Vision model required | Any text LLM works |-| **Cost (10-step task)** | ~$0.06 | ~$0.015 |--Playwright MCP, OpenClaw, and Browser Use all default to accessibility trees for the same reason.--## Token Efficiency β Real Numbers--Measured on a live search results page:--| Method | Size | ~Tokens |-|---|---|---|-| Full a11y snapshot | 42 KB | 10,500 |-| Interactive-only (`?filter=interactive`) | 14 KB | 3,600 |-| Text extraction (`/text`) | 3 KB | 800 |-| Screenshot (vision model) | β | ~2,000 |-For read-heavy tasks (monitoring feeds, scraping search results), `/text` at ~800 tokens per page is **5x cheaper** than a full snapshot and **13x cheaper** than the same page via screenshots.--**Example: 50-page search monitoring task**--| Approach | Tokens | Est. cost |-|---|---|---|-| Screenshots (vision) | ~100,000 | $0.30 |-| Full snapshots | ~525,000 | $0.16 |-| PinchTab `/text` | ~40,000 | $0.01 |-| PinchTab interactive filter | ~180,000 | $0.05 |--Use `/text` when you only need content. Use `?filter=interactive` when you need to act. Use the full snapshot when you need page structure.--## Built With--| Dependency | What it does | License |-|---|---|---|-| [chromedp](https://github.com/chromedp/chromedp) | Chrome DevTools Protocol driver for Go | MIT |-| [cdproto](https://github.com/chromedp/cdproto) | Generated CDP types and commands | MIT |-| [gobwas/ws](https://github.com/gobwas/ws) | Low-level WebSocket (used by chromedp) | MIT |-| [go-json-experiment/json](https://github.com/go-json-experiment/json) | JSON v2 library (used by cdproto) | BSD-3-Clause |--Everything else is Go standard library.--## Requirements--- **Go 1.25+** (build from source) or download a [prebuilt binary](https://github.com/pinchtab/pinchtab/releases)-- **Google Chrome** or Chromium installed--## Install+### Data Extraction```bash-# From source-go install github.com/pinchtab/pinchtab@latest--# Or clone and build-git clone https://github.com/pinchtab/pinchtab.git-cd pinchtab-go build -o pinchtab ./cmd/pinchtab+# Extract text (token-efficient)+pinchtab nav https://example.com/article+pinchtab text # ~800 tokens instead of 10,000```-## Development+### Multi-Instance Workflows```bash-git clone https://github.com/pinchtab/pinchtab.git-cd pinchtab-go build -o pinchtab ./cmd/pinchtab-./pinchtab+# Run multiple instances in parallel+pinchtab instances create --profile=alice --port=9868+pinchtab instances create --profile=bob --port=9869-# Run tests (38 tests)-go test ./...+# Each instance is isolated+curl http://localhost:9868/text?tabId=X # Alice's instance+curl http://localhost:9869/text?tabId=Y # Bob's instance```-## β οΈ Security β Read This--**PinchTab gives AI agents full control of a real browser with your real accounts.**--When you log into sites through PinchTab's Chrome window, those sessions β cookies, tokens, saved passwords β persist in `~/.pinchtab/chrome-profile/`. Any agent with HTTP access to PinchTab can then act as you: read your email, post on your behalf, make purchases, access sensitive data.--**This is by design.** That's what makes it useful. But it means:+----- **You are responsible for what agents do with your accounts.** PinchTab is a tool, not a guardrail. If you give an agent access to your bank and it does something stupid, that's on you.-- **Set `BRIDGE_TOKEN`** β without it, anyone on your network can control your browser. In production, this is non-negotiable.-- **Treat `~/.pinchtab/` as sensitive** β it contains your Chrome profile with all saved sessions and cookies. Guard it like you'd guard your passwords.-- **PinchTab binds to all interfaces by default** β use a firewall or reverse proxy if you're on a shared network.-- **If using `CDP_URL`:** Chrome's DevTools Protocol has no authentication. **Never expose the CDP port to the network.** Only use localhost or SSH tunnels. See [docs/cdp-url-shared-chrome.md#security](docs/cdp-url-shared-chrome.md#security) for details.-- **Start with low-risk accounts.** Don't point an experimental agent at your primary email or bank account on day one. Test with throwaway accounts first.-- **No data leaves your machine** β all processing is local. But the agents you connect might send data wherever they want.+## License-Think of PinchTab like giving someone your unlocked laptop. Powerful if you trust them. Dangerous if you don't.+Apache 2.0 β Free and open source.-## Works with any agent+----PinchTab is built to work seamlessly with [OpenClaw](https://openclaw.ai) β the open-source personal AI assistant. Use PinchTab as your agent's browser backend for faster, cheaper web automation.+**Get started:** [pinchtab.com/docs](https://pinchtab.com/docs)