Hugging Face's logo

Spaces:
AUXteam
/
WitNote
Sleeping

App Files Community
WitNote / README.md
AUXteam's picture
AUXteam
Upload folder using huggingface_hub
6a7089a verified
preview code
|
raw
history blame contribute delete
11.4 kB
metadata 
title: PinchTab
sdk: docker
app_port: 7860

PinchTab

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

Full Documentation Release
Build
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.

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.

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
  • sensitive endpoint families are disabled by default
  • attach is disabled by default
  • IDPI is enabled with a local-only website allowlist

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.

See the full guide: docs/guides/security.md

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

Quick Start

Installation

macOS / Linux:

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

Homebrew (macOS / Linux):

brew install pinchtab/tap/pinchtab

npm:

npm install -g pinchtab

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

Terminal 1 — Start the server:

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
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:

# Create an instance (returns instance id)
INST=$(curl -s -X POST http://localhost:9867/instances/launch \
  -H "Content-Type: application/json" \
  -d '{"name":"work","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 guide.

Why PinchTab?

Aspect PinchTab
Tokens performance ✅
Headless and Headed ✅
Profile ✅
Advanced CDP control ✅
Persistent sessions ✅
Binary size ✅
Multi-instance ✅
External Chrome attach ✅

Privacy

PinchTab is a fully open-source, local-only tool. No telemetry, no analytics, no outbound connections. 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. The single Go binary (~16 MB) is fully verifiable: build from source at github.com/pinchtab/pinchtab.

Documentation

Full docs at pinchtab.com/docs

MCP (SMCP) integration

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).

Examples

AI Agent Automation 

# 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 

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

Multi-Instance Workflows 

# 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 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. The full setup and workflow guide lives at docs/guides/contributing.md.

Quick start:

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

License

MIT — Free and open source.

Get started: pinchtab.com/docs