tab-agent 0.3.0 → 0.3.2

package/README.md

@@ -1,32 +1,45 @@
 # Tab Agent
 
-**Secure browser control for Claude Code and Codex** — only the tabs you explicitly activate, not your entire browser.
+[![npm version](https://img.shields.io/npm/v/tab-agent.svg)](https://www.npmjs.com/package/tab-agent)
+
+**Give Claude, Codex, or any LLM full control of your browser tabs** — securely, with click-to-activate permission.
 
 ```
 ┌─────────────────┐     ┌─────────────────┐     ┌─────────────────┐
-│  Claude/Codex   │────▶│  Relay Server   │────▶│    Extension    │
-│                 │◀────│   :9876         │◀────│    (Chrome)     │
+│   Claude Code   │────▶│  Relay Server   │────▶│    Extension    │
+│   Codex / LLM   │◀────│   (background)  │◀────│    (Chrome)     │
 └─────────────────┘     └─────────────────┘     └─────────────────┘
-                                                        │
-                                                        ▼
-                                              ┌───────────────────┐
-                                              │  Your Active Tab  │
-                                              │    🟢 ON          │
-                                              └───────────────────┘
+                                                       │
+                                                       ▼
+                                             ┌───────────────────┐
+                                             │  Your Active Tab  │
+                                             │   🟢 Click to ON  │
+                                             └───────────────────┘
 ```
 
+## Features
+
+- **Full browser control** — navigate, click, type, scroll, screenshot, run JavaScript
+- **Uses your login sessions** — access authenticated sites (GitHub, Gmail, X) without sharing credentials
+- **Runs in background** — relay server starts automatically, works while you do other things
+- **Click-to-activate security** — only tabs you explicitly enable, your other tabs stay private
+- **AI-optimized snapshots** — pages converted to readable text with element refs `[e1]`, `[e2]`
+- **Works with any LLM** — Claude Code, Codex, or any tool that can run shell commands
+
+---
+
 ## Quick Start
 
 ```bash
 # 1. Clone and load extension
 git clone https://github.com/DrHB/tab-agent
-# → Open chrome://extensions → Enable Developer mode → Load unpacked → select extension/
+# → Chrome: chrome://extensions → Developer mode → Load unpacked → select extension/
 
 # 2. Setup (auto-detects everything)
 npx tab-agent setup
 
-# 3. Use it
-# → Click Tab Agent icon on a tab (turns green)
+# 3. Activate a tab & go!
+# → Click Tab Agent icon on any tab (turns green = active)
 # → Ask Claude: "Use tab-agent to search Google for 'hello world'"
 ```
 
@@ -42,9 +55,8 @@ npx tab-agent setup
 | **Visibility** | Green badge = active | Hidden/background |
 | **Sessions** | Uses your cookies | Requires re-login |
 | **Credentials** | Never shared | Often required |
-| **Audit** | Full action logging | Varies |
 
-**Click-to-activate model:** Your banking, email, and sensitive tabs stay completely isolated. You always see exactly which tabs AI can control.
+**Click-to-activate model:** Your banking, email, and sensitive tabs stay completely isolated. You always see exactly which tabs the LLM can control.
 
 ### 🍪 Works With Your Login Sessions
 
@@ -55,9 +67,9 @@ Because Tab Agent runs as a Chrome extension:
 - **Works with SSO and 2FA** — enterprise apps, protected accounts
 - **No credential sharing** — your passwords stay in your browser
 
-### 🤖 AI-Optimized
+### 🤖 LLM-Optimized
 
-- **Semantic snapshots** — pages converted to AI-readable text with refs `[e1]`, `[e2]`
+- **Semantic snapshots** — pages converted to readable text with refs `[e1]`, `[e2]`
 - **Screenshot fallback** — for complex dynamic pages
 - **Simple targeting** — click/type using refs instead of fragile CSS selectors
 
@@ -111,7 +123,7 @@ This automatically:
 
 1. Navigate to any webpage
 2. **Click the Tab Agent icon** — it turns green (🟢 ON)
-3. Ask your AI to interact with the page
+3. Ask your LLM to interact with the page
 
 ---
 
@@ -122,56 +134,43 @@ This automatically:
 |---------|-------------|
 | `tabs` | List all activated tabs |
 | `navigate` | Go to a URL |
-| `snapshot` | Get AI-readable page with element refs |
+| `snapshot` | Get page with element refs |
 | `screenshot` | Capture viewport image |
-| `screenshot fullPage` | Capture entire page |
+| `screenshot --full` | Capture entire page |
 
 ### Interaction
 | Command | Description |
 |---------|-------------|
 | `click` | Click element by ref |
 | `type` | Type text into element |
-| `type ... submit` | Type and press Enter |
 | `fill` | Fill a form field |
-| `batchfill` | Fill multiple fields at once |
 | `press` | Press a key (Enter, Escape, Tab, Arrows) |
 
 ### Page Control
 | Command | Description |
 |---------|-------------|
 | `scroll` | Scroll up/down by amount |
-| `scrollintoview` | Scroll element into view |
 | `wait` | Wait for text or element to appear |
 | `evaluate` | Run JavaScript in page context |
-| `dialog` | Handle alert/confirm/prompt |
 
-## CLI Usage
+---
 
-Run commands directly from terminal:
+## CLI Usage
 
 ```bash
+# Setup & Status
+npx tab-agent setup                   # Initial configuration
+npx tab-agent status                  # Check if everything works
+npx tab-agent start                   # Start relay server manually
+
+# Browser Commands
 npx tab-agent tabs                    # List active tabs
-npx tab-agent snapshot                # Get page content
+npx tab-agent snapshot                # Get page content with refs
 npx tab-agent screenshot              # Capture viewport
 npx tab-agent screenshot --full       # Capture full page
 npx tab-agent click e5                # Click element
 npx tab-agent type e3 "hello"         # Type text
-npx tab-agent fill e3 "value"         # Fill field
-npx tab-agent press Enter             # Press key
-npx tab-agent scroll down 500         # Scroll
 npx tab-agent navigate "https://..."  # Go to URL
-npx tab-agent wait "Loading"          # Wait for text
-npx tab-agent evaluate "document.title"  # Run JS
-```
-
----
-
-## CLI Reference
-
-```bash
-npx tab-agent setup   # Initial configuration
-npx tab-agent status  # Check if everything works
-npx tab-agent start   # Start relay server manually
 ```
 
 ---
@@ -208,17 +207,17 @@ Setup automatically detects your browser.
 
 1. **Chrome Extension** — Runs in your browser with access to activated tabs and your session cookies
 
-2. **Relay Server** — Local WebSocket server (port 9876) that bridges AI ↔ Extension via Chrome's Native Messaging API
+2. **Relay Server** — Local WebSocket server that bridges LLM ↔ Extension via Chrome's Native Messaging API (runs in background)
 
-3. **Skill File** — Tells Claude/Codex how to send commands to the relay
+3. **Skill File** — Tells Claude/Codex how to send commands
 
 **Data flow:**
 ```
 You: "Search Google for cats"
  ↓
-Claude/Codex → WebSocket command → Relay Server → Native Messaging → Extension → DOM action
+LLM → CLI command → Relay Server → Native Messaging → Extension → Browser action
  ↑
-Results ← WebSocket response ← Relay Server ← Native Messaging ← Page snapshot
+Results ← Response ← Relay Server ← Native Messaging ← Page snapshot
 ```
 
 ---
@@ -229,4 +228,4 @@ MIT
 
 ---
 
-**Made for [Claude Code](https://claude.ai/code) and [Codex](https://openai.com/codex)**
+**Works with [Claude Code](https://claude.ai/code), [Codex](https://openai.com/codex), and any LLM that can run shell commands.**

package/cli/command.js

@@ -182,16 +182,8 @@ function printScreenshot(msg) {
     console.error('Error:', msg.error);
     return;
   }
-  // Save to file
-  const fs = require('fs');
-  const filename = `/tmp/tab-agent-screenshot-${Date.now()}.png`;
-  const base64Data = msg.screenshot.replace(/^data:image\/png;base64,/, '');
-  fs.writeFileSync(filename, base64Data, 'base64');
-  console.log(`Screenshot saved: ${filename}`);
-
-  // Try to open it
-  const { exec } = require('child_process');
-  exec(`open "${filename}"`, () => {});
+  // Output base64 directly - no file, no auto-open
+  console.log(msg.screenshot);
 }
 
 function printResult(msg) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tab-agent",
-  "version": "0.3.0",
+  "version": "0.3.2",
   "description": "Browser control for Claude Code and Codex via WebSocket",
   "bin": {
     "tab-agent": "./bin/tab-agent.js"

package/skills/claude-code/tab-agent.md

@@ -19,8 +19,6 @@ sleep 2
 ```bash
 npx tab-agent tabs                    # List active tabs
 npx tab-agent snapshot                # Get page with refs [e1], [e2]...
-npx tab-agent screenshot              # Capture viewport
-npx tab-agent screenshot --full       # Capture full page
 npx tab-agent click <ref>             # Click element
 npx tab-agent type <ref> <text>       # Type text
 npx tab-agent fill <ref> <value>      # Fill form field
@@ -28,15 +26,19 @@ npx tab-agent press <key>             # Press key (Enter, Escape, Tab)
 npx tab-agent scroll <dir> [amount]   # Scroll up/down
 npx tab-agent navigate <url>          # Go to URL
 npx tab-agent wait <text|selector>    # Wait for condition
-npx tab-agent evaluate <script>       # Run JavaScript
+npx tab-agent screenshot              # Capture viewport (fallback only)
+npx tab-agent screenshot --full       # Capture full page (fallback only)
 ```
 
-## Usage
+## Workflow
 
-1. `tabs` -> find active tab
-2. `snapshot` -> read page, get element refs [e1], [e2]...
-3. `click`/`type`/`fill` using refs
-4. If snapshot incomplete -> `screenshot` and analyze visually
+1. `snapshot` first - always start here to get element refs
+2. Use refs [e1], [e2]... with `click`/`type`/`fill`
+3. `snapshot` again after actions to see results
+4. **Only use `screenshot` if:**
+   - Snapshot is missing expected content
+   - Page has complex visuals (charts, images, canvas)
+   - Debugging why an action didn't work
 
 ## Examples
 
@@ -46,14 +48,15 @@ npx tab-agent navigate "https://google.com"
 npx tab-agent snapshot
 npx tab-agent type e1 "hello world"
 npx tab-agent press Enter
+npx tab-agent snapshot  # See results
 
-# Read page content
-npx tab-agent snapshot
+# Only screenshot if snapshot doesn't show what you need
 npx tab-agent screenshot --full
 ```
 
 ## Notes
 
-- Screenshot saves to /tmp/ and opens automatically
 - Refs reset on each snapshot - always snapshot before interacting
 - Keys: Enter, Escape, Tab, Backspace, ArrowUp/Down/Left/Right
+- Screenshot outputs base64 to stdout (no file saved)
+- Prefer snapshot over screenshot - it's faster and text-based

package/skills/codex/tab-agent.md

@@ -16,19 +16,23 @@ curl -s http://localhost:9876/health || (npx tab-agent start &)
 ## Commands
 
 ```bash
-tabs                         # List active tabs
-snapshot                     # Page with refs [e1], [e2]...
-screenshot [--full]          # Capture viewport/full page
-click <ref>                  # Click element
-type <ref> <text>            # Type text
-fill <ref> <value>           # Fill form field
-press <key>                  # Enter/Escape/Tab/Arrow*
-scroll <dir> [amount]        # Scroll up/down
-navigate <url>               # Go to URL
-wait <text|selector>         # Wait for condition
-evaluate <script>            # Run JavaScript
+npx tab-agent tabs              # List active tabs
+npx tab-agent snapshot          # Page with refs [e1], [e2]...
+npx tab-agent click <ref>       # Click element
+npx tab-agent type <ref> <text> # Type text
+npx tab-agent fill <ref> <val>  # Fill form field
+npx tab-agent press <key>       # Enter/Escape/Tab/Arrow*
+npx tab-agent scroll <dir> [n]  # Scroll up/down
+npx tab-agent navigate <url>    # Go to URL
+npx tab-agent wait <text|sel>   # Wait for condition
+npx tab-agent screenshot        # Fallback only - if snapshot incomplete
 ```
 
-## Flow
+## Workflow
 
-`snapshot` -> `click`/`type` -> repeat. Use `screenshot` if snapshot incomplete.
+1. Always `snapshot` first - get refs [e1], [e2]...
+2. `click`/`type`/`fill` using refs
+3. `snapshot` again to see results
+4. **Only screenshot if snapshot missing content** (charts, canvas, debugging)
+
+Prefer snapshot over screenshot - faster and text-based.