tab-agent 0.2.0

package/README.md

@@ -0,0 +1,62 @@
+# Tab Agent
+
+Secure tab-level browser control for Claude Code and Codex — only the tabs you explicitly activate, not your entire browser.
+
+## Install
+
+### 1. Load Extension
+```bash
+git clone https://github.com/DrHB/tab-agent
+```
+
+1. Open `chrome://extensions`
+2. Enable **Developer mode**
+3. Click **Load unpacked** → select `extension/` folder
+
+### 2. Setup
+```bash
+npx tab-agent setup
+```
+
+That's it! The setup auto-detects your extension and configures everything.
+
+## Use
+
+1. Click Tab Agent icon on any tab (turns green = active)
+2. Ask Claude/Codex: "Use tab-agent to search Google for 'hello world'"
+
+## Commands
+
+| Command | Description |
+|---------|-------------|
+| `tabs` | List activated tabs |
+| `snapshot` | Get AI-readable page with refs [e1], [e2]... |
+| `screenshot` | Capture viewport (or `fullPage: true` for full page) |
+| `click` | Click element by ref |
+| `fill` | Fill form field |
+| `type` | Type text (with optional `submit: true`) |
+| `press` | Press key (Enter, Escape, Tab, Arrow*) |
+| `scroll` | Scroll page |
+| `scrollintoview` | Scroll element into view |
+| `navigate` | Go to URL |
+| `wait` | Wait for text or selector |
+| `evaluate` | Run JavaScript in page context |
+| `batchfill` | Fill multiple fields at once |
+| `dialog` | Handle alert/confirm/prompt |
+
+## Manual Commands
+
+```bash
+npx tab-agent status  # Check configuration
+npx tab-agent start   # Start relay manually
+```
+
+## Architecture
+
+```
+Claude/Codex → WebSocket:9876 → Relay → Native Messaging → Extension → DOM
+```
+
+## License
+
+MIT

package/bin/tab-agent.js

@@ -0,0 +1,40 @@
+#!/usr/bin/env node
+const command = process.argv[2];
+const pkg = require('../package.json');
+
+function showHelp() {
+  console.log(`
+tab-agent - Browser control for Claude/Codex
+
+Commands:
+  setup   Auto-detect extension, register native host, install skills
+  start   Start the relay server
+  status  Check configuration status
+
+Usage:
+  npx tab-agent setup
+  npx tab-agent start
+`);
+}
+
+switch (command) {
+  case 'setup':
+    require('../cli/setup.js');
+    break;
+  case 'start':
+    require('../cli/start.js');
+    break;
+  case 'status':
+    require('../cli/status.js');
+    break;
+  case '-v':
+  case '--version':
+    console.log(pkg.version);
+    break;
+  case undefined:
+    showHelp();
+    break;
+  default:
+    showHelp();
+    process.exit(1);
+}

package/cli/detect-extension.js

