File size: 3,389 Bytes
6a7089a | 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 | # 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 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 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
```bash
pinchtab server
```
### 2. Start an instance
By default we use always-on strategy. This is optional now and not necessary.
```bash
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
```bash
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
```bash
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
```bash
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
## Support
- [GitHub Issues](https://github.com/pinchtab/pinchtab/issues)
- [GitHub Discussions](https://github.com/pinchtab/pinchtab/discussions)
- [@pinchtabdev](https://x.com/pinchtabdev)
## License
[MIT](https://github.com/pinchtab/pinchtab?tab=MIT-1-ov-file#readme)
|