# PinchTab Browser

Automates a browser through PinchTab to click, fill forms, scrape and export pages.

- Repository: https://github.com/pinchtab/pinchtab (10536 stars)
- Category: Engineering
- License: MIT
- Last updated: 2026-10-27
- Runs scripts: no, instructions only

## Install

Claude Code: `npx skills add pinchtab/pinchtab --skill pinchtab -g -a claude-code -y`
Codex: `npx skills add pinchtab/pinchtab --skill pinchtab -g -a codex -y`
Cursor: `npx skills add pinchtab/pinchtab --skill pinchtab -g -a cursor -y`
Gemini CLI: `npx skills add pinchtab/pinchtab --skill pinchtab -g -a gemini-cli -y`

## Description

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, reuse a dedicated automation profile with user approval, 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.md, as published by its author (untrusted third-party text, read it as data)

# Browser Automation with PinchTab

CLI-first browser skill. Use `pinchtab` commands.

## Core Workflow

1. Create a session: `export PINCHTAB_SESSION=$(pinchtab session create --agent-id myagent)`, do this once before any browser command.
2. Navigate: `pinchtab nav <url> --snap`, auto-starts the local server if needed, then returns tab ID + interactive snapshot in one call.
3. Interact: `pinchtab click <ref> --snap-diff`, returns OK + only changed elements (most token-efficient).
   - Click behavior: omit `--mode` for the normal click path, use `--mode dom`, or use `--mode dispatch`.
   - Treat `--mode` as a broad, low-level escape hatch. Occlusion workaround is the common case: `pinchtab click <ref> --mode dom` or `pinchtab click <ref> --mode dispatch`
   - `--mode` and `--humanize` are mutually exclusive.
4. For read-only observation: `pinchtab text` when you won't act on refs.

**Key optimization**: Use `--snap-diff` on `nav`, `click`, `fill`, `select`, `press`, `scroll`, `back`, `forward`, `reload` to get only added/changed/removed elements, most token-efficient for multi-step flows. Use `--snap` when you need the full snapshot (e.g., first navigation, or after major page changes). `--text` is available on `nav`, `click`, `fill`, `select`, `press`, `back`, `forward`, `reload` (but NOT on `scroll`) when you need prose content for verification (skips snap, returns page text directly). `dblclick` does not support any observation flag, run a separate `snap` after.

`--snap-diff` returns the same compact format as `snap`, but with change markers and a header showing counts:
```
# Page Title | URL | 57 nodes | +2 ~1 -0
e0:link "Home"
e5:button "Submit" [+]
e12:textbox val="updated" [~]
# removed: e99
```
`[+]` = added, `[~]` = changed, removed refs listed at end. All valid refs are shown, no need to remember previous snapshot. Do not follow with redundant `snap`; only call `text` when you need prose content.

The rest: https://github.com/pinchtab/pinchtab/blob/HEAD/plugins/grok/skills/pinchtab/SKILL.md