Skip to content

High-performance browser automation bridge and multi-instance orchestrator with advanced stealth injection and real-time dashboard.

feat(dev): add hot-reload dashboard development mode + pinchtab-dev skill (#318)

pinchtabdevb4b8186dce3a
diff --git a/dev b/dev
index 0d5c7e53..2b7ec57a 100755
--- a/dev
+++ b/dev
@@ -19,6 +19,7 @@ NC=$'\033[0m'
COMMANDS=(
"build:πŸ”¨:Build the application"
"dev:πŸš€:Build & run"
+ "dashboard:πŸ”₯:Hot-reload dashboard development"
"run:πŸƒ:Run the application"
"check:πŸ§ͺ:All checks"
"test unit:πŸ”¬:Go unit tests"
@@ -158,6 +159,7 @@ run_command() {
exec bash scripts/e2e.sh "$suite"
;;
"dev") exec bash scripts/dev.sh ;;
+ "dashboard") exec bash scripts/dev-dashboard.sh ;;
"build") exec bash scripts/build.sh ;;
"binary") exec bash scripts/binary.sh ;;
"binary all"|"all") exec bash scripts/binary.sh all ;;
@@ -253,6 +255,7 @@ if [ $# -gt 0 ]; then
if command -v gum &>/dev/null; then pick_with_gum; else pick_with_select; fi
exit 0
;;
+
check)
if [ $# -gt 1 ]; then
run_command "check $2"
diff --git a/scripts/dev-dashboard.sh b/scripts/dev-dashboard.sh
new file mode 100755
index 00000000..6d2fcec1
--- /dev/null
+++ b/scripts/dev-dashboard.sh
@@ -0,0 +1,91 @@
+#!/bin/bash
+# dev-dashboard.sh β€” Run pinchtab + Vite dev server for hot-reload dashboard development
+#
+# This starts:
+# 1. pinchtab backend (Go) on port 9867
+# 2. Vite dev server (React) on port 5173 with proxy to backend
+#
+# Access the dashboard at: http://localhost:5173/dashboard/
+# Changes to dashboard/src/* will hot-reload instantly.
+#
+# Usage: ./scripts/dev-dashboard.sh [pinchtab args...]
+
+set -e
+
+cd "$(dirname "$0")/.."
+
+BOLD=$'\033[1m'
+ACCENT=$'\033[38;2;251;191;36m'
+MUTED=$'\033[38;2;90;100;128m'
+SUCCESS=$'\033[38;2;0;229;204m'
+NC=$'\033[0m'
+
+cleanup() {
+ echo ""
+ echo " ${MUTED}Shutting down...${NC}"
+ kill $BACKEND_PID 2>/dev/null || true
+ kill $VITE_PID 2>/dev/null || true
+ exit 0
+}
+
+trap cleanup SIGINT SIGTERM
+
+echo ""
+echo " ${ACCENT}${BOLD}πŸ”₯ Dashboard Hot-Reload Dev Mode${NC}"
+echo ""
+
+# Build Go binary (without embedded dashboard - it won't be used)
+echo " ${MUTED}Building Go backend...${NC}"
+go build -o pinchtab ./cmd/pinchtab
+
+# Start backend
+echo " ${MUTED}Starting pinchtab backend on :9867...${NC}"
+./pinchtab server "$@" &
+BACKEND_PID=$!
+
+# Wait for backend to be ready
+echo " ${MUTED}Waiting for backend...${NC}"
+for i in {1..30}; do
+ if curl -s http://localhost:9867/health >/dev/null 2>&1; then
+ break
+ fi
+ sleep 0.5
+done
+
+if ! curl -s http://localhost:9867/health >/dev/null 2>&1; then
+ echo " ${BOLD}Backend failed to start${NC}"
+ kill $BACKEND_PID 2>/dev/null || true
+ exit 1
+fi
+
+echo " ${SUCCESS}βœ“${NC} Backend ready"
+echo ""
+
+# Start Vite dev server
+echo " ${MUTED}Starting Vite dev server on :5173...${NC}"
+cd dashboard
+
+if command -v bun >/dev/null 2>&1; then
+ bun run dev &
+else
+ npm run dev &
+fi
+VITE_PID=$!
+
+cd ..
+
+# Wait for Vite
+sleep 3
+
+echo ""
+echo " ${SUCCESS}${BOLD}βœ“ Ready!${NC}"
+echo ""
+echo " ${BOLD}Dashboard:${NC} ${ACCENT}http://localhost:5173/dashboard/${NC}"
+echo " ${BOLD}Backend:${NC} http://localhost:9867"
+echo ""
+echo " ${MUTED}Edit dashboard/src/* and changes will hot-reload.${NC}"
+echo " ${MUTED}Press Ctrl+C to stop.${NC}"
+echo ""
+
+# Wait for either process to exit
+wait $BACKEND_PID $VITE_PID
diff --git a/skills/pinchtab-dev/SKILL.md b/skills/pinchtab-dev/SKILL.md
new file mode 100644
index 00000000..8e958c63
--- /dev/null
+++ b/skills/pinchtab-dev/SKILL.md
@@ -0,0 +1,244 @@
+---
+name: pinchtab-dev
+description: Develop and contribute to the PinchTab project. Use when working on PinchTab source code, adding features, fixing bugs, running tests, or preparing PRs. Triggers on "work on pinchtab", "pinchtab development", "contribute to pinchtab", "fix pinchtab bug", "add pinchtab feature".
+---
+
+# PinchTab Development
+
+PinchTab is a browser control server for AI agents β€” 12MB Go binary with HTTP API.
+
+## Project Location
+
+```bash
+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) |
+| `./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 pr` | PR suite (api-fast + cli-fast) |
+| `./dev e2e release` | Release suite (api-full + cli-full) |
+| `./dev e2e docker` | Build local image and Docker smoke test |
+| `./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`:
+ ```bash
+ 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**:
+ ```bash
+ ./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
+
+| 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
+```bash
+./dev test unit # All Go tests
+go test ./internal/handlers # Specific package
+```
+
+### E2E Tests
+```bash
+./dev e2e pr # Fast suite for PRs
+./dev e2e api-fast # API tests only
+./dev e2e cli-fast # CLI tests only
+./dev e2e release # Full release suite
+```
+
+### Dashboard Tests
+```bash
+./dev test dashboard # Vitest
+cd dashboard && npm test
+```
+
+## Dashboard Development
+
+### Setup
+
+Start hot-reload development:
+```bash
+./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**:
+ ```bash
+ ./dev dashboard
+ ```
+
+2. **Make changes** to files in `dashboard/src/`
+
+3. **Verify with pinchtab** β€” use the pinchtab skill to inspect the dashboard:
+ ```bash
+ # 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
+
+```bash
+# 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`:
+```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