pinchtab
High-performance browser automation bridge and multi-instance orchestrator with advanced stealth injection and real-time dashboard.
Safety scan
A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.
Badge for your README
Markdown
[](/listings/pinchtab-pinchtab)HTML
<a href="/listings/pinchtab-pinchtab"><img src="/api/listings/pinchtab-pinchtab/badge.svg" alt="findsafeskills safety rating" /></a>Install
Install instructions from the README
As written by the repo's author. findsafeskills has not verified these steps.
These steps run a script from the network that findsafeskills does not scan.
Installation
**macOS / Linux:**
curl -fsSL https://pinchtab.com/install.sh | bash
**Homebrew (macOS / Linux):**
brew install pinchtab/tap/pinchtab
**npm:**
npm install -g pinchtab
Agent skill
The npm package ships the `pinchtab` agent skill and copies it into every agent home it detects (`~/.claude/skills`, `~/.cursor/skills`, `~/.windsurf/skills`, `~/.codex/skills`, OpenClaw) on install and upgrade, printing what it wrote. The shipped copy carries the release version and a content hash in its frontmatter, so a stale or hand-edited copy is detectable without a source checkout:
pinchtab skill status # each detected copy vs the bundled skill; exit 1 if any is stale pinchtab skill update # install or refresh; an edited copy is kept and reported pinchtab skill update --force # replace an edited copy
Inside a checkout, `scripts/install-skills.sh` symlinks the repo skills instead so edits are live; the sync never writes through a symlink.
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`:
# 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:**
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:
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:**
pinchtab nav https://pinchtab.com --snap
**Or start the server explicitly when you want foreground logs:**
pinchtab server
**Recommended for daily local use — install the daemon once:**
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:**
# 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 (every request needs the server token):
export PINCHTAB_TOKEN=$(pinchtab config token --stdout)
# Create a profile first (returns profile id)
PROF=$(curl -s -X POST http://localhost:9867/profiles \
-H "Authorization: Bearer $PINCHTAB_TOKEN" \
-H "Content-Type: application/json" \
-d '{"name":"work"}' | jq -r '.id')What was scanned
The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.
README.md · README · 475 lines · 2 findings marked
View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)
- <p align="center">
- <img src="assets/pinchtab-headless.png" alt="PinchTab" width="200"/>
- </p>
- <p align="center">
- <strong>PinchTab</strong><br/>
- <strong>Browser control for AI agents</strong><br/>
- Small Go binary • HTTP API • Token-efficient
- </p>
- <table align="center">
- <tr>
- <td align="center" valign="middle">
- <a href="https://pinchtab.com/docs"><img src="assets/docs-no-background-256.png" alt="Full Documentation" width="92"/></a>
- </td>
- <td align="left" valign="middle">
- <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><br/>
- <a href="https://github.com/pinchtab/pinchtab/actions/workflows/ci-go.yml"><img src="https://img.shields.io/github/actions/workflow/status/pinchtab/pinchtab/ci-go.yml?branch=main&style=flat-square&label=Go%20CI" alt="Go CI"/></a><br/>
- <img src="https://img.shields.io/badge/Go-1.26+-00ADD8?style=flat-square&logo=go&logoColor=white" alt="Go 1.26+"/><br/>
- <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-blue?style=flat-square" alt="License"/></a>
- </td>
- </tr>
- </table>
- ---
- ## 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
- Note: Pipes a downloaded script directly into a shell (curl | sh / wget | bash)
- Line 35 on GitHub
- # 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
- Running bare `pinchtab` runs the security setup on first use, then prints server status, the security posture, and suggested next steps:
- `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.
- ### Site audits and visual comparison
- PinchTab can audit whole sites at the browser level — screenshots, console
- errors, broken assets, accessibility score, Core Web Vitals, and security
- findings — and compare two site versions visually before a release:
- ```bash
- pinchtab audit https://example.com --output-dir ./audit # report.json + screenshots/
- pinchtab audit https://example.com/sitemap.xml --sitemap --sample-size 2 --output-dir ./audit
- pinchtab compare https://example.com https://staging.example.com --fail-on-diff # CI gate
- ```
- See [docs/audit.md](docs/audit.md) for the full command reference, report
- anatomy, and CI examples.
- ### 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 bare `pinchtab` for first-run setup or a status overview.
- Agent plugins (binary still installed separately):
- ```bash
- # Grok Build, after listing in the official xAI marketplace
- grok plugin install pinchtab --trust
- # OpenClaw
- openclaw plugins install @pinchtab/pinchtab
- ```
- Grok users can install from the PinchTab repository marketplace or directly from GitHub. See the [Grok plugin install and usage guide](plugins/grok/README.md).
- ### 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** — single ~30MB binary; drives a locally installed Chrome or Chromium
- - **Accessibility-first** — Element refs that denote a DOM node, not a row: the same `e5` survives a change of filter, selector or depth (filtered views are sparse), and expires only on navigation to a new document
- - **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
- Note: Pipes a downloaded script directly into a shell (curl | sh / wget | bash)
- Line 201 on GitHub
- ```
- **Homebrew (macOS / Linux):**
- ```bash
- brew install pinchtab/tap/pinchtab
- ```
- **npm:**
- ```bash
- npm install -g pinchtab
- ```
- ### Agent skill
- The npm package ships the `pinchtab` agent skill and copies it into every agent home it detects (`~/.claude/skills`, `~/.cursor/skills`, `~/.windsurf/skills`, `~/.codex/skills`, OpenClaw) on install and upgrade, printing what it wrote. The shipped copy carries the release version and a content hash in its frontmatter, so a stale or hand-edited copy is detectable without a source checkout:
- ```bash
- pinchtab skill status # each detected copy vs the bundled skill; exit 1 if any is stale
- pinchtab skill update # install or refresh; an edited copy is kept and reported
- pinchtab skill update --force # replace an edited copy
- ```
- Inside a checkout, `scripts/install-skills.sh` symlinks the repo skills instead so edits are live; the sync never writes through a symlink.
- ### 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 (every request needs the server token):
- ```bash
- export PINCHTAB_TOKEN=$(pinchtab config token --stdout)
- # Create a profile first (returns profile id)
- PROF=$(curl -s -X POST http://localhost:9867/profiles \
- -H "Authorization: Bearer $PINCHTAB_TOKEN" \
- -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 "Authorization: Bearer $PINCHTAB_TOKEN" \
- -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 "Authorization: Bearer $PINCHTAB_TOKEN" \
- -H "Content-Type: application/json" \
- -d '{"url":"https://pinchtab.com"}' | jq -r '.tabId')
- # Get snapshot
- curl -H "Authorization: Bearer $PINCHTAB_TOKEN" "http://localhost:9867/tabs/$TAB/snapshot?filter=interactive"
- # Click element
- curl -X POST "http://localhost:9867/tabs/$TAB/action" \
- -H "Authorization: Bearer $PINCHTAB_TOKEN" \
- -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 (~30 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 (profiles "alice" and "bob" must already exist — see POST /profiles above)
- curl -s -X POST http://localhost:9867/instances/start \
- -H "Authorization: Bearer $PINCHTAB_TOKEN" \
- -H "Content-Type: application/json" \
- -d '{"profileId":"alice","mode":"headless"}'
- curl -s -X POST http://localhost:9867/instances/start \
- -H "Authorization: Bearer $PINCHTAB_TOKEN" \
- -H "Content-Type: application/json" \
- -d '{"profileId":"bob","mode":"headless"}'
- # Each instance is isolated
- curl -H "Authorization: Bearer $PINCHTAB_TOKEN" http://localhost:9867/instances
- ```
- See [chrome-files.md](docs/implementations/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 diagnostics of your installed PinchTab + browser config (config file loads, browser found and version adequate, a headless launch exposes CDP, request shapes handled; CloakBrowser adds fingerprint-flag and font checks), use:
- ```bash
- pinchtab doctor # human-readable report
- pinchtab doctor --json # machine-readable
- pinchtab doctor --check <name> # run a single check by name
- pinchtab doctor browser <name> # scope to one browser.targets entry
- ```
- ---
- ## License
- MIT — Free and open source.
- ---
- **Get started:** [pinchtab.com/docs](https://pinchtab.com/docs)
Ratings and comments
Sign in to rate this skill.
Sign inFree to use. If it’s helped, pass it on.