pinchtab-helper

What this skill does

# PinchTab Browser Automation

## Core Concepts

- **Profile**: stored browser state on disk (cookies, local storage, history, extensions). Persistent across restarts.
- **Instance**: a running Chrome process backed by a profile. One profile can have at most one active instance.
- **Tab ID**: opaque string returned by API. Never construct them.
- **Shorthand routes** (`pinchtab nav`, `pinchtab eval`, `pinchtab snap`): proxy to the **default/first instance**. Do NOT use when targeting a non-default profile.

## Authentication

The server requires a bearer token (`Authorization: Bearer <token>`) for all protected routes.

- **Where the token lives:** at `.server.token` inside the config file selected by the `PINCHTAB_CONFIG` env var. If `PINCHTAB_CONFIG` is unset, the CLI defaults to `~/.pinchtab/config.json`; the launchd daemon pins it to `~/Library/Application Support/pinchtab/config.json` via its plist. **These can be two different files** — if their tokens drift you get `401 bad_token` from the CLI while the daemon itself is fine. On this machine `PINCHTAB_CONFIG` is exported in fish config to the Library path so the CLI, daemon, and install script all share one config.
- **CLI auth:** shorthand commands (`pinchtab nav`, `pinchtab health`, …) read the token from that config file. Setting `PINCHTAB_TOKEN` in the environment **overrides** the config-file token — handy for a one-off call, but if it's the only thing making the CLI work, you're masking a config split (fix the split instead).
- **Diagnose a 401:** `pinchtab config` prints the exact file + token it's using. Compare `.server.token` across the candidate config files and curl each against the server:

```bash
pinchtab config            # shows the config file + token currently in use
T=$(jq -r .server.token "$HOME/Library/Application Support/pinchtab/config.json")
curl -s -o /dev/null -w '%{http_code}\n' http://localhost:9867/instances -H "Authorization: Bearer $T"
```

- **REST/curl** works with an explicit `Authorization: Bearer <token>` header regardless of `PINCHTAB_CONFIG`.

## Critical: Multi-Instance Routing

**Shorthand CLI commands route to the default instance.** When working with a non-default profile:

1. Get the instance ID: `pinchtab instances`
2. Use instance-scoped CLI: `pinchtab instance navigate <instanceId> <url>`
3. Or use REST API with instance-scoped routes (see API section below)

The `always-on` strategy auto-respawns the default instance — stopping it is futile. To prevent this, change strategy to `explicit` in config:

```bash
pinchtab config set multiInstance.strategy explicit
```

## Authentication & CAPTCHAs

- **HttpOnly cookies** (session tokens) CANNOT be set via `document.cookie` or `pinchtab eval`. They can only be set by actual browser login flows.
- **CAPTCHAs** (Cloudflare Turnstile, reCAPTCHA) cannot be solved by headless browsers. At the first sign of a CAPTCHA, immediately start **headed** mode and ask the user to solve it.
- After user logs in via headed mode, cookies persist in the profile. Do NOT restart the instance — that may lose the session.
- For subsequent runs, start headless from the same profile to reuse persisted cookies.

## Rate Limiting

PinchTab has no built-in rate limiting for target sites. When making multiple API calls:

- Add `await new Promise(r => setTimeout(r, 2000))` between fetch calls in `pinchtab eval` scripts
- For bulk operations, use PinchTab's scheduler with `maxInflight` to control concurrency
- Sites like LeetCode trigger bot detection with rapid automated requests

## CLI Quick Reference

### Server & Config

```bash
pinchtab health                    # Check server health
pinchtab config                    # Show config
pinchtab config set <path> <val>   # Set config value
pinchtab instances                 # List running instances
pinchtab profiles                  # List profiles
```

### Instance Management

```bash
# Start instance (prefer REST API for full control)
curl -s -X POST http://localhost:9867/instances/start \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $TOKEN" \
  -d '{"profileId":"prof_xxx","mode":"headed"}'

# Stop instance
curl -s -X POST http://localhost:9867/instances/<id>/stop \
  -H "Authorization: Bearer $TOKEN"

# Get auth token (from the config file PINCHTAB_CONFIG selects; default below)
jq -r .server.token "${PINCHTAB_CONFIG:-$HOME/.pinchtab/config.json}"
```

### Shorthand Commands (default instance only)

```bash
pinchtab nav <url>                 # Navigate
pinchtab snap                      # Accessibility snapshot
pinchtab snap --interactive        # Interactive elements only
pinchtab snap --compact            # Token-efficient format
pinchtab click <ref>               # Click element (e.g. "e5")
pinchtab click "css:#btn"          # Click by CSS selector
pinchtab click "find:login button" # Click by semantic search
pinchtab fill <ref> <text>         # Fill input field
pinchtab type <ref> <text>         # Type into element
pinchtab press <key>               # Press key (Enter, Tab, Escape)
pinchtab text                      # Extract page text
pinchtab screenshot                # Take screenshot
pinchtab tab                       # List tabs
pinchtab eval '<js>'               # Execute JavaScript
```

### Instance-Scoped Commands (target specific instance)

```bash
pinchtab instance navigate <instanceId> <url>
pinchtab instance logs <instanceId>
pinchtab instance stop <instanceId>
```

## REST API Reference

Base URL: `http://localhost:9867`
Auth: `Authorization: Bearer <token>`

### Profiles

| Method | Endpoint                     | Description                 |
| ------ | ---------------------------- | --------------------------- |
| GET    | `/profiles`                  | List profiles               |
| POST   | `/profiles`                  | Create profile              |
| DELETE | `/profiles/{id}`             | Delete profile              |
| POST   | `/profiles/{nameOrId}/start` | Start instance from profile |
| POST   | `/profiles/{nameOrId}/stop`  | Stop profile's instance     |

### Instances

| Method | Endpoint                    | Description                    |
| ------ | --------------------------- | ------------------------------ |
| GET    | `/instances`                | List running instances         |
| POST   | `/instances/start`          | Start new instance             |
| POST   | `/instances/{id}/stop`      | Stop instance                  |
| POST   | `/instances/{id}/tabs/open` | Open tab in specific instance  |
| GET    | `/instances/{id}/tabs`      | List tabs in specific instance |

### Tabs (cross-instance, by tab ID)

| Method | Endpoint                   | Description                        |
| ------ | -------------------------- | ---------------------------------- |
| POST   | `/tabs/{tabId}/navigate`   | Navigate tab                       |
| GET    | `/tabs/{tabId}/snapshot`   | Get accessibility snapshot         |
| GET    | `/tabs/{tabId}/text`       | Extract page text                  |
| GET    | `/tabs/{tabId}/cookies`    | Get cookies (read-only)            |
| POST   | `/tabs/{tabId}/action`     | Execute action (click, type, etc.) |
| GET    | `/tabs/{tabId}/screenshot` | Capture screenshot                 |
| POST   | `/tabs/{tabId}/close`      | Close tab                          |

### Scheduler (if enabled)

| Method | Endpoint             | Description |
| ------ | -------------------- | ----------- |
| POST   | `/tasks`             | Submit task |
| GET    | `/tasks`             | List tasks  |
| POST   | `/tasks/{id}/cancel` | Cancel task |

## Config Reference

Config location: the file `PINCHTAB_CONFIG` points at — default `~/.pinchtab/config.json`, but the daemon (and this machine's fish config) pin it to `~/Library/Application Support/pinchtab/config.json`. See the Authentication section above.

Key settings:

```json
{
  "server": { "token": "..." },
  "instanceDefaults": {
    "mode": "headed", // or