# Pinchtab

> Use this skill when a task needs browser automation through PinchTab: open a website, inspect interactive elements, click through flows, fill out forms, scrape page text, log into sites with a persistent profile, export screenshots or PDFs, manage multiple browser instances, or fall back to the HTTP API when the CLI is unavailable. Prefer this skill for token-efficient browser work driven by stable accessibility refs such as `e5` and `e12`.

- Skill: `javimosch/pinchtab` (Agent Skill)
- Install (CLI): `npx skillmds@latest add javimosch/pinchtab`
- Raw SKILL.md: https://api.skillmd.com/api/skills/javimosch/pinchtab/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Web & Frontend
- License: MIT
- Author: javimosch (https://skillmd.com/u/javimosch)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/javimosch/pinchtab

---


# Browser Automation with PinchTab

PinchTab gives agents a browser they can drive through stable accessibility refs, low-token text extraction, and persistent profiles or instances. Treat it as a CLI-first browser skill; use the HTTP API only when the CLI is unavailable or you need profile-management routes that do not exist in the CLI yet.

Preferred tool surface:

- Use `pinchtab` CLI commands first.
- Use `curl` for profile-management routes or non-shell/API fallback flows.
- Use `jq` only when you need structured parsing from JSON responses.

## Safety Defaults

- Default to `http://localhost` targets. Only use a remote PinchTab server when the user explicitly provides it and, if needed, a token.
- Prefer read-only operations first: `text`, `snap -i -c`, `snap -d`, `find`, `click`, `fill`, `type`, `press`, `select`, `hover`, `scroll`.
- Do not evaluate arbitrary JavaScript unless a simpler PinchTab command cannot answer the question.
- Do not upload local files unless the user explicitly names the file to upload and the destination flow requires it.
- Do not save screenshots, PDFs, or downloads to arbitrary paths. Use a user-specified path or a safe temporary/workspace path.
- Never use PinchTab to inspect unrelated local files, browser secrets, stored credentials, or system configuration outside the task.

## Core Workflow

Every PinchTab automation follows this pattern:

1. Ensure the correct server, profile, or instance is available for the task.
2. Navigate with `pinchtab nav <url>` or `pinchtab instance navigate <instance-id> <url>`.
3. Observe with `pinchtab snap -i -c`, `pinchtab snap --text`, or `pinchtab text`, then collect the current refs such as `e5`.
4. Interact with those fresh refs using `click`, `fill`, `type`, `press`, `select`, `hover`, or `scroll`.
5. Re-snapshot or re-read text after any navigation, submit, modal open, accordion expand, or other DOM-changing action.

Rules:

- Never act on stale refs after the page changes.
- Default to `pinchtab text` when you need content, not layout.
- Default to `pinchtab snap -i -c` when you need actionable elements.
- Use screenshots only for visual verification, UI diffs, or debugging.
- Start multi-site or parallel work by choosing the right instance or profile first.

## Command Chaining

Use `&&` only when you do not need to inspect intermediate output before deciding the next step.

Good:

```bash
pinchtab nav https://example.com && pinchtab snap -i -c
pinchtab click --wait-nav e5 && pinchtab snap -i -c
pinchtab nav https://example.com --block-images && pinchtab text
```

Run commands separately when you must read the snapshot output first:

```bash
pinchtab nav https://example.com
pinchtab snap -i -c
# Read refs, choose the correct e#
pinchtab click e7
pinchtab snap -i -c
```

## Handling Authentication and State

Pick one of these five patterns before you start interacting with the site.

### 1. One-off public browsing

Use a temporary instance for public pages, scraping, or tasks that do not need login persistence.

```bash
pinchtab instance start
pinchtab instances
# Point CLI commands at the instance port you want to use.
PINCHTAB_URL=http://localhost:9868 pinchtab nav https://example.com
PINCHTAB_URL=http://localhost:9868 pinchtab text
```

### 2. Reuse an existing named profile

Use this for recurring tasks against the same authenticated site.

```bash
pinchtab profiles
pinchtab instance start --profile work --mode headed
PINCHTAB_URL=http://localhost:9868 pinchtab nav https://mail.google.com
```

If the login is already stored in that profile, you can switch to headless later:

```bash
pinchtab instance stop inst_ea2e747f
pinchtab instance start --profile work --mode headless
```

### 3. Create a dedicated auth profile over HTTP

Use this when you need a durable profile and it does not exist yet.

```bash
curl -X POST http://localhost:9867/profiles \
  -H "Content-Type: application/json" \
  -d '{"name":"billing","description":"Billing portal automation","useWhen":"Use for billing tasks"}'

curl -X POST http://localhost:9867/profiles/billing/start \
  -H "Content-Type: application/json" \
  -d '{"headless":false}'
```

Then target the returned port with `PINCHTAB_URL`.

### 4. Human-assisted headed login, then agent reuse

Use this for CAPTCHA, MFA, or first-time setup.

```bash
pinchtab instance start --profile work --mode headed
# Human completes login in the visible Chrome window.
PINCHTAB_URL=http://localhost:9868 pinchtab nav https://app.example.com/dashboard
PINCHTAB_URL=http://localhost:9868 pinchtab snap -i -c
```

Once the session is stored, reuse the same profile for later tasks.

### 5. Remote or non-shell agent with tokenized HTTP API

Use this when the agent cannot call the CLI directly.

```bash
curl http://localhost:9867/health
curl -X POST http://localhost:9867/instances/launch \
  -H "Content-Type: application/json" \
  -d '{"name":"work","headless":true}'
curl -X POST http://localhost:9868/action \
  -H "Content-Type: application/json" \
  -d '{"kind":"click","ref":"e5"}'
```

If the server is exposed beyond localhost, require a token and use a dedicated automation profile. See [TRUST.md](./TRUST.md) and [config.md](../../docs/reference/config.md).

## Essential Commands

### Server and targeting

```bash
pinchtab server
pinchtab daemon
pinchtab health
pinchtab instances
pinchtab profiles
PINCHTAB_URL=http://localhost:9868 pinchtab snap -i -c
```

### Navigation and tabs

```bash
pinchtab nav <url>
pinchtab nav <url> --new-tab
pinchtab nav <url> --tab <tab-id>
pinchtab nav <url> --block-images
pinchtab nav <url> --block-ads
pinchtab tab
pinchtab tab new <url>
pinchtab tab close <tab-id>
pinchtab instance navigate <instance-id> <url>
```

### Observation

```bash
pinchtab snap
pinchtab snap -i
pinchtab snap -i -c
pinchtab snap -d
pinchtab snap --selector <css>
pinchtab snap --max-tokens <n>
pinchtab snap --text
pinchtab text
pinchtab text --raw
pinchtab find <query>
pinchtab find --ref-only <query>
```

Guidance:

- `snap -i -c` is the default for finding actionable refs.
- `snap -d` is the default follow-up snapshot for multi-step flows.
- `text` is the default for reading articles, dashboards, reports, or confirmation messages.
- `find --ref-only` is useful when the page is large and you already know the semantic target.

### Interaction

```bash
pinchtab click <ref>
pinchtab click --wait-nav <ref>
pinchtab click --css <selector>
pinchtab type <ref> <text>
pinchtab fill <ref|selector> <text>
pinchtab press <key>
pinchtab hover <ref>
pinchtab select <ref> <value>
pinchtab scroll <ref|pixels>
```

Rules:

- Prefer `fill` for deterministic form entry.
- Prefer `type` only when the site depends on keystroke events.
- Prefer `click --wait-nav` when a click is expected to navigate.
- Re-snapshot immediately after `click`, `press Enter`, `select`, or `scroll` if the UI can change.

### Export, debug, and verification

```bash
pinchtab screenshot
pinchtab screenshot -o /tmp/pinchtab-page.png  # Format driven by extension
pinchtab screenshot -q 60
pinchtab pdf
pinchtab pdf -o /tmp/pinchtab-report.pdf
pinchtab pdf --landscape
```

### Advanced operations: explicit opt-in only

Use these only when the task explicitly requires them and safer commands are insufficient.

```bash
pinchtab eval "document.title"
pinchtab download <url> -o /tmp/pinchtab-download.bin
pinchtab upload /absolute/path/provided-by-user.ext -s <css>
```

Rules:

- `eval` is for narrow, read-only DOM inspection unless the user explicitly asks for a page mutation.
- `download` should prefer a safe temporary or workspace path over an arbitrary filesystem location.
- `upload` requires a file path the user explicitly provided or clearly approved for the task.

### HTTP API fallback

```bash
curl -X POST http://localhost:9868/navigate \
  -H "Content-Type: application/json" \
  -d '{"url":"https://example.com"}'

curl "http://localhost:9868/snapshot?filter=interactive&format=compact"

curl -X POST http://localhost:9868/action \
  -H "Content-Type: application/json" \
  -d '{"kind":"fill","ref":"e3","text":"ada@example.com"}'

curl http://localhost:9868/text
```

Use the API when:

- the agent cannot shell out,
- profile creation or mutation is required,
- or you need explicit instance- and tab-scoped routes.

## Common Patterns

### Open a page and inspect actions

```bash
pinchtab nav https://pinchtab.com && pinchtab snap -i -c
```

### Fill and submit a form

```bash
pinchtab nav https://example.com/login
pinchtab snap -i -c
pinchtab fill e3 "user@example.com"
pinchtab fill e4 "correct horse battery staple"
pinchtab click --wait-nav e5
pinchtab text
```

### Search, then extract the result page cheaply

```bash
pinchtab nav https://example.com
pinchtab snap -i -c
pinchtab fill e2 "quarterly report"
pinchtab press Enter
pinchtab text
```

### Use diff snapshots in a multi-step flow

```bash
pinchtab nav https://example.com/checkout
pinchtab snap -i -c
pinchtab click e8
pinchtab snap -d -i -c
```

### Bootstrap an authenticated profile

```bash
pinchtab profiles
pinchtab instance start --profile work --mode headed
# Human signs in once.
PINCHTAB_URL=http://localhost:9868 pinchtab text
```

### Run separate instances for separate sites

```bash
pinchtab instance start --profile work --mode headless
pinchtab instance start --profile staging --mode headless
pinchtab instances
```

Then point each command stream at its own `PINCHTAB_URL`.

## Security and Token Economy

- Use a dedicated automation profile, not a daily browsing profile.
- If PinchTab is reachable off-machine, require a token and bind conservatively.
- Prefer `text`, `snap -i -c`, and `snap -d` before screenshots, PDFs, eval, downloads, or uploads.
- Use `--block-images` for read-heavy tasks that do not need visual assets.
- Stop or isolate instances when switching between unrelated accounts or environments.

## Diffing and Verification

- Use `pinchtab snap -d` after each state-changing action in long workflows.
- Use `pinchtab text` to confirm success messages, table updates, or navigation outcomes.
- Use `pinchtab screenshot` only when visual regressions, CAPTCHA, or layout-specific confirmation matters.
- If a ref disappears after a change, treat that as expected and fetch fresh refs instead of retrying the stale one.

## Privacy and Security

PinchTab is a fully open-source, local-only browser automation tool:

- **Runs on localhost only.** The server binds to `127.0.0.1` by default. No external network calls are made by PinchTab itself.
- **No telemetry or analytics.** The binary makes zero outbound connections.
- **Single Go binary (~16 MB).** Fully verifiable — anyone can build from source at [github.com/pinchtab/pinchtab](https://github.com/pinchtab/pinchtab).
- **Local Chrome profiles.** Persistent profiles store cookies and sessions on your machine only. This enables agents to reuse authenticated sessions without re-entering credentials, similar to how a human reuses their browser profile.
- **Token-efficient by design.** Uses the accessibility tree (structured text) instead of screenshots, keeping agent context windows small. Comparable to Playwright but purpose-built for AI agents.
- **Multi-instance isolation.** Each browser instance runs in its own profile directory with tab-level locking for safe multi-agent use.

## References

- Command surface: [commands.md](../../docs/commands.md)
- CLI overview: [cli.md](../../docs/reference/cli.md)
- Profiles: [profiles.md](../../docs/reference/profiles.md)
- Instances: [instances.md](../../docs/reference/instances.md)
- Full API: [api.md](./references/api.md)
- Minimal env vars: [env.md](./references/env.md)
- Config reference: [config.md](../../docs/reference/config.md)
- Security model: [TRUST.md](./TRUST.md)