PinchTab

Welcome to PinchTab: browser control for AI agents, scripts, and automation workflows.

What PinchTab is

PinchTab is a standalone HTTP server that gives you direct control over Chrome through a CLI and HTTP API.

PinchTab has two runtimes:

  • pinchtab or pinchtab server: the full server
  • pinchtab bridge: the single-instance bridge runtime

The server is the normal entry point. It manages profiles, instances, routing, security policy, and the dashboard. The bridge is the lightweight per-instance HTTP runtime used behind managed child instances.

The basic model is:

  • start the server
  • start or attach instances
  • operate on tabs

Main usage patterns

Start pinchtab and leave it running:

  • use it as a browser for agents
  • use it as a local automation endpoint
  • attach an existing debug browser when needed

Minimal working flow

1. Start the server

terminal 
pinchtab
pinchtab

2. Start an instance

terminal 
pinchtab instance start
curl -X POST http://localhost:9867/instances/start \  -H "Content-Type: application/json" \  -d '{"mode":"headless"}'
Response 
{
  "id": "inst_0a89a5bb",
  "profileId": "prof_278be873",
  "profileName": "instance-1741400000000000000",
  "port": "9868",
  "headless": true,
  "status": "starting"
}

3. Navigate

terminal 
pinchtab nav https://pinchtab.com
curl -s -X POST http://localhost:9867/navigate \  -H "Content-Type: application/json" \  -d '{"url":"https://pinchtab.com"}' | jq .
Response 
{
  "tabId": "CDP_TARGET_ID",
  "title": "PinchTab",
  "url": "https://pinchtab.com"
}

4. Inspect interactive elements

terminal 
pinchtab snap -i -c
curl -s "http://localhost:9867/snapshot?filter=interactive" | jq .
Response 
{
  "nodes": [
    {
      "ref": "e0",
      "role": "link",
      "name": "Docs"
    },
    {
      "ref": "e1",
      "role": "button",
      "name": "Get started"
    }
  ]
}

5. Click by ref

terminal 
pinchtab click e1
curl -s -X POST http://localhost:9867/action \  -H "Content-Type: application/json" \  -d '{"kind":"click","ref":"e1"}' | jq .
Response 
{
  "success": true,
  "result": {
    "clicked": true
  }
}

Characteristics

  • Server-first: the main process is the control-plane server
  • Bridge-backed instances: managed instances run behind isolated bridge runtimes
  • Tab-oriented: interaction happens at the tab level
  • Stateful: profiles persist cookies and browser state
  • Token-efficient: snapshot and text endpoints are cheaper than screenshot-driven workflows
  • Flexible: headless, headed, profile-backed, or attached Chrome
  • Controlled: health, metrics, auth, and tab locking are built into the system

Common features

  • Accessibility-tree snapshots with e0, e1, and similar refs
  • Text extraction
  • Direct actions such as click, type, fill, press, focus, hover, select, and scroll
  • Screenshots and PDF export
  • Multi-instance orchestration
  • External Chrome attach
  • Optional JavaScript evaluation

Support

License

MIT