High-performance browser automation bridge and multi-instance orchestrator with advanced stealth injection and real-time dashboard.
docs: comprehensive overview and getting started guides
Mario8be35a66d321
diff --git a/docs/get-started.md b/docs/get-started.mdindex e69de29b..cd810d2b 100644--- a/docs/get-started.md+++ b/docs/get-started.md@@ -0,0 +1,666 @@+# Getting Started with Pinchtab++Get Pinchtab running in 5 minutes, from zero to browser automation.++---++## Installation (Choose One)++### Option 1: One-Liner (Recommended)++**macOS / Linux:**+```bash+curl -fsSL https://pinchtab.com/install.sh | bash+```++Then verify:+```bash+pinchtab --version+```++### Option 2: npm++**Requires:** Node.js 18+++```bash+npm install -g pinchtab+pinchtab --version+```++**Troubleshooting npm:**+```bash+# If "command not found", add npm to PATH+export PATH="$(npm config get prefix)/bin:$PATH"+# Add to ~/.bashrc or ~/.zshrc to persist+```++### Option 3: Docker++**Requires:** Docker++```bash+docker run -d -p 9867:9867 pinchtab/pinchtab+curl http://localhost:9867/health+```++### Option 4: Build from Source++**Requires:** Go 1.25+, Git, Chrome/Chromium++```bash+git clone https://github.com/pinchtab/pinchtab.git+cd pinchtab+go build -o pinchtab ./cmd/pinchtab+./pinchtab --version+```++**[Full build guide →](architecture/building.md)**++---++## Quick Start (5 Minutes)++### Step 1: Start the Server++**Terminal 1:**+```bash+pinchtab+```++**Expected output:**+```+🦀 PINCH! PINCH! port=9867 cdp= stealth=light+auth disabled (set BRIDGE_TOKEN to enable)+startup configuration bind=127.0.0.1 port=9867 headless=true ...+```++The server is running on `http://127.0.0.1:9867`.++### Step 2: Run Your First Command++**Terminal 2:**+```bash+pinchtab quick https://example.com+```++**What happens:**+1. Navigates to the URL+2. Shows page structure+3. Lists interactive elements+4. Suggests next actions++**Output:**+```+🦀 Navigating to https://example.com ...++📋 Page structure:+[accessibility tree...]++📌 Title: Example Domain+🔗 URL: https://example.com/++💡 Quick actions:+ pinchtab click <ref> # Click an element+ pinchtab type <ref> <text> # Type into input+ pinchtab screenshot # Take a screenshot+ pinchtab pdf -o output.pdf # Save as PDF+```++✅ **You're running Pinchtab!**++---++## Common First Commands++### Get Page Content++```bash+# Read the page as text+pinchtab text++# See interactive elements+pinchtab snap -i -c++# Get raw HTML content+pinchtab text --raw+```++### Take a Screenshot++```bash+pinchtab screenshot -o page.jpg+pinchtab screenshot -o page.jpg -q 75 # Lower quality+```++### Export as PDF++```bash+pinchtab pdf -o output.pdf+pinchtab pdf -o report.pdf --landscape+```++### Interact with the Page++```bash+# First, get interactive elements+pinchtab snap -i -c++# Then click one (replace 'e5' with a real ref)+pinchtab click e5++# Verify the change+pinchtab snap -i -c++# Or fill a form+pinchtab fill e3 "[email protected]"+pinchtab fill e5 "password"+pinchtab click e7 # Submit button+```++### Multiple Tabs++```bash+# Open second tab+pinchtab tabs new https://github.com++# List all tabs+pinchtab tabs++# Get snapshot from specific tab (replace tabId)+pinchtab snap --tab abc123def456+```++---++## Understanding the Workflow++### Key Concept: Tab-Centric++Pinchtab is **tab-centric**, not URL-centric:++```+❌ WRONG: pinchtab snap https://example.com+✅ CORRECT:+ 1. pinchtab nav https://example.com (uses current tab)+ 2. pinchtab snap (snapshots current tab)+```++**Why?** Because a tab has state (cookies, history, focus, loaded content). Multiple tabs can exist. You need to specify which tab to work with.++### Typical Workflow++```+1. Navigate to a page+ pinchtab nav https://example.com++2. Get page structure+ pinchtab snap -i -c # See buttons, links, inputs++3. Interact with page+ pinchtab click e5 # Click element+ pinchtab type e3 "text" # Type text++4. Verify changes+ pinchtab snap -i -c # Check new state++5. Capture result+ pinchtab screenshot # Take screenshot+ pinchtab pdf -o out.pdf # Export PDF+```++---++## Using with curl (HTTP API)++You don't need the CLI. Pinchtab is HTTP:++```bash+# Health check+curl http://localhost:9867/health++# Navigate (returns tabId)+curl -X POST http://localhost:9867/tab \+ -H "Content-Type: application/json" \+ -d '{"action":"new","url":"https://example.com"}'++# Get snapshot+curl "http://localhost:9867/snapshot?tabId=abc123"++# Extract text+curl "http://localhost:9867/text?tabId=abc123"+```++**Full API reference** → [curl-commands.md](references/curl-commands.md)++---++## Using with Python++```python+import requests+import json++BASE = "http://localhost:9867"++# Create tab + navigate+resp = requests.post(f"{BASE}/tab", json={+ "action": "new",+ "url": "https://example.com"+})+tab_id = resp.json()["tabId"]++# Get snapshot+snapshot = requests.get(f"{BASE}/snapshot", params={+ "tabId": tab_id,+ "filter": "interactive"+}).json()++# Print interactive elements+for elem in snapshot["elements"]:+ print(f"{elem['ref']}: {elem['role']} - {elem['name']}")++# Click an element+requests.post(f"{BASE}/action", json={+ "kind": "click",+ "ref": "e5",+ "tabId": tab_id+})+```++---++## Using with Node.js++```javascript+const fetch = require('node-fetch');++const BASE = "http://localhost:9867";++async function main() {+ // Create tab+ const navResp = await fetch(`${BASE}/tab`, {+ method: "POST",+ headers: { "Content-Type": "application/json" },+ body: JSON.stringify({+ action: "new",+ url: "https://example.com"+ })+ });+ const nav = await navResp.json();+ const tabId = nav.tabId;++ // Get snapshot+ const snapResp = await fetch(+ `${BASE}/snapshot?tabId=${tabId}&filter=interactive`+ );+ const snap = await snapResp.json();++ // Click element+ await fetch(`${BASE}/action`, {+ method: "POST",+ headers: { "Content-Type": "application/json" },+ body: JSON.stringify({+ kind: "click",+ ref: "e5",+ tabId: tabId+ })+ });+}++main();+```++---++## Configuration++### Basic Configuration++```bash+# Custom port+BRIDGE_PORT=9868 pinchtab++# Visible window+BRIDGE_HEADLESS=false pinchtab++# Stealth mode (bypass bot detection)+BRIDGE_STEALTH=full pinchtab++# Block ads+BRIDGE_BLOCK_ADS=true pinchtab++# Custom Chrome+CHROME_BINARY=/usr/bin/google-chrome pinchtab+```++### Combined++```bash+BRIDGE_PORT=9868 \+BRIDGE_STEALTH=full \+BRIDGE_BLOCK_ADS=true \+BRIDGE_HEADLESS=false \+pinchtab+```++**[Full configuration →](architecture/pinchtab-architecture.md)**++---++## Common Scenarios++### Scenario 1: Scrape a Website++```bash+# Navigate+pinchtab nav https://example.com/article++# Extract readable text+pinchtab text > article.txt++# Or with curl+curl http://localhost:9867/text > article.json+jq '.text' article.json+```++### Scenario 2: Fill a Form++```bash+# Navigate to form+pinchtab nav https://example.com/contact++# Get interactive elements+pinchtab snap -i -c++# Fill form fields (use refs from snapshot)+pinchtab fill e3 "John Doe"+pinchtab fill e5 "[email protected]"+pinchtab fill e7 "My message here"++# Click submit+pinchtab click e10++# Verify success+pinchtab snap+```++### Scenario 3: Login + Stay Logged In++```bash+# Login+pinchtab nav https://example.com/login+pinchtab fill e3 "[email protected]"+pinchtab fill e5 "password"+pinchtab click e7++# Later, even after restarting Pinchtab, you're still logged in+pkill pinchtab+sleep 2+pinchtab &++# Tab and session restored+pinchtab nav https://example.com/dashboard+pinchtab snap # Already authenticated+```++### Scenario 4: Generate PDF Report++```bash+# Navigate to report page+pinchtab nav https://reports.example.com/monthly++# Export as PDF with header/footer+pinchtab pdf -o report.pdf \+ --landscape \+ --display-header-footer \+ --header-template "<div>Monthly Report</div>" \+ --footer-template "<div>Page <span class='pageNumber'></span></div>"+```++### Scenario 5: Multi-Tab Workflow++```bash+# Open first tab+pinchtab nav https://source.example.com+SOURCE_TAB=$(pinchtab tabs | jq -r '.[0].id')++# Open second tab+pinchtab tabs new https://destination.example.com+DEST_TAB=$(pinchtab tabs | jq -r '.[1].id')++# Extract from source+DATA=$(curl "http://localhost:9867/text?tabId=$SOURCE_TAB")++# Fill in destination+curl -X POST http://localhost:9867/action \+ -d "{\"kind\":\"fill\",\"ref\":\"e3\",\"text\":\"$DATA\",\"tabId\":\"$DEST_TAB\"}"+```++---++## Troubleshooting++### "connection refused" / "Cannot connect"++**Problem:** Server not running++**Solution:**+```bash+# Terminal 1: Start server+pinchtab++# Terminal 2: Use client (once server is running)+pinchtab snap+```++### "Port already in use"++**Problem:** Port 9867 is taken++**Solution:**+```bash+# Use different port+BRIDGE_PORT=9868 pinchtab++# Or kill the process using 9867+lsof -i :9867+kill -9 <PID>+```++### "Chrome not found"++**Problem:** Chrome/Chromium not installed++**Solution:**+```bash+# macOS+brew install chromium++# Linux (Ubuntu/Debian)+sudo apt install chromium-browser++# Or specify custom Chrome+CHROME_BINARY=/path/to/chrome pinchtab+```++### "Empty snapshot / about:blank"++**Problem:** Tab not navigated yet++**Solution:**+```bash+# Always navigate first+pinchtab nav https://example.com++# Then snapshot+pinchtab snap+```++### "ref e5 not found"++**Problem:** Ref changed (page updated)++**Solution:**+```bash+# Get fresh snapshot+pinchtab snap -i -c++# Use new refs from this snapshot+pinchtab click <new-ref>+```++---++## Next Steps++### 1. Try Some Workflows+→ [Practical examples & workflows](showcase.md)++### 2. Learn the CLI+→ [CLI commands reference](references/cli-commands.md)++### 3. Use the HTTP API+→ [API reference with curl examples](references/curl-commands.md)++### 4. Advanced Usage+→ [API workflows & patterns](showcase.md)++### 5. Production Deployment+→ [Docker deployment guide](guides/docker.md)++### 6. Understand the Architecture+→ [How Pinchtab works](architecture/pinchtab-architecture.md)++---++## Common Features++### Extract Text Efficiently++```bash+# Readable text (strips ads, nav)+pinchtab text # 800 tokens++# Raw text (full page)+pinchtab text --raw # ~1,500 tokens++# Filter by selector+pinchtab snap -s "main" # Only <main> element++# Limit tokens+pinchtab snap --max-tokens 1000+```++### Interact Precisely++```bash+# Get clickable elements only+pinchtab snap -i++# Click by ref+pinchtab click e5++# Type text+pinchtab type e3 "hello"++# Press keys+pinchtab press Enter+pinchtab press Tab+pinchtab press Escape++# Focus element+pinchtab focus e5++# Hover over element+pinchtab hover e5++# Select dropdown+pinchtab select e8 "Option 2"+```++### Run JavaScript++```bash+# Get page title+curl -X POST http://localhost:9867/execute \+ -d '{"expression":"document.title"}'++# Count links+curl -X POST http://localhost:9867/execute \+ -d '{"expression":"document.querySelectorAll(\"a\").length"}'++# Complex logic+curl -X POST http://localhost:9867/execute \+ -d '{"expression":"JSON.stringify({title: document.title, url: location.href})"}'+```++---++## Performance Tips++### Token Efficiency++```bash+# Use text, not screenshot+pinchtab text # 800 tokens+pinchtab screenshot # 10,000+ tokens++# Filter to interactive elements only+pinchtab snap -i -c # ~1,000 tokens+pinchtab snap # ~3,600 tokens++# Limit by tokens+pinchtab snap --max-tokens 1000+```++### Speed++```bash+# Parallel tabs for concurrent work+pinchtab tabs new https://...+pinchtab tabs new https://...+# Process multiple tabs in parallel++# Cache responses when possible+# Snapshot once, extract refs, then interact+pinchtab snap > snapshot.json+# Use refs from snapshot.json multiple times+```++---++## Quick Reference++| Task | Command |+|------|---------|+| Start server | `pinchtab` |+| Health check | `curl http://localhost:9867/health` |+| Navigate | `pinchtab nav https://...` |+| See structure | `pinchtab snap -i -c` |+| Get text | `pinchtab text` |+| Click element | `pinchtab click e5` |+| Type text | `pinchtab type e3 "hello"` |+| Screenshot | `pinchtab screenshot -o page.jpg` |+| PDF export | `pinchtab pdf -o out.pdf` |+| List tabs | `pinchtab tabs` |+| New tab | `pinchtab tabs new https://...` |+| Show help | `pinchtab help` |++---++## Getting Help++- **Issues** → [GitHub Issues](https://github.com/pinchtab/pinchtab/issues)+- **Q&A** → [GitHub Discussions](https://github.com/pinchtab/pinchtab/discussions)+- **Docs** → [Full documentation](overview.md)++---++## What's Next?++1. ✅ You've installed and run Pinchtab+2. 📚 Learn more → [Full documentation](overview.md)+3. 🎯 Try workflows → [Practical examples](showcase.md)+4. 🔧 Go deeper → [Architecture docs](architecture/)++**Happy automating!** 🦀diff --git a/docs/overview.md b/docs/overview.mdindex e69de29b..2d1aa8ea 100644--- a/docs/overview.md+++ b/docs/overview.md@@ -0,0 +1,363 @@+# Pinchtab Documentation++Welcome to Pinchtab — browser control for AI agents, scripts, and automation workflows.++## What is Pinchtab?++Pinchtab is a **standalone HTTP server** that gives you direct control over a Chrome browser. Instead of being locked into a specific agent framework, you can interact with it from anywhere — any AI agent, any programming language, or even `curl`.++```bash+# It's just HTTP. Use it anywhere.+curl http://localhost:9867/health+curl http://localhost:9867/text?tabId=abc123+curl -X POST http://localhost:9867/action -d '{"kind":"click","ref":"e5"}'+```++---++## Why Pinchtab?++### The Problem++Most browser automation tools are **framework-locked**:+- OpenClaw Browser → only works in OpenClaw+- Playwright MCP → only works with your MCP client+- Browser Use → only works in its own system++You can't use the same browser automation across different agents.++### The Solution++Pinchtab is **framework-agnostic HTTP server**:+- ✅ Works with any AI agent (Claude, ChatGPT, local models)+- ✅ Works with any language (bash, Python, Node.js, Go)+- ✅ Works with any tool (curl, Postman, your own scripts)+- ✅ Persistent sessions (log in once, stays logged in)+- ✅ Stealth mode (bypass bot detection)+- ✅ Token efficient (5-13x cheaper than alternatives)++---++## Key Features++### 🌲 Accessibility Tree+Structured tree with stable refs (e0, e1...) for click, type, and read. Deterministic — no coordinate guessing.++### 🎯 Smart Filters+`?filter=interactive` returns only buttons, links, and inputs. Fewer tokens per snapshot.++### 🕵️ Stealth Mode+Patches `navigator.webdriver`, spoofs UA, and hides automation flags to pass major bot checks.++### 💾 Persistent Sessions+Cookies, auth, and tabs survive restarts. Log in once and keep the session alive.++### 📝 Text Extraction+Readability mode strips nav and ads. Raw mode keeps full text for parser workflows.++### 🖱️ Direct Actions+Click, type, fill, press, focus, hover, select, and scroll by ref or selector.++### ⚡ JS Evaluation+Escape hatch for any workflow gap. Execute JavaScript in any tab on demand.++### 📸 Screenshots+JPEG output with quality control for visual verification and downstream auditing.++### 📄 PDF Export+Export full pages as PDF for sharing, archiving, and offline review.++### 🎭 Multi-Tab Support+Create, switch, and close tabs. Work with multiple pages simultaneously.++---++## Quick Comparison++| Feature | Pinchtab | OpenClaw Browser | Playwright | Selenium |+|---------|----------|------------------|-----------|----------|+| **Interface** | HTTP (any agent) | Framework-locked | Framework-locked | WebDriver |+| **Tokens/page** | ~800 (text) | ~10,000+ | N/A | N/A |+| **Stealth mode** | ✅ | ❌ | ❌ | ❌ |+| **Persistent sessions** | ✅ | ❌ | ❌ | ❌ |+| **Self-contained binary** | ✅ 12MB | ❌ | ❌ | ❌ |+| **Accessibility tree** | ✅ | ✅ | ❌ | ❌ |+| **PDF export** | ✅ | ❌ | ✅ | ❌ |+| **Tab-centric design** | ✅ | ❌ | ❌ | ❌ |++---++## Real Performance Numbers++### Token Efficiency++```+Reading a 1,500-word article:+ Pinchtab /text: 800-900 tokens (5-13x cheaper)+ OpenClaw snapshot: ~3,600 tokens+ Full screenshot: ~10,000 tokens+ Vision + screenshot: ~20,000 tokens+```++### Response Times++```+Navigate + snapshot: 1-3 seconds+Click + verify: 200-500ms+Text extraction: 100-300ms+PDF generation: 2-5 seconds+```++### Binary Size++```+Pinchtab: 12MB (includes Chrome)+Node.js equivalent: 100MB++Python equivalent: 200MB++```++---++## Architecture++### High-Level Design++```+┌─────────────────────────────────────────┐+│ Your Tool/Agent │+│ (curl, Python, Node.js, etc.) │+└──────────────┬──────────────────────────┘+ │+ │ HTTP+ ↓+┌─────────────────────────────────────────┐+│ Pinchtab HTTP Server (Go) │+│ ┌─────────────────────────────────┐ │+│ │ Tab Manager (multi-tab) │ │+│ │ ┌────────────┐ ┌────────────┐ │ │+│ │ │ Tab 1 │ │ Tab 2 │ │ │+│ │ │ DOM │ │ DOM │ │ │+│ │ │ History │ │ History │ │ │+│ │ └────────────┘ └────────────┘ │ │+│ └─────────────────────────────────┘ │+│ ┌─────────────────────────────────┐ │+│ │ Chrome DevTools Protocol │ │+│ │ (WebSocket to Chrome) │ │+│ └─────────────────────────────────┘ │+└──────────────┬──────────────────────────┘+ │+ │ CDP+ ↓+┌─────────────────────────────────────────┐+│ Chrome Browser (Headless) │+│ ┌────────────┐ ┌────────────┐ │+│ │ Tab 1 │ │ Tab 2 │ │+│ │ (website) │ │ (website) │ │+│ └────────────┘ └────────────┘ │+└─────────────────────────────────────────┘+```++### What Makes It Different++1. **Tab-Centric** — Everything revolves around tabs, not URLs+2. **Stateful** — Sessions persist between requests+3. **Accessibility-First** — Uses accessibility tree, not coordinates+4. **HTTP API** — Standard web interface, no proprietary protocols+5. **Multi-Agent Safe** — Tab locking for agent coordination++---++## Getting Started++### Installation (30 seconds)++```bash+# macOS / Linux+curl -fsSL https://pinchtab.com/install.sh | bash++# Or with npm+npm install -g pinchtab++# Or build from source+git clone https://github.com/pinchtab/pinchtab.git+cd pinchtab+go build -o pinchtab ./cmd/pinchtab+```++### First Steps++```bash+# Terminal 1: Start the server+pinchtab++# Terminal 2: Try a command+curl http://localhost:9867/health # Health check+pinchtab quick https://example.com # Quick start+pinchtab snap -i -c # Get interactive elements+```++### Next++- **Quick Start Guide** → [get-started.md](get-started.md)+- **CLI Commands** → [references/cli-commands.md](references/cli-commands.md)+- **API Reference** → [references/curl-commands.md](references/curl-commands.md)+- **Practical Examples** → [showcase.md](showcase.md)+- **Architecture Deep-Dive** → [architecture/pinchtab-architecture.md](architecture/pinchtab-architecture.md)++---++## Use Cases++### 1. AI Agent Automation+Any AI agent (Claude, ChatGPT, Anthropic models) can control browsers:+```bash+# Agent uses Pinchtab to fill forms, navigate, extract data+pinchtab nav https://example.com+pinchtab snap -i -c # Get interactive elements+pinchtab click e5 # Agent decides based on snapshot+```++### 2. Data Scraping+Extract text from complex websites:+```bash+pinchtab nav https://example.com/article+pinchtab text # 800 tokens instead of 10,000 with vision+```++### 3. Testing & QA+End-to-end testing with persistence:+```bash+# Login once+pinchtab nav https://myapp.com/login+pinchtab fill e3 username+pinchtab fill e5 password+pinchtab click e7 # Submit++# Subsequent tests reuse the session+pinchtab nav https://myapp.com/dashboard+pinchtab snap # Already logged in+```++### 4. Report Generation+Create PDFs from web pages:+```bash+pinchtab nav https://analytics.example.com/report+pinchtab pdf -o report.pdf --landscape --displayHeaderFooter+```++### 5. Bot Detection Bypass+Stealth mode fools modern bot detection:+```bash+BRIDGE_STEALTH=full pinchtab+pinchtab nav https://protected-site.com # Bypasses detection+```++---++## Documentation Structure++```+docs/+├── overview.md (you are here)+├── get-started.md ← Start here for quick setup+├── showcase.md ← Practical examples+├── architecture/ ← How it works inside+│ ├── pinchtab-architecture.md+│ ├── chrome-lifecycle-and-orchestration.md+│ └── building.md+├── guides/ ← How-to guides+│ ├── docker.md+│ ├── headed-mode-guide.md+│ ├── cdp-url-shared-chrome.md+│ └── identifying-instances.md+├── references/ ← API documentation+│ ├── cli-commands.md+│ └── curl-commands.md+└── extras/ ← Background reading+ ├── pinchtab-clean-slate.md+ ├── agent-optimization.md+ └── browser-extraction-spectrum.md+```++---++## Support & Community++- **GitHub Issues** — https://github.com/pinchtab/pinchtab/issues+- **Discussions** — https://github.com/pinchtab/pinchtab/discussions+- **Twitter/X** — [@pinchtabdev](https://x.com/pinchtabdev)++---++## Core Concepts (Brief)++### Tab-Centric Design+Every operation works on a tab, not a URL. Create a tab first, then use its `tabId`:++```bash+# Create tab + navigate → returns tabId+curl -X POST http://localhost:9867/tab \+ -d '{"action":"new","url":"https://example.com"}' | jq '.tabId'+# "abc123"++# Use tabId for all operations+curl "http://localhost:9867/snapshot?tabId=abc123"+curl "http://localhost:9867/text?tabId=abc123"+curl -X POST http://localhost:9867/action \+ -d '{"kind":"click","ref":"e5","tabId":"abc123"}'+```++### Refs Instead of Coordinates+The accessibility tree gives you stable refs (e0, e1, e2...) instead of pixel coordinates:++```json+{+ "elements": [+ {"ref": "e0", "role": "heading", "name": "Title"},+ {"ref": "e5", "role": "button", "name": "Click Me"},+ {"ref": "e8", "role": "link", "name": "Learn More"}+ ]+}+```++Then interact by ref:+```bash+curl -X POST http://localhost:9867/action \+ -d '{"kind":"click","ref":"e5"}'+```++### Persistent Sessions+Tabs and cookies survive restarts:++```bash+# Login in one session+pinchtab nav https://example.com/login+pinchtab fill e3 [email protected]+pinchtab fill e5 password+pinchtab click e7++# Restart Pinchtab, tab is still there + still logged in+pkill pinchtab+./pinchtab+# Tab is restored, cookies intact+```++---++## Next Steps++1. **Install:** Follow [get-started.md](get-started.md)+2. **Try it:** Run the quick start examples+3. **Learn:** Read [showcase.md](showcase.md) for workflows+4. **Build:** Check [architecture/](architecture/) for how it works+5. **Deploy:** See [guides/](guides/) for production setups++---++## License++Apache 2.0 — Free and open source.++---++**Ready?** → [Get Started](get-started.md)