@@ -0,0 +1,131 @@
+// cli/detect-extension.js
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+
+// Support multiple browsers: Chrome, Brave, Edge, Chromium
+function getAllBrowserExtensionPaths() {
+  const platform = os.platform();
+  const home = os.homedir();
+  const paths = [];
+
+  if (platform === 'darwin') {
+    const base = path.join(home, 'Library/Application Support');
+    paths.push(
+      path.join(base, 'Google/Chrome'),
+      path.join(base, 'Google/Chrome Canary'),
+      path.join(base, 'Chromium'),
+      path.join(base, 'BraveSoftware/Brave-Browser'),
+      path.join(base, 'Microsoft Edge'),
+    );
+  } else if (platform === 'linux') {
+    paths.push(
+      path.join(home, '.config/google-chrome'),
+      path.join(home, '.config/chromium'),
+      path.join(home, '.config/BraveSoftware/Brave-Browser'),
+      path.join(home, '.config/microsoft-edge'),
+    );
+  } else if (platform === 'win32') {
+    const localAppData = process.env.LOCALAPPDATA;
+    paths.push(
+      path.join(localAppData, 'Google/Chrome/User Data'),
+      path.join(localAppData, 'Chromium/User Data'),
+      path.join(localAppData, 'BraveSoftware/Brave-Browser/User Data'),
+      path.join(localAppData, 'Microsoft/Edge/User Data'),
+    );
+  }
+
+  // Expand to include Default and Profile N directories
+  const expandedPaths = [];
+  for (const browserPath of paths) {
+    if (!fs.existsSync(browserPath)) continue;
+
+    const profiles = ['Default', ...fs.readdirSync(browserPath).filter(f => f.startsWith('Profile '))];
+    for (const profile of profiles) {
+      const extPath = path.join(browserPath, profile, 'Extensions');
+      if (fs.existsSync(extPath)) {
+        expandedPaths.push(extPath);
+      }
+    }
+  }
+
+  return expandedPaths;
+}
+
+function findTabAgentExtension() {
+  const extensionPaths = getAllBrowserExtensionPaths();
+
+  for (const extPath of extensionPaths) {
+    try {
+      const extIds = fs.readdirSync(extPath);
+
+      for (const extId of extIds) {
+        const extDir = path.join(extPath, extId);
+        if (!fs.statSync(extDir).isDirectory()) continue;
+
+        const versions = fs.readdirSync(extDir).filter(v => !v.startsWith('.'));
+
+        for (const version of versions) {
+          const manifestPath = path.join(extDir, version, 'manifest.json');
+          if (fs.existsSync(manifestPath)) {
+            try {
+              const manifest = JSON.parse(fs.readFileSync(manifestPath, 'utf8'));
+              if (manifest.name === 'Tab Agent') {
+                return { extId, browser: extPath };
+              }
+            } catch (e) {}
+          }
+        }
+      }
+    } catch (e) {}
+  }
+  return null;
+}
+
+function checkExistingManifest() {
+  const platform = os.platform();
+  const home = os.homedir();
+  let manifestPath;
+
+  if (platform === 'darwin') {
+    manifestPath = path.join(home, 'Library/Application Support/Google/Chrome/NativeMessagingHosts/com.tabagent.relay.json');
+  } else if (platform === 'linux') {
+    manifestPath = path.join(home, '.config/google-chrome/NativeMessagingHosts/com.tabagent.relay.json');
+  } else if (platform === 'win32') {
+    manifestPath = path.join(home, 'AppData/Local/Google/Chrome/User Data/NativeMessagingHosts/com.tabagent.relay.json');
+  }
+
+  if (manifestPath && fs.existsSync(manifestPath)) {
+    try {
+      const manifest = JSON.parse(fs.readFileSync(manifestPath, 'utf8'));
+      const origin = manifest.allowed_origins?.[0];
+      if (origin) {
+        const match = origin.match(/chrome-extension:\/\/([^/]+)/);
+        if (match) return match[1];
+      }
+    } catch (e) {}
+  }
+  return null;
+}
+
+async function promptForExtensionId() {
+  const readline = require('readline');
+  const rl = readline.createInterface({
+    input: process.stdin,
+    output: process.stdout
+  });
+
+  return new Promise((resolve) => {
+    rl.question('Enter extension ID from chrome://extensions: ', (answer) => {
+      rl.close();
+      resolve(answer.trim());
+    });
+  });
+}
+
+module.exports = {
+  findTabAgentExtension,
+  checkExistingManifest,
+  promptForExtensionId,
+  getAllBrowserExtensionPaths
+};

package/cli/setup.js

