PinchTab Development

PinchTab is a browser control server for AI agents — Small Go binary with HTTP API.

Project Location

cd ~/dev/pinchtab

Dev Commands

All development commands run via

./dev

./dev build

./dev dev

./dev dashboard

./dev run

./dev check

./dev check go

./dev check dashboard

./dev test unit

./dev test dashboard

./dev e2e pr

./dev e2e release

./dev e2e docker

./dev doctor

Architecture

cmd/pinchtab/     CLI entry point
internal/
  bridge/         Chrome CDP communication
  handlers/       HTTP API handlers
  server/         HTTP server
  dashboard/      Embedded React dashboard
  config/         Configuration
  assets/         Embedded assets (stealth.js)
dashboard/        React dashboard source (Vite + TypeScript)
tests/e2e/        E2E test suites

Workflow: New Feature or Bug Fix

1. Create branch from

   main

   :

   git checkout main && git pull
   git checkout -b feat/my-feature  # or fix/my-bug
   

2. Make changes — follow code patterns in existing files

3. Run checks locally:

   ./dev check        # Lint + format + typecheck
   ./dev test unit    # Go unit tests
   ./dev e2e pr       # E2E tests (Docker required)
   

4. Commit with conventional commits:

   • feat:

     new feature

   • fix:

     bug fix

   • refactor:

     code change without behavior change

   • test:

     adding tests

   • docs:

     documentation

   • chore:

     maintenance

5. Push and create PR

Definition of Done (PR Checklist)

Required — Code Quality

• Error handling explicit — all errors wrapped with

  %w

  , no silent failures
• No regressions — verify stealth, token efficiency, session persistence
• SOLID principles — functions do one thing, testable
• No redundant comments — explain why, not what

Required — Testing

• New/changed functionality has tests
• Docker E2E tests pass locally:

  ./dev e2e pr

• If npm wrapper touched:

  npm pack

  and

  npm install

  work

Required — Documentation

• README.md updated if user-facing changes
• /docs/ updated if API/architecture changed

Required — Review

• PR description explains what + why
• Commits are atomic with good messages

Key Files

internal/assets/stealth.js

internal/bridge/bridge.go

internal/handlers/*.go

dashboard/src/

tests/e2e/scenarios-api/

tests/e2e/scenarios-cli/

Testing

Unit Tests

./dev test unit              # All Go tests
go test ./internal/handlers  # Specific package

E2E Tests (requires Docker)

./dev e2e pr                    # PR suite (api + cli + infra basic tests)
./dev e2e api                   # API basic tests
./dev e2e cli                   # CLI basic tests
./dev e2e infra                 # Infra basic tests
./dev e2e api-extended          # API extended tests (multi-instance)
./dev e2e cli-extended          # CLI extended tests
./dev e2e infra-extended        # Infra extended tests (multi-instance)
./dev e2e release               # Full release suite (all extended tests)
./dev e2e docker                # Docker smoke test only

# Run specific test file(s) with filter (second argument)
./dev e2e api clipboard                # Run only clipboard-basic.sh
./dev e2e api-extended "clipboard|console"  # Run clipboard and console tests
./dev e2e cli browser                  # Run browser-basic.sh in CLI suite

The filter is a regex pattern matched against scenario filenames. Requires Docker daemon running.

Dashboard Tests

./dev test dashboard  # Vitest
cd dashboard && npm test

Dashboard Development

Setup

Start hot-reload development:

./dev dashboard

This runs:

• Backend on

  :9867

• Vite dev server on

  :5173

  with hot-reload
• Dashboard at

  http://localhost:5173/dashboard/

Development Workflow (Use PinchTab to Develop PinchTab)

Do not assume changes worked. Use pinchtab itself to verify changes visually:

1. Start dev mode:

   ./dev dashboard
   

2. Make changes to files in

   dashboard/src/

3. Verify with pinchtab — use the pinchtab skill to inspect the dashboard:

   # Navigate to the page under development
   curl -X POST http://localhost:9867/navigate \
     -d '{"url":"http://localhost:5173/dashboard/settings"}'
   
   # Take a screenshot to verify the change
   curl -X POST http://localhost:9867/screenshot \
     -d '{"path":"/tmp/dashboard-check.png"}'
   
   # Or get a snapshot to inspect elements
   curl -s http://localhost:9867/snapshot | jq .
   

4. Provide evidence — when reporting changes, include:

   • Link to the page:

     http://localhost:5173/dashboard/{page}

   • Screenshot of the result
   • Relevant snapshot data if inspecting specific elements

Example: Verifying a Settings Page Change

# Navigate to settings
curl -X POST http://localhost:9867/navigate \
  -d '{"url":"http://localhost:5173/dashboard/settings"}'

# Screenshot the result
curl -X POST http://localhost:9867/screenshot \
  -d '{"path":"./dashboard-settings.png","fullPage":true}'

# Find specific element
curl -X POST http://localhost:9867/find \
  -d '{"selector":"[data-testid=stealth-level]"}'

Key Dashboard Pages

/dashboard/

/dashboard/settings

/dashboard/profiles

/dashboard/tabs

Dashboard Tech Stack

• React 19 + TypeScript
• Vite (build/dev)
• Tailwind CSS
• Zustand (state)
• Vitest (tests)

Stealth Module

The stealth module (

internal/assets/stealth.js

light

medium

full

Configure in

~/.pinchtab/config.json

{
  "instanceDefaults": {
    "stealthLevel": "medium"
  }
}

Common Tasks

Add new API endpoint

1. Create handler in

   internal/handlers/

2. Register route in

   internal/server/routes.go

3. Add tests in same package
4. Add E2E test in

   tests/e2e/scenarios-api/

Modify stealth behavior

1. Edit

   internal/assets/stealth.js

2. Run

   ./dev build

   (embeds via go:embed)
3. Test with

   ./dev e2e api-fast

   (includes stealth tests)

Update dashboard

1. Run

   ./dev dashboard

   for hot-reload
2. Edit files in

   dashboard/src/

3. Run

   ./dev check dashboard

   before commit