tab-agent 0.3.4 → 0.4.1

package/CHANGELOG.md

@@ -0,0 +1,39 @@
+# Changelog
+
+## [0.4.1] - 2026-03-15
+
+### Fixed
+- `setup` now installs the native host into a stable user-library location instead of pointing Chrome at the repo checkout
+- Native host installation now copies the `ws` dependency from the packaged install, so fresh npm installs can launch reliably
+- Relay server now accepts the current Chrome native-host client identifier, fixing cases where Chrome was connected but commands could not see an active browser
+
+### Docs
+- README now treats `status` as part of the setup flow and documents the native-host recovery steps that go with the new install path
+
+## [0.4.0] - 2026-03-14
+
+### Added
+- Auto-launch Chrome with profile detection, saved defaults, and `--profile`
+- New browser commands: `hover`, `select`, `drag`, `get`, `find`, `cookies`, `storage`, and `pdf`
+- Experimental Safari support with browser selection flags
+- Auto-activate toggle and bulk activation support in the extension popup
+
+### Fixed
+- Published packages now ship a real `extension/manifest.json` for unpacked Chrome installs
+- Setup can auto-detect unpacked Tab Agent extensions from Chrome profile preferences
+- Status output shows the detected extension path and native host path for easier debugging
+- README install steps now call out `@latest` usage to avoid stale cached `npx` installs
+
+## [0.1.0] - 2026-01-30
+
+### Added
+- Chrome extension (Manifest V3)
+- WebSocket relay server
+- Native messaging host
+- AI-readable page snapshots
+- DOM actions: click, type, fill, press, select, hover, scroll
+- Screenshot capture
+- Multi-tab support
+- Audit logging
+- Claude Code skill
+- Codex skill

package/README.md