@@ -0,0 +1,133 @@
+// cli/setup.js
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+const { findTabAgentExtension, checkExistingManifest, promptForExtensionId } = require('./detect-extension');
+
+async function setup() {
+  console.log('Tab Agent Setup\n');
+
+  // 1. Detect extension ID
+  console.log('Detecting extension...');
+  let extensionId = null;
+
+  const found = findTabAgentExtension();
+  if (found) {
+    extensionId = found.extId;
+    console.log(`✓ Found extension: ${extensionId}`);
+  } else {
+    extensionId = checkExistingManifest();
+    if (extensionId) {
+      console.log(`✓ Found existing config: ${extensionId}`);
+    } else {
+      console.log('✗ Could not auto-detect extension');
+      console.log('  Make sure Tab Agent is loaded in chrome://extensions\n');
+      extensionId = await promptForExtensionId();
+    }
+  }
+
+  if (!extensionId || extensionId.length !== 32) {
+    console.error('Invalid extension ID');
+    process.exit(1);
+  }
+
+  // 2. Install native messaging host
+  console.log('\nInstalling native messaging host...');
+  installNativeHost(extensionId);
+  console.log('✓ Native messaging host installed');
+
+  // 3. Install skills
+  console.log('\nInstalling skills...');
+  installSkills();
+
+  console.log('\n✓ Setup complete!\n');
+  console.log('Usage:');
+  console.log('  1. Click Tab Agent icon on any tab (turns green)');
+  console.log('  2. Ask Claude/Codex: "Use tab-agent to search Google"');
+  console.log('\nThe relay server starts automatically when needed.');
+}
+
+function installNativeHost(extensionId) {
+  const platform = os.platform();
+  const home = os.homedir();
+  const packageDir = path.dirname(__dirname);
+
+  let manifestDir;
+  let wrapperName;
+
+  if (platform === 'darwin') {
+    manifestDir = path.join(home, 'Library/Application Support/Google/Chrome/NativeMessagingHosts');
+    wrapperName = 'native-host-wrapper.sh';
+  } else if (platform === 'linux') {
+    manifestDir = path.join(home, '.config/google-chrome/NativeMessagingHosts');
+    wrapperName = 'native-host-wrapper.sh';
+  } else if (platform === 'win32') {
+    manifestDir = path.join(home, 'AppData/Local/Google/Chrome/User Data/NativeMessagingHosts');
+    wrapperName = 'native-host-wrapper.cmd';
+  }
+
+  fs.mkdirSync(manifestDir, { recursive: true });
+
+  const wrapperPath = path.join(packageDir, 'relay', wrapperName);
+  const manifest = {
+    name: 'com.tabagent.relay',
+    description: 'Tab Agent Native Messaging Host',
+    path: wrapperPath,
+    type: 'stdio',
+    allowed_origins: [`chrome-extension://${extensionId}/`]
+  };
+
+  const manifestPath = path.join(manifestDir, 'com.tabagent.relay.json');
+  fs.writeFileSync(manifestPath, JSON.stringify(manifest, null, 2));
+
+  // Make wrapper executable (Unix only)
+  if (platform !== 'win32') {
+    fs.chmodSync(wrapperPath, '755');
+  }
+
+  // Windows: also set registry key
+  if (platform === 'win32') {
+    const { execSync } = require('child_process');
+    const regPath = 'HKCU\\Software\\Google\\Chrome\\NativeMessagingHosts\\com.tabagent.relay';
+    execSync(`reg add "${regPath}" /ve /t REG_SZ /d "${manifestPath}" /f`);
+  }
+}
+
+function installSkills() {
+  const home = os.homedir();
+  const packageDir = path.dirname(__dirname);
+  const skillSource = path.join(packageDir, 'skills');
+
+  // Claude Code - always install
+  const claudeSkillDir = path.join(home, '.claude', 'skills');
+  const claudeSkillPath = path.join(claudeSkillDir, 'tab-agent.md');
+  fs.mkdirSync(claudeSkillDir, { recursive: true });
+
+  if (fs.existsSync(claudeSkillPath)) {
+    console.log(`  Updating existing skill at ${claudeSkillPath}`);
+  }
+  fs.copyFileSync(
+    path.join(skillSource, 'claude-code', 'tab-agent.md'),
+    claudeSkillPath
+  );
+  console.log('✓ Installed Claude Code skill');
+
+  // Codex (only if .codex exists)
+  const codexDir = path.join(home, '.codex');
+  if (fs.existsSync(codexDir)) {
+    const codexSkillDir = path.join(codexDir, 'skills');
+    const codexSkillPath = path.join(codexSkillDir, 'tab-agent.md');
+    fs.mkdirSync(codexSkillDir, { recursive: true });
+
+    if (fs.existsSync(codexSkillPath)) {
+      console.log(`  Updating existing skill at ${codexSkillPath}`);
+    }
+    fs.copyFileSync(
+      path.join(skillSource, 'codex', 'tab-agent.md'),
+      codexSkillPath
+    );
+    console.log('✓ Installed Codex skill');
+  }
+}
+
+setup().catch(console.error);

