open-browser-setup 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 samonjoat
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,65 @@
+# Open Browser Setup
+
+[![npm version](https://img.shields.io/npm/v/open-browser-setup)](https://www.npmjs.com/package/open-browser-setup)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+Interactive installer for the Open Browser ecosystem. One command to set up everything you need to control your real Chrome browser with AI agents.
+
+## Quick Start
+
+```bash
+npx open-browser-setup
+```
+
+The installer walks you through:
+
+1. **Package installation** — MCP server, CLI tool, or both
+2. **Skill installation** — Claude Code `/open-browser` skill for the CLI
+3. **MCP client configuration** — auto-configures Claude Code, Cursor, Windsurf, Codex, OpenCode, or Pi
+4. **Chrome extension** — opens the Chrome Web Store for the Open Browser Bridge extension
+
+## What gets installed
+
+### MCP Server (`open-browser-mcp`)
+
+58 browser automation tools exposed via the Model Context Protocol. Works with any MCP-compatible client (Claude Code, Cursor, Windsurf, etc.).
+
+```bash
+npm install -g open-browser-mcp
+```
+
+### CLI Tool (`open-browser-cli`)
+
+Direct terminal commands for browser control. Token-efficient alternative to MCP — no tool registration overhead.
+
+```bash
+npm install -g open-browser-cli
+```
+
+### Claude Code Skill
+
+The `/open-browser` skill loads on demand in Claude Code, giving the agent full browser control without consuming context window tokens for tool schemas.
+
+### Chrome Extension
+
+The [Open Browser Bridge](https://chromewebstore.google.com/detail/open-browser-bridge) Chrome extension connects the MCP server or CLI to your real browser via WebSocket + CDP.
+
+## Supported MCP Clients
+
+| Client | Config File | Auto-configured |
+|--------|-------------|:-:|
+| Claude Code | `~/.claude/settings.json` | Yes |
+| Cursor | `~/.cursor/mcp.json` | Yes |
+| Windsurf | `~/.codeium/windsurf/mcp_config.json` | Yes |
+| Codex | `~/.codex/config.toml` | Yes |
+| OpenCode | `~/.config/opencode/opencode.json` | Yes |
+| Pi (omp) | `~/.omp/mcp.json` | Yes |
+
+## Requirements
+
+- Node.js >= 18
+- Chrome (any recent version)
+
+## License
+
+MIT

package/bin/setup.js

@@ -0,0 +1,5 @@
+#!/usr/bin/env node
+
+import { run } from '../src/index.js';
+
+run();

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "open-browser-setup",
+  "version": "1.0.0",
+  "description": "Interactive installer for Open Browser — MCP server, CLI tool, skill, and Chrome extension setup",
+  "type": "module",
+  "bin": {
+    "open-browser-setup": "bin/setup.js"
+  },
+  "files": [
+    "bin/",
+    "src/",
+    "skill/",
+    "README.md",
+    "LICENSE"
+  ],
+  "keywords": [
+    "open-browser",
+    "mcp",
+    "browser",
+    "chrome",
+    "automation",
+    "setup",
+    "installer",
+    "cli",
+    "ai",
+    "agent",
+    "skill"
+  ],
+  "author": "samonjoat <samuelodira@gmail.com>",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/samonjoat/open-browser-setup.git"
+  },
+  "homepage": "https://github.com/samonjoat/open-browser-setup#readme",
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "dependencies": {
+    "@clack/prompts": "^0.11.0",
+    "picocolors": "^1.1.0"
+  }
+}

package/skill/SKILL.md

@@ -0,0 +1,267 @@
+---
+name: open-browser
+description: >
+  Control the user's real Chrome browser from the terminal via the open-browser CLI.
+  A token-efficient alternative to open-browser-mcp — loads on demand instead of
+  registering 58 MCP tools in context. Use this skill whenever the user wants to:
+  browse a website, open a URL, navigate to a page, take a screenshot of a website,
+  interact with a web page, fill out a form online, check or test a website, read or
+  scrape web content, automate browser tasks, click something in Chrome, verify page
+  content, test a web UI, or do anything involving a real browser. Also triggers on
+  /open-browser or /browser. Prefer this over launching Puppeteer, Playwright, or any
+  sandboxed browser — this uses the user's actual Chrome profile with their cookies,
+  sessions, extensions, and bookmarks.
+allowed-tools:
+  - Bash
+  - Read
+user-invocable: true
+argument-hint: "describe what you want to do in the browser"
+---
+
+# Open Browser
+
+Control the user's real Chrome browser via the `open-browser` CLI. Every command runs as a shell call and exits — the browser state persists through the Chrome extension between commands.
+
+## Prerequisites
+
+- `open-browser-cli` installed globally (`npm install -g open-browser-cli`)
+- The Open Browser Bridge Chrome extension loaded in Chrome (shared with open-browser-mcp)
+- The open-browser-mcp server must NOT be running (they share the same WebSocket port)
+
+## Core Workflow
+
+Every browser session follows this pattern:
+
+```
+1. open-browser session          ← required first step, creates tab group + CDP
+2. open-browser navigate <url>   ← go to a page
+3. open-browser snapshot --json  ← see interactive elements with @eN refs
+4. open-browser click @e5        ← interact using refs from snapshot
+5. open-browser verify text "…"  ← confirm the result
+```
+
+Always start with `session`. Always use `snapshot --json` to discover elements before interacting. The `@eN` refs (like `@e1`, `@e5`, `@e12`) are how you target elements for click, type, select, and other interactions.
+
+## Using --json
+
+Add `--json` to any command when you need to parse the output programmatically. Without it, output is human-readable text. Use `--json` for snapshot, read, markdown, find, network, cookies, tabs, and screenshot commands. For simple action commands (click, type, key, navigate), text output is usually fine.
+
+## Command Reference
+
+### Session & Navigation
+
+```bash
+open-browser session                        # REQUIRED first step
+open-browser navigate <url>                 # go to URL (--wait networkIdle for SPAs)
+open-browser navigate <url> --wait networkIdle  # wait for all network to settle
+open-browser close                          # close active tab
+open-browser close --tab-id 123             # close specific tab
+open-browser back                           # browser back
+open-browser forward                        # browser forward
+```
+
+External domains trigger a permission popup in Chrome — the user must approve. This is expected behavior. The navigate command has a 5-minute timeout to allow for this.
+
+### Reading & Inspection
+
+```bash
+open-browser snapshot --json                # primary tool — get all interactive elements
+open-browser read --json                    # full page text content
+open-browser read --format html --json      # raw HTML source
+open-browser markdown --json                # clean markdown, boilerplate removed
+open-browser markdown --full --json         # include nav/footer/sidebar
+open-browser find "div.error" --json        # search by CSS selector
+open-browser find "Welcome back" --json     # search by text
+open-browser js "document.title" --json     # execute JavaScript
+open-browser console --json                 # read console messages
+open-browser console --pattern "error" --json  # filter console by pattern
+```
+
+The snapshot returns elements like:
+```
+@e1   link        "Home"        href="/home"
+@e2   textbox     ""            placeholder="Search..."
+@e5   button      "Sign In"
+```
+
+Use these `@eN` refs in click, type, hover, select, and drag commands.
+
+### Input & Interaction
+
+```bash
+open-browser click @e5                      # click element
+open-browser click @e5 --button right       # right-click
+open-browser click @e5 --count 2            # double-click
+open-browser type @e2 "hello world"         # type into input (clears first)
+open-browser type @e2 "search term" --slowly  # char-by-char for autocomplete
+open-browser key Enter                      # press key
+open-browser key Tab                        # tab to next field
+open-browser key "Ctrl+A"                   # select all
+open-browser hover @e3                      # hover to reveal menus
+open-browser select @e4 "Option B"          # select dropdown value
+open-browser drag @e1 @e5                   # drag element to target
+open-browser upload @e3 /path/to/file.pdf   # upload file
+```
+
+### Verification
+
+```bash
+open-browser verify text "Welcome back"     # PASS/FAIL — is text on page?
+open-browser verify element "#submit-btn"   # PASS/FAIL — is element visible?
+open-browser verify list "Item A" "Item B"  # per-item PASS/FAIL
+open-browser verify value "#email" "user@example.com"  # check input value
+```
+
+### Screenshots & Media
+
+```bash
+open-browser screenshot --json              # viewport screenshot
+open-browser screenshot --full-page --json  # full scrollable page
+open-browser screenshot --filename "login.png" --json  # custom name
+open-browser pdf --json                     # save page as PDF
+open-browser resize 1920 1080               # resize window
+```
+
+Screenshots save to `.open-browser-mcp/` in the current directory. Use the Read tool to view screenshot files afterward.
+
+### Tabs
+
+```bash
+open-browser tabs --json                    # list all tabs (id, title, url)
+open-browser tab create https://example.com # open new tab
+open-browser tab switch 12345               # switch to tab by ID
+```
+
+### Waiting & Scrolling
+
+```bash
+open-browser wait --time 2000               # wait 2 seconds
+open-browser wait --selector ".loaded"      # wait for element to appear
+open-browser wait-text "Loading complete" --timeout 10000  # poll for text
+open-browser scroll --down 500              # scroll down 500px
+open-browser scroll --up 300                # scroll up
+open-browser scroll --ref @e15              # scroll element into view
+```
+
+### Network & Cookies
+
+```bash
+open-browser network --json                 # captured network requests
+open-browser network --url-pattern "api" --json  # filter by URL
+open-browser cookies --json                 # read cookies
+open-browser set-cookie session_id abc123 .example.com  # set cookie
+open-browser clear-storage                  # clear all storage
+open-browser block-urls "*ads*" "*.tracker.com*"  # block URL patterns
+```
+
+### Device Emulation
+
+```bash
+open-browser emulate                        # default iPhone (375x812)
+open-browser emulate --width 768 --height 1024 --no-mobile  # tablet
+open-browser emulate --network "Slow 3G"    # throttle network
+open-browser geolocation 37.7749 -122.4194  # set GPS (San Francisco)
+```
+
+### Batch Operations
+
+For multi-step interactions in a single call — faster than individual commands:
+
+```bash
+open-browser batch '[{"action":"click","ref":"@e1"},{"action":"type","ref":"@e2","text":"hello"},{"action":"press_key","key":"Enter"}]'
+```
+
+Supported actions: `click`, `type`, `select_option`, `press_key`, `wait`, `scroll`, `mouse_click_xy`.
+
+### Advanced
+
+```bash
+# Captcha handling
+open-browser solve-captcha                  # detect and click captcha checkbox
+open-browser captcha-tiles --json           # analyze tile grid after checkbox
+open-browser batch-click @t1 @t4 @t7 --human-like  # click tiles
+
+# DevTools
+open-browser a11y-tree --json               # accessibility tree
+open-browser audit-a11y --json              # accessibility audit
+open-browser memory --json                  # JS heap, DOM nodes, layout
+open-browser locator @e5 --json             # generate CSS/XPath selectors
+open-browser trace start                    # start performance trace
+open-browser trace stop --json              # stop and get results
+
+# Script injection (persists across navigations)
+open-browser inject "window.__TEST = true"
+open-browser inject --remove <identifier>
+
+# Screen recording
+open-browser screencast start --interval 500  # record at 2 FPS
+open-browser screencast stop                  # save frames to disk
+
+# JS dialogs
+open-browser dialog accept                  # click OK on alert/confirm
+open-browser dialog dismiss                 # click Cancel
+open-browser dialog accept --text "response"  # answer prompt dialog
+
+# Domain permissions
+open-browser domain-mode allow_all          # skip domain popups
+open-browser domains allow github.com stackoverflow.com  # pre-approve
+```
+
+## Common Patterns
+
+### Fill and submit a form
+
+```bash
+open-browser session
+open-browser navigate "https://example.com/login"
+open-browser snapshot --json
+# Find the username and password fields from snapshot output
+open-browser type @e2 "username"
+open-browser type @e5 "password"
+open-browser click @e8   # submit button
+open-browser verify text "Welcome"
+```
+
+### Read article content
+
+```bash
+open-browser session
+open-browser navigate "https://example.com/article"
+open-browser markdown --json
+```
+
+### Test responsive layout
+
+```bash
+open-browser session
+open-browser navigate "https://example.com"
+open-browser screenshot --filename "desktop.png" --json
+open-browser emulate --width 375 --height 812
+open-browser screenshot --filename "mobile.png" --json
+```
+
+### Multi-step with batch
+
+```bash
+open-browser session
+open-browser navigate "https://example.com/form"
+open-browser snapshot --json
+open-browser batch '[{"action":"type","ref":"@e1","text":"John"},{"action":"type","ref":"@e2","text":"john@example.com"},{"action":"click","ref":"@e5"}]'
+```
+
+## Error Handling
+
+If a command fails, the error message is printed to stderr. Common issues:
+
+- **"Chrome extension is not connected"** — The extension isn't loaded or Chrome isn't open
+- **"Chrome extension did not connect within 10s"** — Extension is loaded but WebSocket port may be in use by the MCP server
+- **"Request timed out"** — Page took too long to respond; try `--wait networkIdle` or increase `--timeout`
+- **"EADDRINUSE"** — Port 9877 is in use (likely by open-browser-mcp); stop the MCP server first
+
+## Important Notes
+
+- The CLI process exits after each command — state persists in the browser via the extension
+- Only one WebSocket client at a time: either the CLI or the MCP server, not both
+- Screenshots save to `.open-browser-mcp/` in the working directory
+- Domain permission popups appear in Chrome for external sites — this is a security feature
+- Relative URLs resolve to `http://localhost:9876` (the built-in test server from open-browser-mcp)

package/src/clients.js

@@ -0,0 +1,138 @@
+import { readFileSync, writeFileSync, mkdirSync, existsSync } from 'fs';
+import { join, dirname } from 'path';
+import { homedir } from 'os';
+import { spinner } from '@clack/prompts';
+
+const HOME = homedir();
+
+const CLIENTS = {
+  'Claude Code': {
+    configPath: join(HOME, '.claude', 'settings.json'),
+    detect: () => existsSync(join(HOME, '.claude')),
+    write: (config) => {
+      if (!config.mcpServers) config.mcpServers = {};
+      config.mcpServers.browser = { command: 'open-browser-mcp' };
+      return config;
+    }
+  },
+  'Cursor': {
+    configPath: join(HOME, '.cursor', 'mcp.json'),
+    detect: () => existsSync(join(HOME, '.cursor')),
+    write: (config) => {
+      if (!config.mcpServers) config.mcpServers = {};
+      config.mcpServers.browser = { command: 'open-browser-mcp' };
+      return config;
+    }
+  },
+  'Windsurf': {
+    configPath: join(HOME, '.codeium', 'windsurf', 'mcp_config.json'),
+    detect: () => existsSync(join(HOME, '.codeium', 'windsurf')),
+    write: (config) => {
+      if (!config.mcpServers) config.mcpServers = {};
+      config.mcpServers.browser = { command: 'open-browser-mcp' };
+      return config;
+    }
+  },
+  'Codex': {
+    configPath: join(HOME, '.codex', 'config.toml'),
+    detect: () => existsSync(join(HOME, '.codex')),
+    write: null // TOML handled separately
+  },
+  'OpenCode': {
+    configPath: join(HOME, '.config', 'opencode', 'opencode.json'),
+    detect: () => existsSync(join(HOME, '.config', 'opencode')),
+    write: (config) => {
+      if (!config.mcp) config.mcp = {};
+      config.mcp.browser = { type: 'local', command: ['open-browser-mcp'], enabled: true };
+      return config;
+    }
+  },
+  'Pi (omp)': {
+    configPath: join(HOME, '.omp', 'mcp.json'),
+    detect: () => existsSync(join(HOME, '.omp')),
+    write: (config) => {
+      if (!config.mcpServers) config.mcpServers = {};
+      config.mcpServers.browser = { command: 'open-browser-mcp' };
+      return config;
+    }
+  }
+};
+
+/**
+ * Detect which MCP clients are installed.
+ */
+export function detectClients() {
+  const detected = [];
+  for (const [name, client] of Object.entries(CLIENTS)) {
+    if (client.detect()) detected.push(name);
+  }
+  return detected;
+}
+
+/**
+ * Get all client names.
+ */
+export function getAllClients() {
+  return Object.keys(CLIENTS);
+}
+
+/**
+ * Configure an MCP client with the open-browser-mcp server.
+ */
+export async function configureClient(clientName) {
+  const client = CLIENTS[clientName];
+  if (!client) throw new Error(`Unknown client: ${clientName}`);
+
+  const s = spinner();
+  s.start(`Configuring ${clientName}...`);
+
+  try {
+    // Codex uses TOML
+    if (clientName === 'Codex') {
+      return configureCodex(client.configPath, s);
+    }
+
+    // All others use JSON
+    const configDir = dirname(client.configPath);
+    mkdirSync(configDir, { recursive: true });
+
+    let config = {};
+    if (existsSync(client.configPath)) {
+      try {
+        config = JSON.parse(readFileSync(client.configPath, 'utf8'));
+      } catch {
+        config = {};
+      }
+    }
+
+    config = client.write(config);
+    writeFileSync(client.configPath, JSON.stringify(config, null, 2) + '\n', 'utf8');
+    s.stop(`${clientName} configured at ${client.configPath}`);
+    return true;
+  } catch (err) {
+    s.stop(`Failed to configure ${clientName}`);
+    throw err;
+  }
+}
+
+function configureCodex(configPath, s) {
+  const configDir = dirname(configPath);
+  mkdirSync(configDir, { recursive: true });
+
+  let content = '';
+  if (existsSync(configPath)) {
+    content = readFileSync(configPath, 'utf8');
+  }
+
+  // Check if already configured
+  if (content.includes('[mcp_servers.browser]')) {
+    s.stop('Codex — already configured');
+    return true;
+  }
+
+  // Append TOML section
+  const tomlEntry = `\n[mcp_servers.browser]\ncommand = "open-browser-mcp"\nargs = []\n`;
+  writeFileSync(configPath, content + tomlEntry, 'utf8');
+  s.stop(`Codex configured at ${configPath}`);
+  return true;
+}

package/src/extension.js

@@ -0,0 +1,23 @@
+import { execSync } from 'child_process';
+import { platform } from 'os';
+
+const STORE_URL = 'https://chromewebstore.google.com/detail/open-browser-bridge';
+
+/**
+ * Open the Chrome Web Store page for the extension.
+ */
+export function openExtensionStore() {
+  const os = platform();
+  try {
+    if (os === 'win32') {
+      execSync(`start "" "${STORE_URL}"`, { stdio: 'pipe', shell: true });
+    } else if (os === 'darwin') {
+      execSync(`open "${STORE_URL}"`, { stdio: 'pipe' });
+    } else {
+      execSync(`xdg-open "${STORE_URL}"`, { stdio: 'pipe' });
+    }
+    return true;
+  } catch {
+    return false;
+  }
+}

package/src/index.js

@@ -0,0 +1,115 @@
+import * as p from '@clack/prompts';
+import pc from 'picocolors';
+import { installPackages } from './packages.js';
+import { installSkill, isSkillInstalled } from './skill.js';
+import { detectClients, getAllClients, configureClient } from './clients.js';
+import { openExtensionStore } from './extension.js';
+
+export async function run() {
+  p.intro(pc.bgCyan(pc.black(' Open Browser Setup ')));
+
+  // Step 1: Choose what to install
+  const installChoice = await p.select({
+    message: 'What would you like to install?',
+    options: [
+      { value: 'both', label: 'Both (recommended)', hint: 'MCP server + CLI tool' },
+      { value: 'mcp', label: 'MCP Server', hint: 'open-browser-mcp — 58 tools via MCP protocol' },
+      { value: 'cli', label: 'CLI Tool', hint: 'open-browser-cli — terminal commands + Claude Code skill' }
+    ]
+  });
+
+  if (p.isCancel(installChoice)) {
+    p.cancel('Setup cancelled.');
+    process.exit(0);
+  }
+
+  // Step 2: Install packages
+  const packages = [];
+  if (installChoice === 'mcp' || installChoice === 'both') packages.push('open-browser-mcp');
+  if (installChoice === 'cli' || installChoice === 'both') packages.push('open-browser-cli');
+
+  try {
+    await installPackages(packages);
+  } catch (err) {
+    p.log.error(err.message);
+    p.log.info('You may need to run your terminal as Administrator for global installs.');
+    process.exit(1);
+  }
+
+  // Step 3: Install skill (CLI users)
+  if (installChoice === 'cli' || installChoice === 'both') {
+    const alreadyInstalled = isSkillInstalled();
+
+    const installSkillChoice = await p.confirm({
+      message: alreadyInstalled
+        ? 'The open-browser skill is already installed. Overwrite?'
+        : 'Install the Claude Code skill? (enables /open-browser command)',
+      initialValue: !alreadyInstalled
+    });
+
+    if (!p.isCancel(installSkillChoice) && installSkillChoice) {
+      try {
+        await installSkill();
+      } catch (err) {
+        p.log.error(err.message);
+      }
+    }
+  }
+
+  // Step 4: Configure MCP client (MCP users)
+  if (installChoice === 'mcp' || installChoice === 'both') {
+    const detected = detectClients();
+    const allClients = getAllClients();
+
+    const clientOptions = allClients.map(name => ({
+      value: name,
+      label: name,
+      hint: detected.includes(name) ? 'detected' : undefined
+    }));
+    clientOptions.push({ value: 'skip', label: 'Skip' });
+
+    const clientChoice = await p.select({
+      message: 'Configure an MCP client?',
+      options: clientOptions
+    });
+
+    if (!p.isCancel(clientChoice) && clientChoice !== 'skip') {
+      try {
+        await configureClient(clientChoice);
+      } catch (err) {
+        p.log.error(err.message);
+      }
+    }
+  }
+
+  // Step 5: Chrome extension
+  const extensionChoice = await p.select({
+    message: 'The Open Browser Bridge Chrome extension is required.',
+    options: [
+      { value: 'open', label: 'Open Chrome Web Store' },
+      { value: 'skip', label: 'Skip (I\'ll install manually)' }
+    ]
+  });
+
+  if (!p.isCancel(extensionChoice) && extensionChoice === 'open') {
+    const opened = openExtensionStore();
+    if (opened) {
+      p.log.success('Opened Chrome Web Store in your browser.');
+    } else {
+      p.log.info(`Visit: ${pc.underline('https://chromewebstore.google.com/detail/open-browser-bridge')}`);
+    }
+  }
+
+  // Outro
+  p.note(
+    [
+      installChoice !== 'cli' ? `${pc.green('MCP')}: Add "open-browser-mcp" to your MCP client config` : '',
+      installChoice !== 'mcp' ? `${pc.green('CLI')}: Run ${pc.cyan('open-browser --help')} to see all commands` : '',
+      installChoice !== 'mcp' ? `${pc.green('Skill')}: Use ${pc.cyan('/open-browser')} in Claude Code` : '',
+      `${pc.green('Extension')}: Load the Open Browser Bridge extension in Chrome`
+    ].filter(Boolean).join('\n'),
+    'Next steps'
+  );
+
+  p.outro(pc.green('Setup complete!'));
+}

package/src/packages.js

@@ -0,0 +1,38 @@
+import { execSync } from 'child_process';
+import { spinner } from '@clack/prompts';
+
+/**
+ * Check if a package is installed globally.
+ */
+function isInstalled(name) {
+  try {
+    execSync(`npm list -g ${name} --depth=0`, { stdio: 'pipe' });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Install packages globally.
+ */
+export async function installPackages(packages) {
+  const s = spinner();
+
+  for (const pkg of packages) {
+    if (isInstalled(pkg)) {
+      s.start(`${pkg} is already installed`);
+      s.stop(`${pkg} — already installed`);
+      continue;
+    }
+
+    s.start(`Installing ${pkg} globally...`);
+    try {
+      execSync(`npm install -g ${pkg}`, { stdio: 'pipe' });
+      s.stop(`${pkg} — installed`);
+    } catch (err) {
+      s.stop(`${pkg} — failed to install`);
+      throw new Error(`Failed to install ${pkg}: ${err.message}`);
+    }
+  }
+}

package/src/skill.js

@@ -0,0 +1,36 @@
+import { readFileSync, writeFileSync, mkdirSync, existsSync } from 'fs';
+import { join, dirname } from 'path';
+import { homedir } from 'os';
+import { fileURLToPath } from 'url';
+import { spinner } from '@clack/prompts';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const BUNDLED_SKILL = join(__dirname, '..', 'skill', 'SKILL.md');
+const SKILL_DIR = join(homedir(), '.claude', 'skills', 'open-browser');
+const SKILL_PATH = join(SKILL_DIR, 'SKILL.md');
+
+/**
+ * Check if the skill is already installed.
+ */
+export function isSkillInstalled() {
+  return existsSync(SKILL_PATH);
+}
+
+/**
+ * Install the bundled skill to ~/.claude/skills/open-browser/
+ */
+export async function installSkill() {
+  const s = spinner();
+  s.start('Installing open-browser skill...');
+
+  try {
+    mkdirSync(SKILL_DIR, { recursive: true });
+    const content = readFileSync(BUNDLED_SKILL, 'utf8');
+    writeFileSync(SKILL_PATH, content, 'utf8');
+    s.stop(`Skill installed to ${SKILL_DIR}`);
+    return true;
+  } catch (err) {
+    s.stop('Failed to install skill');
+    throw new Error(`Failed to install skill: ${err.message}`);
+  }
+}