barebrowse 0.2.1 → 0.3.0

package/CHANGELOG.md

@@ -1,5 +1,58 @@
 # Changelog
 
+## 0.3.0
+
+CLI session mode. Shell commands that output to disk — coding agents read files when needed instead of getting full snapshots in every tool response. ~4x more token-efficient than MCP for multi-step browsing flows.
+
+### New: CLI session commands
+- `barebrowse open [url] [flags]` — spawn background daemon holding a `connect()` session
+- `barebrowse close` / `status` — session lifecycle
+- `barebrowse goto <url>` — navigate
+- `barebrowse snapshot [--mode=act|read]` — ARIA snapshot → `.barebrowse/page-*.yml`
+- `barebrowse screenshot [--format]` — screenshot → `.barebrowse/screenshot-*.png`
+- `barebrowse click/type/fill/press/scroll/hover/select` — all interactions from connect() API
+- Open flags: `--mode`, `--port`, `--no-cookies`, `--browser`, `--timeout`, `--prune-mode`, `--no-consent`
+
+### New: agent self-sufficiency
+- `barebrowse eval <expression>` — run JS in page context via `Runtime.evaluate`
+- `barebrowse console-logs [--level --clear]` — dump captured console logs → `.barebrowse/console-*.json`
+- `barebrowse network-log [--failed]` — dump network requests → `.barebrowse/network-*.json`
+- `barebrowse wait-idle [--timeout]` — wait for network idle
+
+### New: daemon architecture (`src/daemon.js` + `src/session-client.js`)
+- Background HTTP server on random localhost port, holding a `connect()` session
+- Spawned as detached child process, communicates via `session.json`
+- Console capture via `Runtime.consoleAPICalled`
+- Network capture via `Network.requestWillBeSent` / `responseReceived` / `loadingFailed`
+- Graceful shutdown on `close` command or SIGTERM
+
+### New: SKILL.md for Claude Code
+- `.claude/skills/barebrowse/SKILL.md` — skill definition + full CLI command reference
+- `barebrowse install --skill` — copies SKILL.md to `~/.config/claude/skills/barebrowse/`
+
+### Fixed: MCP setup instructions
+- README now has per-client instructions: Claude Code (`claude mcp add`), Claude Desktop/Cursor (`npx barebrowse install`), VS Code (`.vscode/mcp.json`)
+- `install` command no longer writes `.mcp.json` for Claude Code — prints `claude mcp add` hint instead
+
+### Fixed: ARIA tree formatting (`src/aria.js`)
+- Ignored nodes joined children with empty string instead of newline, causing sibling subtrees to concatenate on one line
+- Fixed to `.filter(Boolean).join('\n')`
+
+### Changed
+- `cli.js` — expanded from 3 commands to full dispatch table (20+ commands)
+- `barebrowse.context.md` — added CLI as third integration path, updated MCP setup
+- `README.md` — "Two ways" → "Three ways", added CLI section
+
+### Docs
+- `docs/04-process/testing.md` — updated to 64 tests, added CLI test section
+- `docs/00-context/system-state.md` — added daemon/session-client to module table, CLI to integrations
+- `docs/03-logs/validation-log.md` — full CLI manual validation results
+
+### Tests
+- 64 tests passing (was 54 in 0.2.x)
+- New: `test/integration/cli.test.js` (10 tests) — full open → snapshot → goto → click → eval → console → network → close cycle
+- All existing 54 tests unchanged and passing
+
 ## 0.2.1
 
 - README rewritten: no code blocks, full obstacle course table with mode column, two usage paths (MCP vs framework), mcprune credited, measured token savings, context.md as code reference

package/CLAUDE.md

@@ -12,11 +12,13 @@
 
 ## Project Specifics
 
+- **What:** Vanilla JS library — CDP-direct browsing for autonomous agents. URL in, pruned ARIA snapshot out.
 - **Language:** Vanilla JavaScript, ES modules, no build step
 - **Runtime:** Node.js >= 22 (built-in WebSocket, sqlite)
 - **Protocol:** CDP (Chrome DevTools Protocol) direct — no Playwright
 - **Browser:** Any installed Chromium-based browser (chromium, chrome, brave, edge)