@@ -1,9 +1,16 @@
+![Tab Agent](./banner-pixel-1.svg)
+
 # Tab Agent
 
 [![npm version](https://img.shields.io/npm/v/tab-agent.svg)](https://www.npmjs.com/package/tab-agent)
+[![Chrome](https://img.shields.io/badge/Chrome-Extension-4285F4?logo=googlechrome&logoColor=white)](https://github.com/DrHB/tab-agent)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 
-**Browser control for Claude Code and Codex** — click-to-activate security.
+**Let Claude & Codex browse as YOU** — uses your existing logins, click-to-activate security.
+
+> No headless browser. No re-authenticating. Your AI uses your actual Chrome sessions.
+>
+> **Safari support is experimental** — [see below](#experimental-safari-support)
 
 ```
 ┌─────────────────┐     ┌─────────────────┐     ┌─────────────────┐
@@ -18,30 +25,68 @@
                                              └───────────────────┘
 ```
 
+## Why Tab Agent?
+
+Most browser automation tools (Playwright, Puppeteer, agent-browser) spin up a **fresh headless browser** — you start logged out of everything, and many sites actively block them. They detect headless browsers through missing plugins, `navigator.webdriver` flags, and other fingerprints.
+
+Tab Agent is different — it uses your real Chrome with your real cookies:
+
+```
++---------------+--------------------------------------+----------------------------------+
+|               | Tab Agent                            | Headless Browsers                |
++---------------+--------------------------------------+----------------------------------+
+| Your logins   | (+) Uses existing sessions           | (-) Must re-authenticate         |
+| Security      | (+) Click to activate specific tabs  | (-) Full browser access          |
+| Privacy       | (+) Credentials never leave browser  | (-) Agent sees everything        |
+| Detection     | (+) Real browser, real cookies       | (-) Often blocked by anti-bot    |
+| Setup         | (+) Uses your Chrome                 | (-) Downloads separate browser   |
+| Visibility    | (+) Watch in real browser            | (-) Runs hidden/headless         |
++---------------+--------------------------------------+----------------------------------+
+```
+
+**Use Tab Agent when:** Claude or Codex needs to browse as "you" — shopping with your Prime account, checking your GitHub notifications, using sites you're already logged into.
+
+**Use headless browsers when:** CI/CD automation, web scraping, or testing with fresh sessions.
+
 ## Features
 
-- **Full browser control** — navigate, click, type, scroll, screenshot, run JavaScript
+- **Full browser control** — navigate, click, type, scroll, hover, drag, screenshot, PDF, run JavaScript
 - **Uses your login sessions** — access GitHub, Gmail, Amazon without sharing credentials
-- **Runs in background** — relay starts automatically, works while you do other things
+- **Runs in background** — run `npx tab-agent@latest start` once, then use commands while it stays running
 - **Click-to-activate security** — only tabs you explicitly enable, others stay private
 - **AI-optimized snapshots** — pages converted to text with refs `[e1]`, `[e2]` for easy targeting
 - **Works with Claude Code & Codex** — installs skills automatically
+- **Auto-launches Chrome** — starts Chrome with profile selection if not already running
 
 ## Quick Start
 
 ```bash
-# 1. Install extension
+# 1. Get the extension files
 git clone https://github.com/DrHB/tab-agent
+cd tab-agent
 # Chrome: chrome://extensions → Developer mode → Load unpacked → select extension/
+# The extension/ folder must contain manifest.json
 
 # 2. Setup
-npx tab-agent setup
+npx tab-agent@latest setup
+
+# 3. Start relay
+npx tab-agent@latest start
+
+# 4. Verify wiring
+npx tab-agent@latest status
 
-# 3. Activate & go
+# 5. Activate & go
 # Click extension icon on any tab (turns green)
-# Ask Claude: "Search Amazon for mechanical keyboards and find the best rated"
+# Ask Claude/Codex: "Search Amazon for mechanical keyboards and find the best rated"
 ```
 
+If you have an older cached `npx` install, keep using `@latest` for `setup`, `start`, and `status` so the CLI/runtime matches the current extension release.
+
+<p align="center">
+  <img src="assets/toggle-demo.gif" alt="Pin extension and toggle on/off" width="600">
+</p>
+
 ## Example Tasks
 
 ```bash
@@ -70,15 +115,41 @@ npx tab-agent click <ref>             # Click element (e.g., click e5)
 npx tab-agent type <ref> <text>       # Type into element
 npx tab-agent fill <ref> <value>      # Fill form field
 
-# Navigation
+# Navigation & interaction
 npx tab-agent navigate <url>          # Go to URL
 npx tab-agent scroll <dir> [amount]   # Scroll up/down
 npx tab-agent press <key>             # Press key (Enter, Escape, Tab)
+npx tab-agent hover <ref>             # Hover over element
+npx tab-agent select <ref> <value>    # Select dropdown option
+npx tab-agent drag <from> <to>        # Drag and drop between elements
+
+# Data extraction
+npx tab-agent get text <ref>          # Get element text
+npx tab-agent get value <ref>         # Get input value
+npx tab-agent get attr <ref> href     # Get element attribute
+npx tab-agent get url                 # Get current URL
+npx tab-agent get title               # Get page title
+
+# Semantic locators
+npx tab-agent find text "Submit"      # Find elements by text
+npx tab-agent find role button        # Find by ARIA role
+npx tab-agent find label "Email"      # Find by label text
+npx tab-agent find placeholder "Search" # Find by placeholder
 
 # Utilities
 npx tab-agent tabs                    # List active tabs
 npx tab-agent wait <text>             # Wait for text to appear
-npx tab-agent screenshot              # Capture page (fallback for complex UIs)
+npx tab-agent wait --url <pattern>    # Wait for URL to match
+npx tab-agent wait --visible <ref>    # Wait for element to be visible
+npx tab-agent screenshot [--full]     # Capture page (fallback for complex UIs)
+npx tab-agent pdf [filename.pdf]      # Save page as PDF
+npx tab-agent evaluate <script>       # Run JavaScript
+npx tab-agent cookies get             # View cookies
+npx tab-agent cookies clear           # Clear cookies
+npx tab-agent storage get [key]       # Read localStorage
+npx tab-agent storage set <key> <val> # Write localStorage
+npx tab-agent storage remove <key>    # Remove localStorage key (or use rm)
+npx tab-agent storage clear           # Clear localStorage
 ```
 
 **Workflow:** `snapshot` → use refs → `click`/`type` → `snapshot` again → repeat
@@ -89,35 +160,130 @@ npx tab-agent screenshot              # Capture page (fallback for complex UIs)
 
 ```bash
 git clone https://github.com/DrHB/tab-agent
+cd tab-agent
 ```
 
 1. Open `chrome://extensions`
 2. Enable **Developer mode** (top right)
 3. Click **Load unpacked**
 4. Select the `extension/` folder
+5. Confirm the folder contains `extension/manifest.json`
 
 ### 2. Run Setup
 
 ```bash
-npx tab-agent setup
+npx tab-agent@latest setup
 ```
 
-This auto-detects your extension and configures everything.
+This auto-detects unpacked and installed Tab Agent extensions, copies the native host into a stable per-user directory, and configures everything.
 
-### 3. Activate Tabs
+### 3. Start Relay
+
+```bash
+npx tab-agent@latest start
+```
+
+Keep this running in a terminal while you use `tab-agent` commands.
+
+### 4. Check Status
+
+```bash
+npx tab-agent@latest status
+```
+
+Confirm that all three pieces are healthy before you start driving the browser:
+
+- Native Host: Installed
+- Extension: Detected
+- Relay Server: Running
+
+### 5. Activate Tabs
 
 Click the Tab Agent icon on any tab you want to control. Green = active.
 
-## Security Model
+## Auto-Launch Chrome
+
+When you run `npx tab-agent@latest start`, Chrome is automatically launched if it's not already running. You'll be prompted to select which Chrome profile to use:
+
+```
+Chrome is not running.
+
+Chrome Profiles:
+  1. Person 1 (Default)
+  2. Work (Profile 1)
+  3. Personal (Profile 2)
 
-| Feature | Tab Agent | Traditional Automation |
-|---------|--------------|----------------------|
-| **Access** | Only tabs you click to activate | Entire browser |
-| **Sessions** | Uses your cookies | Requires credentials |
-| **Visibility** | Green badge shows active tabs | Hidden/background |
-| **Control** | You choose what AI can access | Full access by default |
+Select profile [1-3]:
+```
+
+### Non-Interactive Mode
+
+Skip the prompt with the `--profile` flag:
+
+```bash
+npx tab-agent@latest start --profile="Profile 1"
+npx tab-agent@latest start --profile="Work"
+```
+
+The flag matches by profile name or directory name (case-insensitive). If Chrome is already running, the prompt is skipped entirely.
+
+## Experimental Safari Support
+
+> **Note:** Safari support is experimental and requires source build steps. Relay + CLI routing work, but Safari packaging is still manual in Xcode.
+
+### Prerequisites
+
+- macOS 14+ (Sonoma or later)
+- Xcode 15+ (free from App Store)
+- Node.js 18+
+
+### Setup Steps
+
+1. **Start the relay server** (in a terminal):
+   ```bash
+   npx tab-agent@latest start
+   ```
+
+2. **Open the Safari Swift package in Xcode**:
+   ```bash
+   open -a Xcode safari/Package.swift
+   ```
+
+3. **Create/configure a Safari Web Extension target in Xcode**:
+   - File → New → Target → Safari Web Extension
+   - Point it to the shared extension assets in `extension/`
+   - Use `extension/manifest.safari.json` settings as the Safari manifest baseline
 
-Your banking, email, and sensitive tabs stay completely isolated unless you explicitly activate them.
+4. **Run the app target**:
+   - Click "Run" in Xcode (⌘R)
+
+5. **Enable the extension in Safari**:
+   - Safari → Settings → Extensions
+   - Check "Tab Agent"
+
+6. **Enable unsigned extensions** (required after each Safari restart):
+   - Safari → Develop → Allow Unsigned Extensions
+
+7. **Test the connection**:
+   ```bash
+   npx tab-agent tabs --browser=safari
+   ```
+
+### Using with Both Browsers
+
+If you have both Chrome and Safari set up:
+
+```bash
+# Auto-detect (uses whichever has activated tabs)
+npx tab-agent snapshot
+
+# Explicitly target a browser
+npx tab-agent snapshot --browser=safari
+npx tab-agent snapshot --browser=chrome
+
+# See tabs from all browsers
+npx tab-agent tabs
+```
 
 ## Supported Browsers
 
@@ -125,16 +291,29 @@ Your banking, email, and sensitive tabs stay completely isolated unless you expl
 - Brave
 - Microsoft Edge
 - Chromium
+- Safari (experimental, manual source setup)
 
 ## Troubleshooting
 
 **Extension not detected?**
 - Make sure Developer mode is enabled in chrome://extensions
 - Reload the extension
+- Run `npx tab-agent@latest setup` again after reloading so the native host is paired to the current extension ID
 
 **Commands not working?**
+- Make sure relay is running: `npx tab-agent@latest start`
 - Click the extension icon — must show green "ON"
-- Run `npx tab-agent status` to check configuration
+- Run `npx tab-agent@latest status` to check configuration
+
+**Popup says "Native host has exited"?**
+- Make sure the relay is running: `npx tab-agent@latest start`
+- Reload the extension in `chrome://extensions`
+- Run `npx tab-agent@latest status` to confirm the native host path and relay status
+- If the extension ID changed, run `npx tab-agent@latest setup` again so Chrome is paired to the current extension
+
+**Fresh machine install still acting like an older release?**
+- Use `npx tab-agent@latest setup`, `npx tab-agent@latest start`, and `npx tab-agent@latest status` to bypass stale cached `npx` installs
+- Make sure the unpacked extension and the CLI/runtime come from the same release family
 
 **No active tabs?**
 - Activate at least one tab by clicking the extension icon
@@ -142,7 +321,7 @@ Your banking, email, and sensitive tabs stay completely isolated unless you expl
 ## How It Works
 
 1. **Chrome Extension** — Injects into activated tabs, captures DOM snapshots
-2. **Relay Server** — Bridges AI ↔ Extension via Chrome Native Messaging (runs in background)
+2. **Relay Server** — Bridges AI ↔ Extension via native messaging (run with `npx tab-agent@latest start`)
 3. **CLI** — Simple commands for Claude Code and Codex
 
 ```
@@ -158,7 +337,3 @@ Claude → npx tab-agent navigate "google.com/flights"
 ## License
 
 MIT
-
----
-
-**Keywords:** browser automation, claude code, codex, AI browser control, web automation, puppeteer alternative, playwright alternative

package/bin/tab-agent.js

@@ -1,8 +1,9 @@
 #!/usr/bin/env node
 const command = process.argv[2];
+const hasHelpFlag = process.argv.includes('--help') || process.argv.includes('-h');
 
 // Commands that go to the command module
-const BROWSER_COMMANDS = ['tabs', 'snapshot', 'screenshot', 'click', 'type', 'fill', 'press', 'scroll', 'navigate', 'wait', 'evaluate'];
+const BROWSER_COMMANDS = ['tabs', 'snapshot', 'screenshot', 'click', 'type', 'fill', 'press', 'scroll', 'navigate', 'wait', 'evaluate', 'hover', 'select', 'drag', 'get', 'find', 'cookies', 'storage', 'pdf'];
 
 if (command === '-v' || command === '--version') {
   console.log(require('../package.json').version);
@@ -13,6 +14,9 @@ if (BROWSER_COMMANDS.includes(command)) {
   const { runCommand } = require('../cli/command.js');
   runCommand(process.argv.slice(2));
 } else {
+  if (hasHelpFlag) {
+    showHelp(0);
+  }
   switch (command) {
     case 'setup':
       require('../cli/setup.js');
@@ -28,9 +32,9 @@ if (BROWSER_COMMANDS.includes(command)) {
   }
 }
 
-function showHelp() {
+function showHelp(exitCode = null) {
   console.log(`
-tabpilot - Give LLMs full control of your browser
+tab-agent - Give LLMs full control of your browser
 
 Setup:
   setup    Auto-detect extension, configure native messaging
@@ -48,18 +52,29 @@ Browser Control:
   tabs                      List active tabs
   wait <text|selector>      Wait for text or element
   screenshot [--full]       Capture page (fallback)
+  hover <ref>               Hover over element
+  select <ref> <value>      Select dropdown option
+  drag <from> <to>          Drag element to another
+  get <prop> [ref] [attr]   Get text, value, attr, url, title
+  find <by> <query>         Find by text, role, label, placeholder, selector
+  cookies <get|clear>       View or clear cookies
+  storage <get|set|remove|rm|clear> Manage localStorage/sessionStorage
+  pdf [filename.pdf]        Save page as PDF
 
 Workflow: snapshot → click/type → snapshot → repeat
 
 Examples:
-  npx tabpilot setup
-  npx tabpilot snapshot
-  npx tabpilot click e5
-  npx tabpilot type e3 "hello world"
-  npx tabpilot navigate "https://google.com"
+  npx tab-agent setup
+  npx tab-agent snapshot
+  npx tab-agent click e5
+  npx tab-agent type e3 "hello world"
+  npx tab-agent navigate "https://google.com"
 
 Version: ${require('../package.json').version}
 `);
+  if (typeof exitCode === 'number') {
+    process.exit(exitCode);
+  }
   if (command && command !== 'help' && command !== '--help' && command !== '-h') {
     process.exit(1);
   }

package/cli/command.js

@@ -1,9 +1,23 @@
 // cli/command.js
 const WebSocket = require('ws');
 
-const COMMANDS = ['tabs', 'snapshot', 'screenshot', 'click', 'type', 'fill', 'press', 'scroll', 'navigate', 'wait', 'evaluate'];
+const COMMANDS = ['tabs', 'snapshot', 'screenshot', 'click', 'type', 'fill', 'press', 'scroll', 'navigate', 'wait', 'evaluate', 'hover', 'select', 'drag', 'get', 'find', 'cookies', 'storage', 'pdf'];
 
 async function runCommand(args) {
+  // Extract --browser flag
+  let targetBrowser = null;
+  const browserFlagIndex = args.findIndex(a => a === '--browser' || a.startsWith('--browser='));
+  if (browserFlagIndex !== -1) {
+    const flag = args[browserFlagIndex];
+    if (flag.includes('=')) {
+      targetBrowser = flag.split('=')[1];
+    } else if (args[browserFlagIndex + 1]) {
+      targetBrowser = args[browserFlagIndex + 1];
+      args.splice(browserFlagIndex + 1, 1);
+    }
+    args.splice(browserFlagIndex, 1);
+  }
+
   const [command, ...params] = args;
 
   if (!command || command === 'help') {
@@ -37,10 +51,10 @@ async function runCommand(args) {
 
     // First get tabs to find tabId
     if (command === 'tabs') {
-      ws.send(JSON.stringify({ id: 1, action: 'tabs' }));
+      ws.send(JSON.stringify({ id: 1, action: 'tabs', browser: targetBrowser }));
     } else {
       // Get active tab first, then run command
-      ws.send(JSON.stringify({ id: 0, action: 'tabs' }));
+      ws.send(JSON.stringify({ id: 0, action: 'tabs', browser: targetBrowser }));
     }
   });
 
@@ -57,7 +71,7 @@ async function runCommand(args) {
 
       const tabId = msg.tabs[0].tabId;
       const payload = buildPayload(command, params, tabId);
-      ws.send(JSON.stringify({ id: 1, ...payload }));
+      ws.send(JSON.stringify({ id: 1, ...payload, browser: targetBrowser }));
       return;
     }
 
@@ -69,6 +83,10 @@ async function runCommand(args) {
         printSnapshot(msg);
       } else if (command === 'screenshot') {
         printScreenshot(msg);
+      } else if (command === 'pdf') {
+        printPdf(msg);
+      } else if (command === 'find') {
+        printFind(msg);
       } else {
         printResult(msg);
       }
@@ -108,10 +126,14 @@ function buildPayload(command, params, tabId) {
       payload.url = params[0];
       break;
     case 'wait':
-      if (params[0]?.startsWith('.') || params[0]?.startsWith('#')) {
+      if (params[0] === '--url') {
+        payload.urlPattern = params[1];
+      } else if (params[0] === '--visible') {
+        payload.visibleRef = params[1];
+      } else if (params[0]?.startsWith('.') || params[0]?.startsWith('#')) {
         payload.selector = params[0];
       } else {
-        payload.text = params.join(' ');
+        payload.text = params.filter(p => !/^\d+$/.test(p)).join(' ');
       }
       payload.timeout = parseInt(params.find(p => /^\d+$/.test(p))) || 5000;
       break;
@@ -123,6 +145,39 @@ function buildPayload(command, params, tabId) {
         payload.fullPage = true;
       }
       break;
+    case 'hover':
+      payload.ref = params[0];
+      break;
+    case 'select':
+      payload.ref = params[0];
+      payload.value = params.slice(1).join(' ');
+      break;
+    case 'drag':
+      payload.fromRef = params[0];
+      payload.toRef = params[1];
+      break;
+    case 'get':
+      payload.subcommand = params[0]; // text, html, value, attr, url, title
+      payload.ref = params[1];
+      payload.attr = params[2]; // for get attr <ref> <name>
+      break;
+    case 'find':
+      payload.by = params[0]; // text, role, label, placeholder, selector
+      payload.query = params.slice(1).join(' ');
+      break;
+    case 'cookies':
+      payload.subcommand = params[0]; // get, clear
+      break;
+    case 'storage':
+      payload.subcommand = params[0] === 'rm' ? 'remove' : params[0]; // get, set, remove, clear
+      payload.storageType = params.includes('--session') ? 'session' : 'local';
+      // Filter out --session flag
+      const storageParams = params.filter(p => p !== '--session');
+      payload.key = storageParams[1];
+      payload.value = storageParams.slice(2).join(' ');
+      break;
+    case 'pdf':
+      break;
   }
 
   return payload;
@@ -146,14 +201,32 @@ Commands:
   wait <text|selector>      Wait for text or element
   screenshot [--full]       Capture page (fallback)
   evaluate <script>         Run JavaScript
+  hover <ref>               Hover over element
+  select <ref> <value>      Select dropdown option
+  drag <from> <to>          Drag element to another
+  get <prop> [ref] [attr]   Get text, value, attr, url, title
+  find <by> <query>         Find by text, role, label, placeholder, selector
+  cookies <get|clear>       View or clear cookies
+  storage <get|set|remove|rm|clear> Manage localStorage/sessionStorage
+  pdf [filename.pdf]        Save page as PDF
+
+Options:
+  --browser=<chrome|safari>   Target specific browser
 
 Workflow: snapshot → click/type → snapshot → repeat
 
 Examples:
   npx tab-agent snapshot
   npx tab-agent click e5
-  npx tab-agent type e3 "hello world"
-  npx tab-agent navigate "https://google.com"
+  npx tab-agent get text e3
+  npx tab-agent find text "Submit"
+  npx tab-agent find role button
+  npx tab-agent pdf page.pdf
+  npx tab-agent drag e1 e5
+  npx tab-agent hover e3
+  npx tab-agent select e7 "Option 2"
+  npx tab-agent cookies get
+  npx tab-agent storage get myKey
 `);
 }
 
@@ -164,7 +237,8 @@ function printTabs(msg) {
   }
   console.log('Active tabs:\n');
   msg.tabs.forEach((tab, i) => {
-    console.log(`  ${i + 1}. [${tab.tabId}] ${tab.title}`);
+    const browserTag = tab.browser ? `[${tab.browser}] ` : '';
+    console.log(`  ${i + 1}. ${browserTag}[${tab.tabId}] ${tab.title}`);
     console.log(`     ${tab.url}\n`);
   });
 }
@@ -186,6 +260,36 @@ function printScreenshot(msg) {
   console.log(msg.screenshot);
 }
 
+function printPdf(msg) {
+  if (!msg.ok) {
+    console.error('Error:', msg.error);
+    return;
+  }
+  // Check if a filename was given via params
+  const outFile = process.argv.find(a => a.endsWith('.pdf'));
+  if (outFile) {
+    require('fs').writeFileSync(outFile, Buffer.from(msg.pdf, 'base64'));
+    console.log(`PDF saved to ${outFile}`);
+  } else {
+    console.log(msg.pdf);
+  }
+}
+
+function printFind(msg) {
+  if (!msg.ok) {
+    console.error('Error:', msg.error);
+    return;
+  }
+  if (msg.results.length === 0) {
+    console.log('No matches found.');
+    return;
+  }
+  console.log(`Found ${msg.count} match${msg.count !== 1 ? 'es' : ''}:\n`);
+  msg.results.forEach(r => {
+    console.log(`  [${r.ref}] ${r.role} "${r.name}"`);
+  });
+}
+
 function printResult(msg) {
   if (!msg.ok) {
     console.error('Error:', msg.error);