# pinchtab **Repository Path**: workingbird/pinchtab ## Basic Information - **Project Name**: pinchtab - **Description**: No description available - **Primary Language**: Unknown - **License**: MIT - **Default Branch**: main - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 0 - **Forks**: 0 - **Created**: 2026-06-30 - **Last Updated**: 2026-06-30 ## Categories & Tags **Categories**: Uncategorized **Tags**: None ## README

PinchTab

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

Full Documentation Release
Go CI
Go 1.25+
License
--- ## What is PinchTab? PinchTab is a **standalone HTTP server** that gives AI agents direct control over Chrome. For day-to-day local use, the server is typically installed as a user-level daemon, allowing agent tools to reuse the same browser control plane running in the background. ```bash curl -fsSL https://pinchtab.com/install.sh | bash # or pinchtab daemon install ``` This installs the control-plane server and starts a default headless Chrome instance, ready to accept requests from agents or manual API calls. PinchTab is designed first for local, single-user control on a machine you manage. Remote and distributed layouts are supported, but they are advanced operator-managed deployments. If you bind beyond loopback, publish ports, or attach remote bridges, you are responsible for tokens, network boundaries, TLS or reverse proxying, and which endpoint families you expose. If you run PinchTab on a different machine, do it only when you understand the security model. Keep it on a private or otherwise closed network, avoid exposing it directly to the public internet, and keep high-risk endpoint families disabled unless you explicitly need them. If you do enable them, lock them down so only the systems that need them can reach them. > [!WARNING] > The dashboard, HTTP API, MCP server, and remote CLI integrations are privileged operator control surfaces. They are not designed for untrusted users, multi-tenant exposure, or direct public-internet access. If you are unsure how to secure a non-local deployment, review [docs/guides/security.md](docs/guides/security.md) and use the private security contact path in [SECURITY.md](SECURITY.md) before exposing the service. If you prefer not to run a daemon, or if you're on Windows, you can instead run: `pinchtab server` — runs the control-plane server directly `pinchtab bridge` — runs a single browser instance as a lightweight runtime PinchTab also provides a CLI with an interactive entry point for local setup and common tasks: `pinchtab` ## Security PinchTab defaults to a **local-first security posture**: - `server.bind = 127.0.0.1` - dashboard session cookies are `Secure` only when the dashboard is actually served over HTTPS - sensitive endpoint families are disabled by default - `attach` is disabled by default - IDPI is enabled with a **local-only website allowlist** If you intentionally access the dashboard over plain HTTP on a non-loopback address, PinchTab now warns in the UI that the session is running without transport encryption. Prefer HTTPS or localhost when possible. If you force `server.cookieSecure = true`, dashboard login requires HTTPS and will fail explicitly on plain HTTP instead of looping silently. > [!CAUTION] > By default, IDPI restricts browsing to **locally hosted websites only**. > This prevents agents from navigating the public internet until you explicitly allow it. > The restriction exists to make the security implications of browser automation clear before enabling wider access. > > Expanding browsing to non-local or non-trusted websites is a security-reducing choice. Hostile pages can still increase browser attack surface and interact badly with enabled automation features even when PinchTab's content defenses are on. See the full guide: [docs/guides/security.md](docs/guides/security.md) Remote, container, and distributed setups are possible, but PinchTab is not positioned as a turnkey internet-facing browser service. Treat any non-local deployment as an advanced setup that you must secure explicitly. ## What can you use it for ### Headless navigation With the daemon installed and an agent skill configured, an agent can execute tasks like: ``` "What are the main news about aliens on news.com?" ``` PinchTab exposes browser tools that allow agents to navigate pages, extract structured content, and interact with the DOM without wasting tokens on raw HTML or images. ### Headed navigation In addition to headless automation, PinchTab supports headed Chrome profiles. You can create profiles configured with authentication, cookies, extensions, or specific environments. Each profile can have a name and description. For example, an agent request like: ``` "Log into my work profile and download the weekly report" ``` can automatically select the appropriate profile and perform the action. ### Local container isolation If you prefer stronger isolation, PinchTab can run inside Docker. This allows agents to control browsers in a sandboxed environment, reducing risk when running automation tasks locally. ### Distributed automation PinchTab can manage multiple Chrome instances (headless or headed) across containers or remote machines. Typical use cases include: - QA automation - testing environments - distributed browsing tasks - development tooling You can connect to multiple PinchTab servers, or attach to Chrome instances running in remote debug mode. ## Process Model PinchTab is server-first: 1. install the daemon or run `pinchtab server` for the full control plane 2. let the server manage profiles and instances 3. let each managed instance run behind a lightweight `pinchtab bridge` runtime In practice: - Server — the main product entry point and control plane - Bridge — the runtime that manages a single browser instance - Attach — an advanced mode for registering externally managed Chrome instances ### Primary Usage The primary user journey is: 1. install Pinchtab 2. install and start the daemon with `pinchtab daemon install` 3. point your agent or tool at `http://localhost:9867` 4. let PinchTab act as your local browser service That is the default “replace the browser runtime” scenario. Most users should not need to think about `pinchtab bridge` directly, and only need `pinchtab` when they want the local interactive menu. ### 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** — ~15MB binary, no external dependencies - **Accessibility-first** — Stable element refs instead of fragile coordinates - **ARM64-optimized** — First-class Raspberry Pi support with automatic Chromium detection - **CloakBrowser support** — Optional drop-in provider for sites that fingerprint stock Chromium. PinchTab launches a user-supplied CloakBrowser binary; no CloakBrowser is bundled in released artifacts. See [docs/guides/cloakbrowser.md](docs/guides/cloakbrowser.md). --- ## Quick Start ### Installation **macOS / Linux:** ```bash curl -fsSL https://pinchtab.com/install.sh | bash ``` **Homebrew (macOS / Linux):** ```bash brew install pinchtab/tap/pinchtab ``` **npm:** ```bash npm install -g pinchtab ``` ### Platform Support PinchTab's primary tested operator workflow is local macOS and Linux. Windows binaries are published, but Windows support is currently limited and best-effort because the project does not have the same level of automated and manual coverage there. On Windows, prefer running `pinchtab server` or `pinchtab bridge` directly instead of relying on the daemon workflow. On **macOS**, prefer a dedicated automation browser (Google Chrome for Testing or Chromium) over your daily Google Chrome. Driving your primary Chrome headless can prevent it from opening a normal window while PinchTab is running. PinchTab now prefers a dedicated browser automatically, and `pinchtab doctor browsers` warns if automation would fall back to your primary Chrome — install Chrome for Testing or set `browser.binary` to a separate build. See [docs/reference/config.md](docs/reference/config.md). ### Shell Completion Generate and install shell completions after `pinchtab` is on your `PATH`: ```bash # Generate and install zsh completions pinchtab completion zsh > "${fpath[1]}/_pinchtab" # Generate bash completions pinchtab completion bash > /etc/bash_completion.d/pinchtab # Generate fish completions pinchtab completion fish > ~/.config/fish/completions/pinchtab.fish ``` **Docker:** ```bash docker run -d \ --name pinchtab \ -p 127.0.0.1:9867:9867 \ -v pinchtab-data:/data \ --shm-size=2g \ pinchtab/pinchtab ``` The bundled container persists its managed config at `/data/.config/pinchtab/config.json`. If you want to supply your own config file instead, mount it and point `PINCHTAB_CONFIG` at it: ```bash docker run -d \ --name pinchtab \ -p 127.0.0.1:9867:9867 \ -e PINCHTAB_CONFIG=/config/config.json \ -v "$PWD/config.json:/config/config.json:ro" \ -v pinchtab-data:/data \ --shm-size=2g \ pinchtab/pinchtab ``` ### Use It **First useful command — auto-starts the local server if needed:** ```bash pinchtab nav https://pinchtab.com --snap ``` **Or start the server explicitly when you want foreground logs:** ```bash pinchtab server ``` **Recommended for daily local use — install the daemon once:** ```bash pinchtab daemon install pinchtab daemon ``` That keeps PinchTab running in the background so your agent tools can reuse it without an open terminal. **Terminal 2 — Control the browser:** ```bash # Navigate; starts the server automatically if needed 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: ```bash # Create a profile first (returns profile id) PROF=$(curl -s -X POST http://localhost:9867/profiles \ -H "Content-Type: application/json" \ -d '{"name":"work"}' | jq -r '.id') # Start an instance for that profile (returns instance id) INST=$(curl -s -X POST http://localhost:9867/instances/start \ -H "Content-Type: application/json" \ -d "{\"profileId\":\"$PROF\",\"mode\":\"headless\"}" | jq -r '.id') # Open a tab in that instance TAB=$(curl -s -X POST http://localhost:9867/instances/$INST/tabs/open \ -H "Content-Type: application/json" \ -d '{"url":"https://pinchtab.com"}' | jq -r '.tabId') # Get snapshot curl "http://localhost:9867/tabs/$TAB/snapshot?filter=interactive" # Click element curl -X POST "http://localhost:9867/tabs/$TAB/action" \ -H "Content-Type: application/json" \ -d '{"kind":"click","ref":"e5"}' ``` --- ## Core Concepts **Server** — The main PinchTab process. It manages profiles, instances, routing, and the dashboard. **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. **Bridge** — The single-instance runtime behind a managed instance. Usually spawned by the server, not started manually. Read more in the [Core Concepts](https://pinchtab.com/docs/core-concepts) guide. --- ## Why PinchTab? | Aspect | PinchTab | |--------|----------| | **Tokens performance** | ✅ | | **Headless and Headed** | ✅ | | **Profile** | ✅ | | **Advanced CDP control** | ✅ | | **Persistent sessions** | ✅ | | **Binary size** | ✅ | | **Multi-instance** | ✅ | | **External Chrome attach** | ✅ | ### Benchmark: PinchTab vs agent-browser Measured end-to-end agent-loop token cost (Anthropic API), percentages read as "PinchTab is N% cheaper than agent-browser on this metric": | Scope | Cost cheaper | Fewer requests | Fewer tokens | |---------------------------|-------------:|---------------:|-------------:| | Basic Haiku (10 steps) | **9.5%** | 23.0% | 17.9% | | Extended Haiku (24 steps) | **19.6%** | 31.1% | 26.2% | | Extended Sonnet (24 steps)| **20.3%** | 29.4% | 25.3% | The cost gap widens with workload length (click→snapshot round trips compound) and is roughly model-invariant at extended scope. See the [benchmark summary](./docs/benchmark.md) for an overview, or the [benchmark deep dive](./docs/deep-dive/benchmark.md) for full methodology, per-run tables, and raw logs. --- ## Privacy PinchTab is a fully open-source, local-first tool. No telemetry, no analytics, and no required outbound service dependency. The binary binds to `127.0.0.1` by default. Persistent profiles store browser sessions locally on your machine, similar to how a human reuses their browser. Remote and distributed deployments are available for advanced use cases, but they are explicit operator-managed setups rather than the default posture. The single Go binary (~16 MB) is fully verifiable: build from source at [github.com/pinchtab/pinchtab](https://github.com/pinchtab/pinchtab). --- ## Documentation Full docs at **[pinchtab.com/docs](https://pinchtab.com/docs)** ## Examples ### AI Agent Automation ```bash # 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 ``` ### Data Extraction ```bash # Extract text (token-efficient) pinchtab nav https://pinchtab.com/article pinchtab text # ~800 tokens instead of 10,000 ``` ### Multi-Instance Workflows ```bash # Run multiple instances in parallel curl -s -X POST http://localhost:9867/instances/start \ -H "Content-Type: application/json" \ -d '{"profileId":"alice","mode":"headless"}' curl -s -X POST http://localhost:9867/instances/start \ -H "Content-Type: application/json" \ -d '{"profileId":"bob","mode":"headless"}' # Each instance is isolated curl http://localhost:9867/instances ``` See [chrome-files.md](chrome-files.md) for technical details on how PinchTab manages Chrome user data directories and ensures isolation between parallel instances. --- ## Development Want to contribute? Start with [CONTRIBUTING.md](CONTRIBUTING.md). The full setup and workflow guide lives at [docs/guides/contributing.md](docs/guides/contributing.md). **Quick start:** ```bash git clone https://github.com/pinchtab/pinchtab.git cd pinchtab ./dev doctor # Verifies environment, offers hooks/deps setup ./dev --help # Shows the developer toolkit commands go build ./cmd/pinchtab # Build pinchtab binary ``` For runtime diagnostics against your installed PinchTab + browser config (binary exists, executes, fingerprint flags accepted, CDP reachable), use: ```bash pinchtab doctor # human-readable report pinchtab doctor --json # machine-readable pinchtab doctor --check # run a single check by name pinchtab doctor browser # scope to one browser.targets entry ``` --- ## License MIT — Free and open source. --- **Get started:** [pinchtab.com/docs](https://pinchtab.com/docs)