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:

Command	Description
./dev build	Build the application
./dev dev	Build & run
./dev dashboard	Hot-reload dashboard development (Vite + Go)
./dev run	Run the application
./dev check	All checks (Go + Dashboard + Plugin)
./dev check go	Go checks only
./dev check dashboard	Dashboard checks only
./dev test unit	Go unit tests
./dev test dashboard	Dashboard unit tests
./dev e2e basic	Basic suite (api + cli + infra)
./dev e2e extended	Extended suite (all extended)
./dev e2e smoke	Smoke suite
./dev e2e smoke-docker	Host Docker smoke checks only
./dev e2e test "<name>"	Run a single E2E test by start_test name
./dev all	check + test + e2e (pre-push gate)
./dev binaries	Build the full release binary matrix into dist/
./dev doctor	Setup dev environment

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 all          # check + test + e2e (one-shot pre-push gate)
   # …or individually:
   ./dev check        # Lint + format + typecheck
   ./dev test unit    # Go unit tests
   ./dev e2e basic    # 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 basic (or ./dev all for the full chain)
• 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

File	Purpose
internal/assets/stealth.js	Bot detection evasion (light/medium/full levels)
internal/bridge/bridge.go	Chrome CDP bridge
internal/handlers/*.go	HTTP API endpoints
dashboard/src/	React dashboard source
tests/e2e/scenarios-api/	API E2E tests
tests/e2e/scenarios-cli/	CLI E2E tests

Testing

Unit Tests

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

E2E Tests (requires Docker)

./dev e2e basic                 # Basic suite (api + cli + infra)
./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 extended              # Full extended suite (all extended tests)
./dev e2e smoke-docker          # Host Docker smoke checks 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

# Run a single test by its start_test name (fastest debug loop)
./dev e2e test "humanClick: click input by ref"
./dev e2e test "scroll (down)"
./dev e2e test "low-level mouse"

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

Single-test mode (dev e2e test "<name>")

Use this when iterating on one specific E2E failure. The runner:

1. Greps tests/e2e/scenarios/**/*.sh for start_test "...<name substring>...".
2. Auto-picks the suite (api/cli/infra/plugin) and -extended variant from the matching scenario file's path.
3. Builds fresh images (compose ... up --build) and runs only the matching start_test...end_test block — the scenario preamble (helper sourcing, FIXTURES_URL, etc.) is preserved, every other test in the file is skipped.

Notes:

• The substring is literal (fgrep), so colons/parens/quotes in test names work without escaping.
• If multiple tests match, the runner uses the first and prints the others — pass a longer/more-specific substring to disambiguate.
• Logs stream to the terminal by default (unlike full suites which hide logs); helpful for debugging.
• Implemented by scripts/dev-e2e.sh + E2E_TEST_FILTER plumbing through scripts/e2e.sh and tests/e2e/run.sh.

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

Page	URL	Purpose
Home	/dashboard/	Instance overview
Settings	/dashboard/settings	Configuration
Profiles	/dashboard/profiles	Browser profiles
Tabs	/dashboard/tabs	Active 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) has three levels:

Level	Features	Trade-offs
light	webdriver, CDP markers, plugins, hardware	None — safe
medium	+ userAgentData, chrome.runtime.connect, csi/loadTimes	May affect error monitoring
full	+ WebGL/canvas noise, WebRTC relay	May break WebRTC, canvas apps

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