-- **Key files:** `src/index.js` (API), `src/cdp.js` (CDP client), `src/chromium.js` (browser launch), `src/aria.js` (ARIA formatting)
-- **Docs:** `docs/prd.md` (decisions + rationale), `docs/poc-plan.md` (phases + DoD)
+- **Modules:** 11 files in `src/`, ~2,400 lines, zero required deps
+- **Tests:** 54 passing — run with `node --test test/unit/*.test.js test/integration/*.test.js`
+- **Docs:** `docs/README.md` (navigation guide to all documentation)
 
 For full development and testing standards, see `.claude/memory/AGENT_RULES.md`.

package/README.md

@@ -18,7 +18,7 @@
 
 barebrowse is agentic browsing stripped to the bone. It gives your AI agent eyes and hands on the web -- navigate any page, see what's there, click buttons, fill forms, scroll, and move on. It uses your installed Chromium browser (Chrome, Brave, Edge -- whatever you have), reuses your existing login sessions, and handles all the friction automatically: cookie consent walls, permission prompts, bot detection, GDPR dialogs.
 
-Instead of dumping raw DOM or taking screenshots, barebrowse returns a **pruned ARIA snapshot** -- a compact semantic view of what's on the page and what the agent can interact with. Buttons, links, inputs, headings -- labeled with `[ref=N]` markers the agent uses to act. The pruning pipeline is ported from [mcprune](https://github.com/nickvdyck/mcprune) and cuts 40-90% of tokens compared to raw page output. Every token your agent reads is meaningful.
+Instead of dumping raw DOM or taking screenshots, barebrowse returns a **pruned ARIA snapshot** -- a compact semantic view of what's on the page and what the agent can interact with. Buttons, links, inputs, headings -- labeled with `[ref=N]` markers the agent uses to act. The pruning pipeline is ported from [mcprune](https://github.com/hamr0/mcprune) and cuts 40-90% of tokens compared to raw page output. Every token your agent reads is meaningful.
 
 No Playwright. No bundled browser. No 200MB download. No broken dependencies. Zero deps. Just CDP over a WebSocket to whatever Chromium you already have.
 
@@ -30,18 +30,65 @@ npm install barebrowse
 
 Requires Node.js >= 22 and any installed Chromium-based browser.
 
-## Two ways to use it
+## Three ways to use it
 
-### 1. MCP server -- for Claude Desktop, Cursor, Claude Code
+### 1. CLI session -- for coding agents and quick testing
 
+```bash
+barebrowse open https://example.com    # Start session + navigate
+barebrowse snapshot                    # ARIA snapshot → .barebrowse/page-*.yml
+barebrowse click 8                     # Click element
+barebrowse close                       # End session
 ```
-npm install -g barebrowse
+
+Outputs go to `.barebrowse/` as files -- agents read them with their file tools, no token waste in tool responses. Install the skill for Claude Code:
+
+```bash
+barebrowse install --skill
+# or: claude mcp add barebrowse -- npx barebrowse mcp
+```
+
+Full command reference: [.claude/skills/barebrowse/SKILL.md](.claude/skills/barebrowse/SKILL.md)
+
+### 2. MCP server -- for Claude Desktop, Cursor, and other MCP clients
+
+**Claude Code:**
+```bash
+claude mcp add barebrowse -- npx barebrowse mcp
+```
+
+**Claude Desktop / Cursor:**
+```bash
 npx barebrowse install
 ```
 
-That's it. `install` auto-detects your MCP client and writes the config. No manual JSON editing. Restart your client and you have 7 browsing tools: `browse`, `goto`, `snapshot`, `click`, `type`, `press`, `scroll`.
+Or manually add to your config (`claude_desktop_config.json`, `.cursor/mcp.json`):
+```json
+{
+  "mcpServers": {
+    "barebrowse": {
+      "command": "npx",
+      "args": ["barebrowse", "mcp"]
+    }
+  }
+}
+```
+
+**VS Code (`.vscode/mcp.json`):**
+```json
+{
+  "servers": {
+    "barebrowse": {
+      "command": "npx",
+      "args": ["barebrowse", "mcp"]
+    }
+  }
+}
+```
+
+7 tools: `browse`, `goto`, `snapshot`, `click`, `type`, `press`, `scroll`.
 
