/pinchtab-opt

name: pinchtab-opt
description: "Run the PinchTab optimization loop (Docker, 3 blind subagents on the runner's HIGH model, 108 steps across 47 groups) against chrome, cloak, ghost-chrome, or all three providers. Pass `setup` (optionally followed by a provider or `all`) to run only the setup test (native binary, single subagent forced to the runner's LOW model) that validates the fresh-install OOTB flow per provider. Use when asked to 'run optimization', 'run the opt loop', 'benchmark the agent', '/pinchtab-opt', '/pinchtab-opt cloak', '/pinchtab-opt ghost-chrome', '/pinchtab-opt setup', '/pinchtab-opt setup all', or 'test pinchtab agent'."

PinchTab Optimization Loop

Two independent modes selected by the argument. They use different runtimes, different models, and answer different questions — only one runs per invocation.

Think of the arg surface as a matrix: **mode × provider**. Model role is fixed by mode (not user-selectable).

| Mode | Providers | Runtime | Model role | Asks | |---|---|---|---|---| | **Optimization** (default) | `chrome` (default), `cloak`, `ghost-chrome`, `all` | Docker, 3 parallel subagents | `HIGH` (default/strong) | how few browser ops does the agent need across 108 steps vs baseline | | **Setup** (`setup` keyword) | `chrome` (default), `cloak`, `ghost-chrome`, `all` | native binary, 1 subagent | `LOW` (small/fast) | can an agent go zero→working from the skill docs alone (OOTB doc-quality gate) |

Model roles

This skill names model tiers abstractly so any runner (Claude, OpenAI, …) can map them at launch time:

• **`LOW`** — small/fast/cheap model. Used by the setup test because a weak model passing is the actual doc-quality signal; a strong model passing is unsurprising.
• **`HIGH`** — the runner's default/strong model. Used by the optimization benchmark because we want the realistic agent performance, not a deliberately handicapped run.

Suggested mappings (pick whatever the runner has available at the time it executes):

| Runner | `LOW` | `HIGH` | |---|---|---| | Claude Code | Haiku (e.g. `claude-haiku-4-5`) | inherit parent (Opus / Sonnet) | | OpenAI Agents | `gpt-*-mini` tier | `gpt-*` flagship tier | | Other | smallest capable model | default/best model |

The thresholds below were calibrated for Claude Haiku 4.5 as `LOW`; if you use a different `LOW`, recalibrate the token / tool-call numbers on the first run.

Argument Parsing

`/pinchtab-opt [setup] [chrome|cloak|ghost-chrome|all]`

Positional args, in order. The first token is either a provider (optimization mode) or the literal `setup` keyword (setup mode); if `setup`, the second token is the provider.

**Optimization mode** (default — no `setup` keyword):

• `/pinchtab-opt` → opt on chrome
• `/pinchtab-opt chrome` → opt on chrome
• `/pinchtab-opt cloak` → opt on CloakBrowser
• `/pinchtab-opt ghost-chrome` → opt on ghost-chrome (Chrome image, ghost-chrome config)
• `/pinchtab-opt all` → opt on chrome, then cloak, then ghost-chrome

**Setup mode** (when first token is `setup`):

• `/pinchtab-opt setup` → setup on chrome (default)
• `/pinchtab-opt setup chrome` → setup on chrome
• `/pinchtab-opt setup cloak` → setup on cloak
• `/pinchtab-opt setup ghost-chrome` → setup on ghost-chrome
• `/pinchtab-opt setup all` → setup on each of the three, in order

Legacy `both` is **removed** (no alias) — use `all` for multi-provider runs. Anything else → print this section and abort.

Path Resolution

All paths are relative to the **project root** (git root):

PROJECT_ROOT=$(git rev-parse --show-toplevel)
TOOLS_DIR="$PROJECT_ROOT/tests/tools"
OPT_DIR="$PROJECT_ROOT/tests/optimization"
SETUP_DIR="$PROJECT_ROOT/tests/optimization-setup"

The optimization subagents must run with `$TOOLS_DIR` as their working directory because `./scripts/pt` and `./scripts/runner` live there. The setup subagent runs with `$PROJECT_ROOT` as its working directory and builds a native binary.

`up.sh` / `down.sh` live in `$OPT_DIR`.

---

Mode: setup (`/pinchtab-opt setup`)

Validate that an AI agent can go from zero to working with PinchTab using only the skill docs — no hand-holding.

Clean slate

The setup test simulates a true first-install OOTB experience. To get there:

1. **Stop any pre-existing server** — first try the recorded PID, then fall back to `pkill -f` for anything spawned outside the PID file's tracking. Killing via PID file is more reliable than `pkill -f` (which can miss processes and won't reap dashboard children). 2. **Stash the user's real `~/.pinchtab/` aside** — so the auto-flow truly creates a config from zero, not on top of an existing profile/activity history that warms Chrome and confuses results. Restored automatically on completion via a trap. 3. **Free port 9867 and remove the stale binary** in the project root.

# 1. Stop any prior server (PID-file first, then pkill fallback)
if [ -f ~/.pinchtab/server.pid ]; then
  prior_pid=$(jq -r '.pid // empty' ~/.pinchtab/server.pid 2>/dev/null)
  [ -n "$prior_pid" ] && kill "$prior_pid" 2>/dev/null
fi
docker compose -f "$TOOLS_DIR/docker-compose.yml" down 2>/dev/null
docker rm -f optimization-pinchtab >/dev/null 2>&1 || true
pkill -f 'pinchtab' 2>/dev/null
pkill -f 'Google Chrome.*pinchtab' 2>/dev/null
lsof -ti:9867 2>/dev/null | xargs kill 2>/dev/null
sleep 2

# 2. Stash the real ~/.pinchtab aside for the duration of the test
PINCHTAB_BACKUP="$HOME/.pinchtab.backup-$(date +%s)"
if [ -d ~/.pinchtab ]; then
  mv ~/.pinchtab "$PINCHTAB_BACKUP"
fi
# Always restore on exit, even on failure or Ctrl-C
trap '
  if [ -d "'"$PINCHTAB_BACKUP"'" ]; then
    rm -rf ~/.pinchtab 2>/dev/null
    mv "'"$PINCHTAB_BACKUP"'" ~/.pinchtab
  fi
' EXIT INT TERM

# 3. Misc state
rm -f ~/.local/state/pinchtab/current-tab-* 2>/dev/null
rm -f "$PROJECT_ROOT/pinchtab" 2>/dev/null
# Defensive: clear any stray *config*.json the agent might leave in a real ~/.pinchtab
# (no-op because we stashed it above — but kept for runs that skip the stash).
find ~/