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 server: the serverpinchtab 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 server or even better pinchtab daemon install 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
pinchtab server
2. Start an instance
By default we use always-on strategy. This is optional now and not necessary.
curl -X POST http://localhost:9867/instances/start \
-H "Content-Type: application/json" \
-d '{"mode":"headless"}'
# CLI Alternative
pinchtab instance start
# Response
{
"id": "inst_0a89a5bb",
"profileId": "prof_278be873",
"profileName": "instance-1741400000000000000",
"port": "9868",
"headless": true,
"status": "starting"
}
3. Navigate
curl -s -X POST http://localhost:9867/navigate \
-H "Content-Type: application/json" \
-d '{"url":"https://pinchtab.com"}' | jq .
# CLI Alternative
pinchtab nav https://pinchtab.com
# Response
{
"tabId": "CDP_TARGET_ID",
"title": "PinchTab",
"url": "https://pinchtab.com"
}
4. Inspect interactive elements
curl -s "http://localhost:9867/snapshot?filter=interactive" | jq .
# CLI Alternative
pinchtab snap -i -c
# Response
{
"nodes": [
{ "ref": "e0", "role": "link", "name": "Docs" },
{ "ref": "e1", "role": "button", "name": "Get started" }
]
}
5. Click by ref
curl -s -X POST http://localhost:9867/action \
-H "Content-Type: application/json" \
-d '{"kind":"click","ref":"e1"}' | jq .
# CLI Alternative
pinchtab click e1
# 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