-### 2. Framework -- for agentic automation
+### 3. Library -- for agentic automation
 
 Import barebrowse in your agent code. One-shot reads, interactive sessions, full observe-think-act loops. Works with any LLM orchestration library. Ships with a ready-made adapter for [bareagent](https://www.npmjs.com/package/bare-agent) (9 tools, auto-snapshot after every action).
 
@@ -80,7 +127,7 @@ This is the obstacle course your agent doesn't have to think about:
 
 ## What the agent sees
 
-Raw ARIA output from a page is noisy -- decorative wrappers, hidden elements, structural junk. The pruning pipeline (ported from [mcprune](https://github.com/nickvdyck/mcprune)) strips it down to what matters.
+Raw ARIA output from a page is noisy -- decorative wrappers, hidden elements, structural junk. The pruning pipeline (ported from [mcprune](https://github.com/hamr0/mcprune)) strips it down to what matters.
 
 | Page | Raw | Pruned | Reduction |
 |------|-----|--------|-----------|

package/barebrowse.context.md

@@ -1,7 +1,7 @@
 # barebrowse -- Integration Guide
 
 > For AI assistants and developers wiring barebrowse into a project.
-> v0.1.0 | Node.js >= 22 | 0 required deps | MIT
+> v0.3.0 | Node.js >= 22 | 0 required deps | MIT
 
 ## What this is
 
@@ -13,9 +13,10 @@ No Playwright. No bundled browser. No build step. Vanilla JS, ES modules.
 npm install barebrowse
 ```
 
-Two entry points:
-- `import { browse } from 'barebrowse'` -- one-shot: URL in, snapshot out
-- `import { connect } from 'barebrowse'` -- session: navigate, interact, observe
+Three integration paths:
+1. **Library:** `import { browse, connect } from 'barebrowse'` -- one-shot or interactive session
+2. **MCP server:** `barebrowse mcp` -- JSON-RPC over stdio for Claude Desktop, Cursor, etc.
+3. **CLI session:** `barebrowse open` / `click` / `snapshot` / `close` -- shell commands, outputs to disk
 
 ## Which mode do I need?
 
@@ -174,15 +175,33 @@ try {
 
 Action tools (click, type, press, scroll, goto) auto-return a fresh snapshot so the LLM always sees the result. 300ms settle delay after actions for DOM updates.
 
-## MCP wrapper
+## CLI session mode
 
-barebrowse ships an MCP server for direct use with Claude Desktop, Cursor, or any MCP client.
+For coding agents (Claude Code, Copilot, Cursor) and quick interactive testing. Commands output files to `.barebrowse/` -- agents read them with file tools, avoiding token waste in tool responses.
 
 ```bash
-npm install barebrowse       # or npm install -g barebrowse
+barebrowse open https://example.com    # Start daemon + navigate
+barebrowse snapshot                    # → .barebrowse/page-<timestamp>.yml
+barebrowse click 8                     # Click element ref=8
+barebrowse type 12 hello world         # Type into element ref=12
+barebrowse screenshot                  # → .barebrowse/screenshot-<timestamp>.png
+barebrowse console-logs                # → .barebrowse/console-<timestamp>.json
+barebrowse close                       # Kill daemon + browser
 ```
 
-Add to your MCP client config (`.mcp.json`, `claude_desktop_config.json`, etc.):
+Session lifecycle: `open` spawns a background daemon holding a `connect()` session. Subsequent commands POST to the daemon over HTTP (localhost). `close` shuts everything down.
+
+Full command reference: `.claude/skills/barebrowse/SKILL.md`
+
+## MCP wrapper
+
+barebrowse ships an MCP server for direct use with Claude Desktop, Cursor, or any MCP client.
+
+**Claude Code:** `claude mcp add barebrowse -- npx barebrowse mcp`
+
+**Claude Desktop / Cursor:** `npx barebrowse install` (auto-detects and writes config)
+
+**Manual config** (`claude_desktop_config.json`, `.cursor/mcp.json`):
 ```json
 {
   "mcpServers": {

package/cli.js

@@ -2,28 +2,192 @@
 /**
  * cli.js -- barebrowse CLI entry point.
  *
- * Usage:
- *   npx barebrowse mcp            Start the MCP server (JSON-RPC over stdio)
- *   npx barebrowse install        Auto-configure MCP in Claude Desktop / Cursor / Claude Code
- *   npx barebrowse browse <url>   One-shot browse, print snapshot to stdout
+ * Session commands:
+ *   barebrowse open [url] [flags]     Open browser session (daemon)
+ *   barebrowse close                  Close session + kill daemon
+ *   barebrowse status                 Check if session is running
+ *
+ * Navigation:
+ *   barebrowse goto <url>             Navigate to URL
+ *   barebrowse snapshot [--mode]      Get pruned ARIA snapshot → file
+ *   barebrowse screenshot [--format]  Take screenshot → file
+ *
+ * Interaction:
+ *   barebrowse click <ref>            Click element by ref
+ *   barebrowse type <ref> <text>      Type text into element
+ *   barebrowse fill <ref> <text>      Clear + type (replace content)
+ *   barebrowse press <key>            Press special key
+ *   barebrowse scroll <deltaY>        Scroll page
+ *   barebrowse hover <ref>            Hover over element
+ *   barebrowse select <ref> <value>   Select dropdown value
+ *
+ * Self-sufficiency:
+ *   barebrowse eval <expression>      Evaluate JS in page
+ *   barebrowse wait-idle [--timeout]  Wait for network idle
+ *   barebrowse console-logs           Dump console logs → file
+ *   barebrowse network-log            Dump network log → file
+ *
+ * Legacy / tools:
+ *   barebrowse browse <url> [mode]    One-shot browse (stdout)
+ *   barebrowse mcp                    Start MCP server (stdio)
+ *   barebrowse install [--skill]      Auto-configure MCP or install skill
  */
 
-import { existsSync, readFileSync, writeFileSync, mkdirSync } from 'node:fs';
-import { join } from 'node:path';
+import { existsSync, readFileSync, writeFileSync, mkdirSync, copyFileSync } from 'node:fs';
+import { join, resolve } from 'node:path';
 import { homedir, platform } from 'node:os';
+import { fileURLToPath } from 'node:url';
 
-const cmd = process.argv[2];
+const args = process.argv.slice(2);
+const cmd = args[0];
 
-if (cmd === 'mcp') {
+// Hidden internal flag: --daemon-internal
+if (args.includes('--daemon-internal')) {
+  await runDaemonInternal();
+} else if (cmd === 'mcp') {
   await import('./mcp-server.js');
-
 } else if (cmd === 'install') {
   install();
+} else if (cmd === 'browse' && args[1]) {
+  await oneShot();
+} else if (cmd === 'open') {
+  await cmdOpen();
+} else if (cmd === 'close') {
+  await cmdProxy('close');
+} else if (cmd === 'status') {
+  await cmdStatus();
+} else if (cmd === 'goto' && args[1]) {
+  await cmdProxy('goto', { url: args[1], timeout: parseFlag('--timeout') });
+} else if (cmd === 'snapshot') {
+  await cmdProxy('snapshot', { mode: parseFlag('--mode') });
+} else if (cmd === 'screenshot') {
+  await cmdProxy('screenshot', { format: parseFlag('--format') });
+} else if (cmd === 'click' && args[1]) {
+  await cmdProxy('click', { ref: args[1] });
+} else if (cmd === 'type' && args[1] && args[2]) {
+  await cmdProxy('type', { ref: args[1], text: args.slice(2).filter(a => !a.startsWith('--')).join(' '), clear: hasFlag('--clear') });
+} else if (cmd === 'fill' && args[1] && args[2]) {
+  await cmdProxy('fill', { ref: args[1], text: args.slice(2).filter(a => !a.startsWith('--')).join(' ') });
+} else if (cmd === 'press' && args[1]) {
+  await cmdProxy('press', { key: args[1] });
+} else if (cmd === 'scroll' && args[1]) {
+  await cmdProxy('scroll', { deltaY: Number(args[1]) });
+} else if (cmd === 'hover' && args[1]) {
+  await cmdProxy('hover', { ref: args[1] });
+} else if (cmd === 'select' && args[1] && args[2]) {
+  await cmdProxy('select', { ref: args[1], value: args[2] });
+} else if (cmd === 'eval' && args[1]) {
+  await cmdProxy('eval', { expression: args.slice(1).join(' ') });
+} else if (cmd === 'wait-idle') {
+  await cmdProxy('wait-idle', { timeout: parseFlag('--timeout') });
+} else if (cmd === 'console-logs') {
+  await cmdProxy('console-logs', { level: parseFlag('--level'), clear: hasFlag('--clear') });
+} else if (cmd === 'network-log') {
+  await cmdProxy('network-log', { failed: hasFlag('--failed') });
+} else {
+  printUsage();
+}
+
+
+// --- Command implementations ---
+
+async function cmdOpen() {
+  const { startDaemon } = await import('./src/daemon.js');
+  const { isAlive } = await import('./src/session-client.js');
+  const outputDir = resolve('.barebrowse');
+
+  // Check for existing session
+  if (await isAlive(outputDir)) {
+    process.stdout.write('Session already running. Use `barebrowse close` first.\n');
+    process.exit(1);
+  }
+
+  const url = args[1] && !args[1].startsWith('--') ? args[1] : undefined;
+  const opts = {
+    mode: parseFlag('--mode') || 'headless',
+    port: parseFlag('--port'),
+    cookies: !hasFlag('--no-cookies'),
+    browser: parseFlag('--browser'),
+    timeout: parseFlag('--timeout'),
+    pruneMode: parseFlag('--prune-mode') || 'act',
+    consent: !hasFlag('--no-consent'),
+  };
+
+  try {
+    const session = await startDaemon(opts, outputDir, url);
+    process.stdout.write(`Session started (pid ${session.pid}, port ${session.port})\n`);
+    if (url) process.stdout.write(`Navigated to ${url}\n`);
+    process.stdout.write(`Output dir: ${outputDir}\n`);
+  } catch (err) {
+    process.stderr.write(`Error: ${err.message}\n`);
+    process.exit(1);
+  }
+}
 
-} else if (cmd === 'browse' && process.argv[3]) {
+async function cmdStatus() {
+  const { readSession, isAlive } = await import('./src/session-client.js');
+  const outputDir = resolve('.barebrowse');
+  const session = readSession(outputDir);
+
+  if (!session) {
+    process.stdout.write('No session found.\n');
+    process.exit(1);
+  }
+
+  const alive = await isAlive(outputDir);
+  if (alive) {
+    process.stdout.write(`Session running (pid ${session.pid}, port ${session.port}, started ${session.startedAt})\n`);
+  } else {
+    process.stdout.write(`Session stale (pid ${session.pid} not responding). Run \`barebrowse close\` to clean up.\n`);
+    process.exit(1);
+  }
+}
+
+async function cmdProxy(command, cmdArgs) {
+  const { sendCommand, readSession } = await import('./src/session-client.js');
+  const { unlinkSync } = await import('node:fs');
+  const outputDir = resolve('.barebrowse');
+
+  try {
+    const result = await sendCommand(command, cmdArgs, outputDir);
+
+    if (!result.ok) {
+      process.stderr.write(`Error: ${result.error}\n`);
+      process.exit(1);
+    }
+
+    // Print result
+    if (result.file && result.count !== undefined) {
+      process.stdout.write(`${result.file} (${result.count} entries)\n`);
+    } else if (result.file) {
+      process.stdout.write(`${result.file}\n`);
+    } else if (result.value !== undefined) {
+      process.stdout.write(JSON.stringify(result.value) + '\n');
+    } else if (command === 'close') {
+      // Clean up session.json in case daemon didn't
+      const sessionPath = join(outputDir, 'session.json');
+      try { unlinkSync(sessionPath); } catch { /* already gone */ }
+      process.stdout.write('Session closed.\n');
+    } else {
+      process.stdout.write('ok\n');
+    }
+  } catch (err) {
+    if (command === 'close') {
+      // Daemon may have exited before responding — that's fine
+      const sessionPath = join(outputDir, 'session.json');
+      try { unlinkSync(sessionPath); } catch { /* already gone */ }
+      process.stdout.write('Session closed.\n');
+    } else {
+      process.stderr.write(`Error: ${err.message}\n`);
+      process.exit(1);
+    }
+  }
+}
+
+async function oneShot() {
   const { browse } = await import('./src/index.js');
-  const url = process.argv[3];
-  const mode = process.argv[4] || 'headless';
+  const url = args[1];
+  const mode = args[2] || 'headless';
   try {
     const snapshot = await browse(url, { mode });
     process.stdout.write(snapshot + '\n');
@@ -32,28 +196,50 @@ if (cmd === 'mcp') {
     process.stderr.write(`Error: ${err.message}\n`);
     process.exit(1);
   }
+}
 
-} else {
-  process.stdout.write(`barebrowse -- CDP-direct browsing for autonomous agents
+async function runDaemonInternal() {
+  const { runDaemon } = await import('./src/daemon.js');
+  const opts = {
+    mode: parseFlag('--mode') || 'headless',
+    port: parseFlag('--port'),
+    cookies: !hasFlag('--no-cookies'),
+    browser: parseFlag('--browser'),
+    timeout: parseFlag('--timeout'),
+    pruneMode: parseFlag('--prune-mode') || 'act',
+    consent: !hasFlag('--no-consent'),
+  };
+  const outputDir = parseFlag('--output-dir') || resolve('.barebrowse');
+  const url = parseFlag('--url');
+  await runDaemon(opts, outputDir, url || undefined);
+}
 
-Usage:
-  barebrowse mcp                Start MCP server (JSON-RPC over stdio)
-  barebrowse install            Auto-configure MCP for Claude Desktop / Cursor / Claude Code
-  barebrowse browse <url>       One-shot browse, print ARIA snapshot
 
-As a library:
-  import { browse, connect } from 'barebrowse';
+// --- Flag parsing helpers ---
 
-As bareagent tools:
-  import { createBrowseTools } from 'barebrowse/bareagent';
+function parseFlag(name) {
+  // --name=value or --name value
+  for (let i = 0; i < args.length; i++) {
+    if (args[i].startsWith(name + '=')) return args[i].slice(name.length + 1);
+    if (args[i] === name && args[i + 1] && !args[i + 1].startsWith('--')) return args[i + 1];
+  }
+  return undefined;
+}
 
-More: see README.md or barebrowse.context.md
-`);
+function hasFlag(name) {
+  return args.includes(name);
 }
 
+
 // --- MCP auto-installer ---
 
 function install() {
+  // Handle --skill flag
+  if (hasFlag('--skill')) {
+    installSkill();
+    return;
+  }
+
   const mcpEntry = {
     command: 'npx',
     args: ['barebrowse', 'mcp'],
@@ -62,10 +248,7 @@ function install() {
   const targets = detectTargets();
 
   if (targets.length === 0) {
-    console.log('No MCP clients detected. You can manually add this to your MCP config:\n');
-    console.log(JSON.stringify({ mcpServers: { barebrowse: mcpEntry } }, null, 2));
-    console.log('\nSupported clients: Claude Desktop, Cursor, Claude Code');
-    return;
+    console.log('No MCP clients detected.\n');
   }
 
   let installed = 0;
@@ -83,7 +266,6 @@ function install() {
 
       config.mcpServers.barebrowse = mcpEntry;
 
-      // Ensure parent dir exists
       const dir = join(target.path, '..');
       mkdirSync(dir, { recursive: true });
 
@@ -97,8 +279,28 @@ function install() {
 
   if (installed > 0) {
     console.log(`\nDone. Restart your MCP client to pick up the new server.`);
-    console.log('Tools available: browse, goto, snapshot, click, type, press, scroll');
   }
+
+  // Always print Claude Code hint (it uses `claude mcp add`, not JSON config)
+  console.log(`\nClaude Code: run this instead of install:`);
+  console.log(`  claude mcp add barebrowse -- npx barebrowse mcp\n`);
+}
+
+function installSkill() {
+  const thisDir = fileURLToPath(new URL('.', import.meta.url));
+  const src = join(thisDir, '.claude', 'skills', 'barebrowse', 'SKILL.md');
+
+  if (!existsSync(src)) {
+    console.error('SKILL.md not found in package. Reinstall barebrowse.');
+    process.exit(1);
+  }
+
+  const dest = join(homedir(), '.config', 'claude', 'skills', 'barebrowse', 'SKILL.md');
+  const destDir = join(dest, '..');
+  mkdirSync(destDir, { recursive: true });
+  copyFileSync(src, dest);
+  console.log(`Skill installed: ${dest}`);
+  console.log('Claude Code will now see barebrowse as an available skill.');
 }
 
 function detectTargets() {
@@ -116,7 +318,6 @@ function detectTargets() {
     claudeDesktop = join(home, 'AppData', 'Roaming', 'Claude', 'claude_desktop_config.json');
   }
   if (claudeDesktop) {
-    // Check if Claude Desktop dir exists (even if config doesn't yet)
     const dir = join(claudeDesktop, '..');
     if (existsSync(dir)) {
       targets.push({ name: 'Claude Desktop', path: claudeDesktop });
@@ -124,26 +325,11 @@ function detectTargets() {
   }
 
   // Cursor
-  let cursorDir;
-  if (os === 'darwin') {
-    cursorDir = join(home, '.cursor');
-  } else if (os === 'linux') {
-    cursorDir = join(home, '.cursor');
-  } else if (os === 'win32') {
-    cursorDir = join(home, '.cursor');
-  }
-  if (cursorDir && existsSync(cursorDir)) {
+  const cursorDir = join(home, '.cursor');
+  if (existsSync(cursorDir)) {
     targets.push({ name: 'Cursor', path: join(cursorDir, 'mcp.json') });
   }
 
-  // Claude Code (project-level .mcp.json in cwd)
-  const cwd = process.cwd();
-  const claudeCodePath = join(cwd, '.mcp.json');
-  // Only suggest if we're in a project directory (has package.json or .git)
-  if (existsSync(join(cwd, 'package.json')) || existsSync(join(cwd, '.git'))) {
-    targets.push({ name: 'Claude Code (this project)', path: claudeCodePath });
-  }
-
   return targets;
 }
 
@@ -154,3 +340,58 @@ function readJsonOrEmpty(path) {
     return {};
   }
 }
+
+
+// --- Usage ---
+
+function printUsage() {
+  process.stdout.write(`barebrowse -- CDP-direct browsing for autonomous agents
+
+Session:
+  barebrowse open [url] [flags]     Open browser session
+  barebrowse close                  Close session
+  barebrowse status                 Check session status
+
+  Open flags:
+    --mode=headless|headed|hybrid   Browser mode (default: headless)
+    --port=N                        CDP port for headed mode
+    --no-cookies                    Skip cookie injection
+    --browser=firefox|chromium      Cookie source browser
+    --timeout=N                     Navigation timeout in ms
+    --prune-mode=act|read           Default pruning mode
+    --no-consent                    Skip consent dismissal
+
+Navigation:
+  barebrowse goto <url>             Navigate to URL
+  barebrowse snapshot [--mode=M]    ARIA snapshot -> .barebrowse/page-*.yml
+  barebrowse screenshot [--format]  Screenshot -> .barebrowse/screenshot-*.png
+
+Interaction:
+  barebrowse click <ref>            Click element
+  barebrowse type <ref> <text>      Type text (--clear to replace)
+  barebrowse fill <ref> <text>      Clear + type
+  barebrowse press <key>            Press key (Enter, Tab, Escape, ...)
+  barebrowse scroll <deltaY>        Scroll (positive=down)
+  barebrowse hover <ref>            Hover element
+  barebrowse select <ref> <value>   Select dropdown value
+
+Debugging:
+  barebrowse eval <expression>      Run JS in page context
+  barebrowse wait-idle [--timeout]  Wait for network idle
+  barebrowse console-logs           Console logs -> .barebrowse/console-*.json
+  barebrowse network-log            Network log -> .barebrowse/network-*.json
+
+One-shot:
+  barebrowse browse <url> [mode]    Browse + print snapshot to stdout
+
+MCP:
+  barebrowse mcp                    Start MCP server (JSON-RPC over stdio)
+  barebrowse install                Auto-configure MCP for Claude Desktop / Cursor
+  barebrowse install --skill        Install SKILL.md for Claude Code
+
+As a library:
+  import { browse, connect } from 'barebrowse';
+
+More: see README.md or barebrowse.context.md
+`);
+}