package/cli/start.js

@@ -0,0 +1,19 @@
+// cli/start.js
+const path = require('path');
+const { spawn } = require('child_process');
+
+const serverPath = path.join(__dirname, '..', 'relay', 'server.js');
+const server = spawn('node', [serverPath], {
+  stdio: 'inherit',
+  detached: false
+});
+
+server.on('error', (err) => {
+  console.error('Failed to start server:', err.message);
+  process.exit(1);
+});
+
+process.on('SIGINT', () => {
+  server.kill();
+  process.exit(0);
+});

package/cli/status.js

@@ -0,0 +1,70 @@
+// cli/status.js
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+const http = require('http');
+
+function checkRelayServer() {
+  return new Promise((resolve) => {
+    const req = http.get('http://localhost:9876/health', (res) => {
+      let data = '';
+      res.on('data', chunk => data += chunk);
+      res.on('end', () => {
+        try {
+          const json = JSON.parse(data);
+          resolve({ running: true, clients: json.clients });
+        } catch {
+          resolve({ running: false });
+        }
+      });
+    });
+    req.on('error', () => resolve({ running: false }));
+    req.setTimeout(2000, () => {
+      req.destroy();
+      resolve({ running: false });
+    });
+  });
+}
+
+async function status() {
+  console.log('Tab Agent Status\n');
+
+  // Check native host
+  const home = os.homedir();
+  const platform = os.platform();
+  let manifestPath;
+
+  if (platform === 'darwin') {
+    manifestPath = path.join(home, 'Library/Application Support/Google/Chrome/NativeMessagingHosts/com.tabagent.relay.json');
+  } else if (platform === 'linux') {
+    manifestPath = path.join(home, '.config/google-chrome/NativeMessagingHosts/com.tabagent.relay.json');
+  } else if (platform === 'win32') {
+    manifestPath = path.join(home, 'AppData/Local/Google/Chrome/User Data/NativeMessagingHosts/com.tabagent.relay.json');
+  }
+
+  if (fs.existsSync(manifestPath)) {
+    const manifest = JSON.parse(fs.readFileSync(manifestPath, 'utf8'));
+    console.log('Native Host: Installed');
+    console.log(`  Extension: ${manifest.allowed_origins[0]}`);
+  } else {
+    console.log('Native Host: Not installed (run: npx tab-agent setup)');
+  }
+
+  // Check skills
+  const claudeSkill = path.join(home, '.claude', 'skills', 'tab-agent.md');
+  const codexSkill = path.join(home, '.codex', 'skills', 'tab-agent.md');
+
+  console.log(`\nClaude Skill: ${fs.existsSync(claudeSkill) ? 'Installed' : 'Not installed'} ${claudeSkill}`);
+  console.log(`Codex Skill:  ${fs.existsSync(codexSkill) ? 'Installed' : 'Not installed (optional)'} ${codexSkill}`);
+
+  // Check relay server
+  console.log('\nRelay Server:');
+  const relayStatus = await checkRelayServer();
+  if (relayStatus.running) {
+    console.log(`  Status: Running (${relayStatus.clients} client${relayStatus.clients !== 1 ? 's' : ''})`);
+  } else {
+    console.log('  Status: Not running (starts automatically when needed)');
+  }
+}
+
+status().catch(console.error);