Skip to content

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

docs: audit and update all build paths and architectural references

Luigi Agostib273c213b842
diff --git a/Dockerfile b/Dockerfile
index f955f80b..e8dde9a2 100644
--- a/Dockerfile
+++ b/Dockerfile
@@ -5,7 +5,7 @@ WORKDIR /build
COPY go.mod go.sum ./
RUN go mod download
COPY . .
-RUN go build -ldflags="-s -w" -o pinchtab .
+RUN go build -ldflags="-s -w" -o pinchtab ./cmd/pinchtab
# Runtime stage
FROM alpine:latest
diff --git a/README.md b/README.md
index 7b0c0a61..e5a3262e 100644
--- a/README.md
+++ b/README.md
@@ -66,7 +66,7 @@ Your agent can clone, build, and configure Pinchtab using the [OpenClaw skill](s
```bash
# Build
-go build -o pinchtab .
+go build -o pinchtab ./cmd/pinchtab
# Headless mode (default) — no window, pure automation (best for token-efficient API flows)
./pinchtab
@@ -360,7 +360,7 @@ go install github.com/pinchtab/pinchtab@latest
# Or clone and build
git clone https://github.com/pinchtab/pinchtab.git
cd pinchtab
-go build -o pinchtab .
+go build -o pinchtab ./cmd/pinchtab
```
## Development
@@ -368,7 +368,7 @@ go build -o pinchtab .
```bash
git clone https://github.com/pinchtab/pinchtab.git
cd pinchtab
-go build -o pinchtab .
+go build -o pinchtab ./cmd/pinchtab
./pinchtab
# Run tests (38 tests)
diff --git a/docs/pinchtab-architecture.md b/docs/pinchtab-architecture.md
index 47bd779a..59a07fc2 100644
--- a/docs/pinchtab-architecture.md
+++ b/docs/pinchtab-architecture.md
@@ -22,77 +22,60 @@ The accessibility tree (a11y) is the primary interface — not screenshots, not
2. **HTTP over WebSocket** — Stateless requests, no connection management for agents
3. **Ref stability** — Snapshot refs (e0, e1...) are cached and reused by action endpoints
4. **Self-contained** — Launches its own Chrome, manages its own state, zero config needed
-5. **Internal tool** — Not a product, not a SaaS, not a platform
+5. **Decoupled Architecture** — Interface-driven design for testability and maintainability
-## File Structure
+## Project Layout
+
+The project follows the standard Go `internal/` pattern to ensure encapsulation and clean boundaries:
```
pinchtab/
-├── main.go # Entry point: Chrome launch, route registration, signal handling
-├── config.go # Configuration: env vars, config file, embedded assets
-├── bridge.go # Bridge struct: tab management, Chrome lifecycle
-├── interfaces.go # BridgeAPI interface (for test mocking)
-├── handlers.go # HTTP handlers: navigate, screenshot, tabs, lock, shutdown
-├── handler_snapshot.go # Snapshot handler: a11y tree fetch, format, file output
-├── handler_actions.go # Action/actions handlers: click, type, press, fill, etc.
-├── handler_cookies.go # Cookie get/set handlers
-├── handler_stealth.go # Stealth status, fingerprint rotation
-├── snapshot.go # A11y tree parsing: CDP response → flat A11yNode list
-├── lock.go # Tab locking for multi-agent coordination
-├── animations.go # CSS animation disabling (global + per-request)
-├── human.go # Human-like interaction: bezier mouse, natural typing
-├── cdp.go # Raw CDP helpers: navigate, readyState polling
-├── state.go # Session persistence: save/restore tabs to disk
-├── middleware.go # HTTP middleware: logging, auth token, CORS
-├── stealth.js # Stealth script: light/full modes, injected via CDP
-├── readability.js # Readability extraction for /text endpoint
-├── welcome.html # Headed mode welcome page (🦀 branding)
+├── cmd/pinchtab/ # Application entry points and CLI commands
+├── internal/
+│ ├── bridge/ # Core CDP logic, tab management, and state logic
+│ ├── handlers/ # HTTP API handlers and middleware
+│ ├── orchestrator/ # Multi-instance lifecycle and process management
+│ ├── profiles/ # Chrome profile management and identity discovery
+│ ├── dashboard/ # Backend logic and static assets for the web UI
+│ ├── assets/ # Centralized embedded files (stealth scripts, HTML)
+│ ├── human/ # Human-like interaction simulation (Bezier mouse, typing)
+│ ├── config/ # Centralized configuration management
+│ └── web/ # Shared HTTP and JSON utilities
├── Dockerfile # Alpine + Chromium container image
-└── scripts/
- ├── install-autostart.sh # LaunchAgent/systemd installer
- ├── launchd/ # macOS plist
- └── systemd/ # Linux service unit
+└── scripts/ # Deployment and automation scripts
```
## Core Components
-### Bridge (`bridge.go`)
-
-The central state holder. Owns the Chrome browser context, tab registry, and snapshot caches.
+### Bridge (`internal/bridge`)
-```go
-type Bridge struct {
- allocCtx context.Context // Chrome allocator context
- browserCtx context.Context // Browser-level context
- tabs map[string]*TabEntry // tabID → context
- snapshots map[string]*refCache // tabID → last snapshot refs
- mu sync.RWMutex
-}
-```
+The central state holder. Owns the Chrome browser context, tab registry, and snapshot caches. It implements the `BridgeAPI` interface.
Key responsibilities:
- **Tab lifecycle** — `CreateTab`, `CloseTab`, `TabContext` (resolve "" to first tab)
- **Ref caching** — Each tab's last snapshot is cached. When `/action` receives `ref: "e5"`,
- it looks up the cached `backendNodeID` without re-fetching the a11y tree.
-- **Thread safety** — `sync.RWMutex` protects tab and cache maps
+ it looks up the cached `BackendDOMNodeID` without re-fetching the a11y tree.
+- **State Logic** — Diffing snapshots and manage session persistence (`SaveState`/`RestoreState`).
-### BridgeAPI Interface (`interfaces.go`)
+### Orchestrator (`internal/orchestrator`)
-```go
-type BridgeAPI interface {
- TabContext(tabID string) (ctx context.Context, resolvedID string, err error)
- ListTargets() ([]*target.Info, error)
- CreateTab(url string) (string, context.Context, context.CancelFunc, error)
- CloseTab(tabID string) error
- GetRefCache(tabID string) *refCache
- SetRefCache(tabID string, cache *refCache)
- DeleteRefCache(tabID string)
-}
-```
+Manages multiple isolated browser instances. It uses a `HostRunner` interface to decouple business logic from OS process management.
+
+Key responsibilities:
+- **Instance Registry** — Tracking running instances, their ports, and statuses.
+- **Process Management** — Spawning, signaling, and stopping instances.
+- **Health Monitoring** — Probing instance health via HTTP.
-Handlers receive `BridgeAPI`, not `*Bridge`. Tests can mock it without Chrome.
+### Profiles (`internal/profiles`)
-### Snapshot Pipeline (`snapshot.go`, `handler_snapshot.go`)
+Handles Chrome user data directories and metadata.
+
+Key responsibilities:
+- **CRUD Operations** — Creating, importing, and resetting profiles.
+- **Identity Discovery** — Parsing internal Chrome JSON files to find user identity info.
+- **Activity Tracking** — Recording and analyzing agent actions per profile.
+
+### Snapshot Pipeline (`internal/bridge/snapshot.go`)
The a11y tree is Pinchtab's core abstraction. Flow:
@@ -100,7 +83,7 @@ The a11y tree is Pinchtab's core abstraction. Flow:
Chrome a11y tree (CDP)
│
▼
- Raw JSON parse (rawAXNode) ← Manual parsing to avoid cdproto crash
+ Raw JSON parse (RawAXNode) ← Manual parsing to avoid cdproto crash
│ on "uninteresting" PropertyName values
▼
Flatten to []A11yNode ← DFS walk, assign refs (e0, e1, e2...)
@@ -110,282 +93,29 @@ Chrome a11y tree (CDP)
└──▶ YAML ← Alternative structured format
```
-**A11yNode** is the universal unit:
-```go
-type A11yNode struct {
- Ref string // "e0", "e1" — stable within snapshot
- Role string // "button", "link", "textbox"
- Name string // Accessible name
- Depth int // Tree depth for indentation
- Value string // Input values
- Disabled bool
- Focused bool
- NodeID int64 // CDP backendNodeID (internal, for actions)
-}
-```
-
**Ref caching**: When `/snapshot` is called, the ref→nodeID mapping is stored per tab.
-When `/action` receives `{"ref": "e5", "kind": "click"}`, it looks up `e5` in the cache
-to find the backendNodeID. This avoids a second a11y tree fetch (which could drift).
+When `/action` receives `{"ref": "e5", "kind": "click"}`, it looks up `e5` in the cache.
-**Filters**:
-- `?filter=interactive` — Only clickable/typeable elements (~65% token reduction)
-- `?depth=3` — Limit tree depth
-- `?diff=true` — Return only changes since last snapshot
+### Human Interaction (`internal/human`)
-### Action System (`handlers.go`)
+Two main simulation engines for anti-detection:
-Actions are registered in an `actionRegistry` map:
-
-```go
-var registry = map[string]actionFunc{
- "click": ..., // Standard click
- "type": ..., // Type text into focused element
- "press": ..., // Key press (Enter, Tab, etc.)
- "select": ..., // Select dropdown option
- "hover": ..., // Mouse hover
- "scroll": ..., // Scroll viewport
- "humanClick": ..., // Bezier-curve mouse movement + click
- "humanType": ..., // Natural typing with variable delays
-}
-```
-
-Actions resolve targets in priority order: `ref` → `selector` → `nodeId`.
-Ref resolution: look up in snapshot cache → find backendNodeID → execute CDP command.
-
-**Action chaining** (`POST /actions`): Batch multiple actions in one request.
-Executes sequentially, returns results array. Saves round-trips for multi-step interactions.
-
-### Human Interaction (`human.go`)
-
-Two main functions for anti-detection:
-
-**`humanMouseMove`** — Cubic bezier curve from A to B:
+**`MouseMove`** — Cubic bezier curve from A to B:
- Random control points for natural curvature
-- Step count scales with distance (5-30 steps, capped to prevent timeout)
-- Per-step jitter (±2px) and variable timing (16-24ms)
+- Step count scales with distance (5-30 steps)
+- Per-step jitter and variable timing
-**`humanType`** — Keystroke-level simulation:
+**`Type`** — Keystroke-level simulation:
- Base delay: 80ms/char (40ms in fast mode)
-- 5% chance of long pause ("thinking")
-- 3% chance of typo → backspace → correct character
-- Faster for repeated characters
-
-### Stealth System (`stealth.js`, `handlers.go`)
-
-Two layers:
-
-**Layer 1: Chrome launch flags** (compile-time)
-```
---exclude-switches=enable-automation
---disable-blink-features=AutomationControlled
---disable-infobars
-+ 15 more flags
-```
-
-**Layer 2: JavaScript injection** (runtime, via `AddScriptToEvaluateOnNewDocument`)
-- `navigator.webdriver` → undefined
-- `navigator.plugins` → 3 realistic entries
-- `navigator.languages` → ['en-US', 'en']
-- WebGL vendor → "Intel Inc." / "Intel Iris OpenGL Engine"
-- Canvas fingerprint noise → temp canvas with pixel-level noise
-- Font metrics noise → Proxy on `measureText` (width only)
-- WebRTC → `iceTransportPolicy: 'relay'` (no local IP leak)
-- Hardware values → seeded PRNG, consistent within session
-- Timezone → configurable via `window.__pinchtab_timezone`
-
-**Stealth status** (`GET /stealth/status`) — live-probes the browser by evaluating JS
-to verify features are actually active (not hardcoded booleans).
-
-**Fingerprint rotation** (`POST /fingerprint/rotate`) — injects UA/platform/screen/timezone
-overrides via `AddScriptToEvaluateOnNewDocument` (persists across navigations).
-
-### Navigation (`cdp.go`)
-
-Custom `navigatePage` instead of chromedp's built-in `Navigate`:
-- Uses raw `Page.navigate` CDP command
-- Polls `document.readyState` until "interactive" or "complete"
-- 10-second timeout prevents hangs on heavy SPAs
-- Doesn't wait for full `load` event (which SPAs may never fire)
-
-### Session Persistence (`state.go`)
-
-On clean shutdown (SIGINT/SIGTERM):
-1. Iterate all open tabs, collect URL + title
-2. Write to `~/.pinchtab/sessions.json`
-
-On startup:
-1. Read `sessions.json` if it exists
-2. Re-open tabs with concurrency limiting (max 3 tabs, max 2 navigations)
-3. `markCleanExit()` patches Chrome prefs to suppress "didn't shut down correctly" bar
-
-### Configuration (`config.go`)
-
-Priority order (highest wins):
-1. Environment variables (`BRIDGE_PORT`, `BRIDGE_TOKEN`, etc.)
-2. Config file (`~/.pinchtab/config.json`)
-3. Defaults
-
-```go
-//go:embed stealth.js
-var stealthScript string
-
-//go:embed readability.js
-var readabilityJS string
-```
-
-Both JS files are compiled into the binary via Go embed.
-
-### Middleware (`middleware.go`)
-
-Request pipeline:
-```
-Request → Logging → Auth (Bearer token) → CORS → Handler → Response
-```
-
-- **Logging**: slog with method, path, status, duration
-- **Auth**: Optional `BRIDGE_TOKEN` — if set, all requests need `Authorization: Bearer <token>`
-- **CORS**: Permissive (localhost tool, not public)
-
-## Data Flow
-
-### Typical Agent Interaction
-
-```
-Agent Pinchtab Chrome
- │ │ │
- │ POST /navigate │ │
- │ {"url": "https://..."} │ │
- │ ─────────────────────────────▶│ Page.navigate │
- │ │─────────────────────────────▶│
- │ │ poll readyState │
- │ │◀─────────────────────────────│
- │ {"tabId": "AB12..."} │ │
- │◀──────────────────────────────│ │
- │ │ │
- │ GET /snapshot?filter=interactive │
- │ ─────────────────────────────▶│ Accessibility.getFullAXTree │
- │ │─────────────────────────────▶│
- │ │ ◀── raw AX nodes ────────── │
- │ │ flatten + assign refs │
- │ │ cache ref→nodeID │
- │ [{"ref":"e0","role":"button",│ │
- │ "name":"Sign In"}, ...] │ │
- │◀──────────────────────────────│ │
- │ │ │
- │ POST /action │ │
- │ {"ref":"e0","kind":"click"} │ │
- │ ─────────────────────────────▶│ lookup e0 → nodeID 1234 │
- │ │ DOM.resolveNode(1234) │
- │ │ DOM.getBoxModel │
- │ │ Input.dispatchMouseEvent │
- │ │─────────────────────────────▶│
- │ {"clicked": true} │ │
- │◀──────────────────────────────│ │
-```
-
-### Typical Agent Interaction in Headed mode
-
-In headed mode, the human sets up and validates profiles first, then the agent runs against those profiles.
-
-```
-Human Operator Dashboard (`pinchtab dashboard`) Profile Instance Agent
- │ │ │ │
- │ create/import profile │ │ │
- │───────────────────────────▶│ │ │
- │ launch profile on :9868 │ │ │
- │───────────────────────────▶│ spawn `pinchtab` │ │
- │ │─────────────────────────────▶│ headed Chrome │
- │ manual login / 2FA │ │ │
- │<──────────────────────────────────── visible browser ────────────────────────-│
- │ validate state │ │ │
- │ │ profile URL ready │ │
- │ │─────────────┬───────────────-│ │
- │ │ │ │
- │ │ │ POST /navigate │
- │ │ │◀──────────────────────────────────-│
- │ │ │ GET /snapshot │
- │ │ │◀──────────────────────────────────-│
- │ │ │ POST /action │
- │ │ │◀──────────────────────────────────-│
-```
-
-Key point: the dashboard coordinates profiles and lifecycle, but agents call the running profile instance (`http://localhost:<profile-port>`), not the dashboard proxy endpoint.
-
-### Token Efficiency
-
-| Method | ~Tokens | Use Case |
-|--------|---------|----------|
-| Full snapshot (JSON) | 10,500 | Initial page understanding |
-| Interactive filter | 3,600 | Action planning (buttons, links, inputs) |
-| `/text` (readability) | 800 | Content extraction |
-| `/screenshot` | 2,000 | Visual verification |
-| Diff snapshot | varies | Monitoring changes |
-
-## API Reference
-
-### Read Operations
-
-| Endpoint | Method | Description |
-|----------|--------|-------------|
-| `/health` | GET | Server status + version |
-| `/tabs` | GET | List all open tabs |
-| `/snapshot` | GET | A11y tree snapshot. Params: `tabId`, `filter`, `depth`, `format`, `diff`, `output` |
-| `/screenshot` | GET | JPEG screenshot. Params: `tabId`, `quality`, `output` |
-| `/text` | GET | Readability-extracted text. Params: `tabId` |
-| `/cookies` | GET | Get cookies for current page. Params: `tabId` |
-| `/stealth/status` | GET | Live stealth feature verification |
-
-### Write Operations
-
-| Endpoint | Method | Description |
-|----------|--------|-------------|
-| `/navigate` | POST | Navigate tab to URL. Body: `{"url", "tabId", "newTab"}` |
-| `/action` | POST | Execute single action. Body: `{"kind", "ref", "selector", "text", ...}` |
-| `/actions` | POST | Execute action batch. Body: `[{action}, {action}, ...]` |
-| `/evaluate` | POST | Run JavaScript. Body: `{"expression", "tabId"}` |
-| `/tab` | POST | Tab management. Body: `{"action": "close", "tabId"}` |
-| `/cookies` | POST | Set cookies. Body: `{"cookies": [...]}` |
-| `/fingerprint/rotate` | POST | Rotate browser fingerprint. Body: `{"os", "browser", "screen", ...}` |
-
-### Action Kinds
-
-| Kind | Required Fields | Description |
-|------|----------------|-------------|
-| `click` | `ref` or `selector` | Standard click |
-| `type` | `ref`/`selector` + `text` | Type into element |
-| `press` | `key` | Keyboard press (Enter, Tab, Escape, etc.) |
-| `select` | `ref`/`selector` + `values` | Select dropdown option(s) |
-| `hover` | `ref` or `selector` | Mouse hover |
-| `scroll` | (optional) `scrollX`, `scrollY` | Scroll viewport (default: down 800px) |
-| `humanClick` | `ref` or `selector` | Click with bezier mouse movement |
-| `humanType` | `ref`/`selector` + `text` | Type with natural timing + typos |
-
-### Snapshot Formats
-
-**JSON** (default): `GET /snapshot`
-```json
-[
- {"ref": "e0", "role": "heading", "name": "Welcome", "depth": 0},
- {"ref": "e1", "role": "button", "name": "Sign In", "depth": 1}
-]
-```
-
-**Text**: `GET /snapshot?format=text`
-```
-heading "Welcome"
- button "Sign In" [e1]
- textbox "Email" [e2]
-```
-
-**YAML**: `GET /snapshot?format=yaml`
+- Random long pauses ("thinking")
+- Simulated typos and backspace corrections
## Deployment
### Binary (recommended)
```bash
# Build
-go build -o pinchtab .
+go build -o pinchtab ./cmd/pinchtab
# Run
BRIDGE_TOKEN=secret ./pinchtab
@@ -393,52 +123,6 @@ BRIDGE_TOKEN=secret ./pinchtab
### Docker
```bash
+docker build -t pinchtab .
docker run -d -p 9867:9867 -e BRIDGE_TOKEN=secret pinchtab
```
-
-### Auto-start
-```bash
-# macOS
-./scripts/install-autostart.sh
-
-# Linux (systemd)
-sudo cp scripts/systemd/pinchtab.service /etc/systemd/system/
-sudo systemctl enable --now pinchtab
-```
-
-### Configuration
-```json
-// ~/.pinchtab/config.json
-{
- "port": "9867",
- "token": "secret",
- "headless": true,
- "stateDir": "~/.pinchtab"
-}
-```
-
-## State & Persistence
-
-```
-~/.pinchtab/
-├── chrome-profile/ # Chrome user data (cookies, localStorage, etc.)
-├── sessions.json # Saved tab state (written on shutdown)
-├── screenshots/ # File output from ?output=file
-├── snapshots/ # File output from ?output=file
-└── config.json # Optional config file
-```
-
-## Security Model
-
-Pinchtab has **no authentication by default**. When `BRIDGE_TOKEN` is set:
-- All requests must include `Authorization: Bearer <token>`
-- `/health` is exempt (for monitoring)
-
-**Pinchtab gives full browser control.** Anyone with HTTP access can:
-- Read any page content (cookies, passwords, session tokens)
-- Navigate to any URL
-- Execute arbitrary JavaScript
-- Take screenshots
-
-**Always run behind a firewall.** Bind to localhost unless you explicitly need remote access.
-This is a power tool for trusted agents on a trusted machine — not a public service.
diff --git a/internal/dashboard/dashboard/profiles.js b/internal/dashboard/dashboard/profiles.js
index ec66489b..1f279f49 100644
--- a/internal/dashboard/dashboard/profiles.js
+++ b/internal/dashboard/dashboard/profiles.js
@@ -255,7 +255,7 @@ function updateLaunchCommand() {
const profilePath = profilePathRaw || '<PROFILE_PATH>';
const statePath = profilePath + '/.pinchtab-state';
const prefix = profilePathRaw ? '' : '# replace <PROFILE_PATH> first\n';
- const cmd = '(test -x ./bin/pinchtab || go build -o ./bin/pinchtab .) && '
+ const cmd = '(test -x ./bin/pinchtab || go build -o ./bin/pinchtab ./cmd/pinchtab) && '
+ 'BRIDGE_PORT=' + shellQuote(port || '9868') + ' '
+ 'BRIDGE_PROFILE=' + shellQuote(profilePath) + ' '
+ 'BRIDGE_STATE_DIR=' + shellQuote(statePath) + ' '
diff --git a/scripts/check.sh b/scripts/check.sh
index b7046802..ece5a29a 100755
--- a/scripts/check.sh
+++ b/scripts/check.sh
@@ -41,7 +41,7 @@ fi
success_step "Go Vet"
check_step "Build"
-if ! go build -o pinchtab .; then
+if ! go build -o pinchtab ./cmd/pinchtab; then
error_step "Build"
fi
success_step "Build"
diff --git a/scripts/install-autostart.sh b/scripts/install-autostart.sh
index 2ee18c98..5e7ee8ac 100755
--- a/scripts/install-autostart.sh
+++ b/scripts/install-autostart.sh
@@ -11,7 +11,7 @@ if [[ "$OSTYPE" == "darwin"* ]]; then
echo "Detected macOS - using launchd"
if [ ! -f "$PINCHTAB_BIN" ]; then
echo "Building pinchtab..."
- (cd "$SCRIPT_DIR/.." && go build -o pinchtab .)
+ (cd "$SCRIPT_DIR/.." && go build -o pinchtab ./cmd/pinchtab)
fi
echo "Installing pinchtab to /usr/local/bin..."
sudo cp "$PINCHTAB_BIN" /usr/local/bin/pinchtab
@@ -36,7 +36,7 @@ elif [[ "$OSTYPE" == "linux-gnu"* ]]; then
echo "Detected Linux - using systemd"
if [ ! -f "$PINCHTAB_BIN" ]; then
echo "Building pinchtab..."
- (cd "$SCRIPT_DIR/.." && go build -o pinchtab .)
+ (cd "$SCRIPT_DIR/.." && go build -o pinchtab ./cmd/pinchtab)
fi
echo "Installing pinchtab to /usr/local/bin..."
sudo cp "$PINCHTAB_BIN" /usr/local/bin/pinchtab
diff --git a/scripts/run_pinchtab.sh b/scripts/run_pinchtab.sh
index b8911be7..c00c4dd5 100755
--- a/scripts/run_pinchtab.sh
+++ b/scripts/run_pinchtab.sh
@@ -8,7 +8,7 @@ BIN_PATH="$BIN_DIR/pinchtab"
mkdir -p "$BIN_DIR"
cd "$ROOT_DIR"
-go build -o "$BIN_PATH" .
+go build -o "$BIN_PATH" ./cmd/pinchtab
if [ "$#" -eq 0 ]; then
set -- dashboard