High-performance browser automation bridge and multi-instance orchestrator with advanced stealth injection and real-time dashboard.
docs: simplify overview — remove comparisons, use cases, getting started links; focus on core concepts
Mariofbddae4b83af
diff --git a/docs/overview.md b/docs/overview.mdindex 508c5486..e950d1ff 100644--- a/docs/overview.md+++ b/docs/overview.md@@ -29,117 +29,38 @@ curl -s -X POST http://localhost:9867/action \----## Why PinchTab?+## Core Characteristics-### 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)+- **Tab-Centric** — Everything revolves around tabs, not URLs+- **Stateful** — Sessions persist between requests. Log in once, stay logged in across restarts+- **Token Inexpensive** — Text extraction at 800 tokens/page (5-13x cheaper than full snapshots)+- **Flexible Modes** — Run headless, headed, with browser profiles, or connect to external Chrome via CDP+- **Monitoring & Control** — Tab locking for multi-agent safety, stealth mode for bot detection bypass---## 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--```text-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--```text-Navigate + snapshot: 1-3 seconds-Click + verify: 200-500ms-Text extraction: 100-300ms-PDF generation: 2-5 seconds-```--### Binary Size--```text-PinchTab: 12MB (includes Chrome)-Node.js equivalent: 100MB+-Python equivalent: 200MB+-```+- 🌲 **Accessibility Tree** — Structured DOM with stable refs (e0, e1...) for click, type, read. No coordinate guessing.+- 🎯 **Smart Filters** — `?filter=interactive` returns only buttons, links, inputs. Fewer tokens per snapshot.+- 🕵️ **Stealth Mode** — Patches `navigator.webdriver`, spoofs UA, hides automation flags for bot detection bypass.+- 📝 **Text Extraction** — Readability mode (clean) or raw (full HTML). Choose based on workflow.+- 🖱️ **Direct Actions** — Click, type, fill, press, focus, hover, select, scroll by ref or selector.+- ⚡ **JavaScript Execution** — Run arbitrary JS in any tab. Escape hatch for workflow gaps.+- 📸 **Screenshots** — JPEG output with quality control.+- 📄 **PDF Export** — Full pages to PDF with headers, footers, landscape mode.+- 🎭 **Multi-Tab** — Create, switch, close tabs. Work with multiple pages concurrently.---## Architecture-### High-Level Design+PinchTab sits between your tools/agents and Chrome:```text┌─────────────────────────────────────────┐│ Your Tool/Agent │-│ (curl, Python, Node.js, etc.) │+│ (CLI, curl, Python, Node.js, etc.) │└──────────────┬──────────────────────────┘││ HTTP@@ -147,231 +68,97 @@ Python equivalent: 200MB+┌─────────────────────────────────────────┐│ PinchTab HTTP Server (Go) ││ ┌─────────────────────────────────┐ │-│ │ Tab Manager (multi-tab) │ │-│ │ ┌────────────┐ ┌────────────┐ │ │-│ │ │ Tab 1 │ │ Tab 2 │ │ │-│ │ │ DOM │ │ DOM │ │ │-│ │ │ History │ │ History │ │ │-│ │ └────────────┘ └────────────┘ │ │+│ │ Tab Manager │ │+│ │ (tracks tabs + sessions) │ ││ └─────────────────────────────────┘ ││ ┌─────────────────────────────────┐ │-│ │ Chrome DevTools Protocol │ │-│ │ (WebSocket to Chrome) │ │+│ │ Chrome DevTools Protocol (CDP) │ ││ └─────────────────────────────────┘ │└──────────────┬──────────────────────────┘│- │ CDP+ │ CDP WebSocket↓┌─────────────────────────────────────────┐-│ Chrome Browser (Headless) │-│ ┌────────────┐ ┌────────────┐ │-│ │ Tab 1 │ │ Tab 2 │ │-│ │ (website) │ │ (website) │ │-│ └────────────┘ └────────────┘ │+│ Chrome Browser │+│ (Headless, headed, or external) │└─────────────────────────────────────────┘```-### 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+## Core Concepts-### 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-```+### Tab-Centric Design-### 4. Report Generation-Create PDFs from web pages:-```bash-pinchtab nav https://analytics.example.com/report-pinchtab pdf -o report.pdf --landscape --displayHeaderFooter-```+Every operation targets a specific tab by `tabId`. Create a tab first:-### 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--```text-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+curl -X POST http://localhost:9867/tab \+ -d '{"action":"new","url":"https://example.com"}' | jq '.tabId'+# Returns: "abc123"```------## 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`:+Then use that `tabId` for all subsequent operations:```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"}'+# Snapshot: curl "http://localhost:9867/snapshot?tabId=abc123"+# Text: curl "http://localhost:9867/text?tabId=abc123"+# Action: 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:++The accessibility tree provides **stable element references** 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"}+ {"ref": "e5", "role": "button", "name": "Submit"},+ {"ref": "e8", "role": "input", "name": "Email"}]}```-Then interact by ref:+Click or interact by ref:+```bashcurl -X POST http://localhost:9867/action \- -d '{"kind":"click","ref":"e5"}'+ -d '{"kind":"click","ref":"e5","tabId":"abc123"}'```### Persistent Sessions-Tabs and cookies survive restarts:++Tabs, cookies, and login state survive server restarts:```bash-# Login in one session+# Loginpinchtab nav https://example.com/loginpinchtab fill e3 [email protected]pinchtab fill e5 passwordpinchtab click e7-# Restart PinchTab, tab is still there + still logged in+# Restart the serverpkill pinchtab+sleep 2./pinchtab-# Tab is restored, cookies intact++# Tab is restored, still logged in+pinchtab nav https://example.com/dashboard+pinchtab snap # Works without re-login```----## Next Steps+## Support & Community-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+- **GitHub Issues** — https://github.com/pinchtab/pinchtab/issues+- **Discussions** — https://github.com/pinchtab/pinchtab/discussions+- **Twitter/X** — [@pinchtabdev](https://x.com/pinchtabdev)---## LicenseApache 2.0 — Free and open source.-------**Ready?** → [Get Started](get-started.md)