poltertab 1.1.0

package/README.md

@@ -0,0 +1,303 @@
+# PolterTab — Browser Control for Any AI
+
+**PolterTab lets any AI assistant drive and scrape your *existing* Chrome profile — no headless browser, no separate automation setup, no re-logging into anything.**
+
+A Chrome extension + Model Context Protocol (MCP) server. The AI acts inside the browser you already use: your real profile, your cookies, your logged-in sessions. Install the extension, point your MCP client at the server, done — it works with Claude Desktop, Cursor, or any MCP-compatible agent.
+
+## Why PolterTab
+
+- **Your real profile** — runs in the Chrome you're already signed into. No fresh headless browser that's logged out of everything.
+- **No complex setup** — load the unpacked extension, add one MCP entry. That's it.
+- **Any AI tool** — any MCP-compatible client can connect.
+
+## How It Works
+
+```
+Any MCP Agent (Claude Desktop, Cursor, custom agents)
+       │  Stdio (MCP Protocol)
+       ▼
+Node.js MCP Server (mcp-server/index.js)
+       │  WebSocket (port 7822 by default)
+       ▼
+PolterTab Chrome Extension
+       │  Chrome APIs + DOM
+       ▼
+  Your existing Chrome profile
+```
+
+Several agents can point at the same browser at once — the first server to claim
+the WebSocket port serves the extension and the rest proxy through it. See
+[Running several agents at once](#troubleshooting--options).
+
+## Setup
+
+Requires Node 18 or newer.
+
+### 1. Run the installer
+
+```bash
+npm install -g poltertab
+poltertab setup
+```
+
+The wizard asks whether to install for all projects or just the current one,
+then puts three things in place:
+
+- the `browser-navigation-strategy` skill, so the agent knows how to drive a
+  browser that fights back
+- a `CLAUDE.md` section, so it knows the tools exist
+- the MCP server registration, via `claude mcp add`
+
+It is safe to re-run — each step detects its own prior work, so an upgrade or a
+second pass will not duplicate anything.
+
+Prefer not to install globally? `npx poltertab setup` does the same thing.
+
+### 2. Install the Chrome Extension
+
+The installer prints this link when it finishes:
+
+1. Download the latest [release zip](https://github.com/abhinav162/poltertab/releases/latest) and unzip it
+2. Open Chrome → `chrome://extensions/`
+3. Enable **Developer mode** (top right toggle)
+4. Click **Load unpacked** and select the unzipped `chrome-extension/` directory
+
+Then restart your AI tool so it picks up the new tools.
+
+### Other MCP clients
+
+The wizard targets Claude Code. Any other MCP client works too — register
+`poltertab` as a stdio command:
+
+```json
+{
+  "mcpServers": {
+    "poltertab": {
+      "command": "poltertab"
+    }
+  }
+}
+```
+
+Running from a clone instead of npm? Point the client at the file directly:
+`{"command": "node", "args": ["/absolute/path/to/poltertab/mcp-server/index.js"]}`
+
+> **Legacy:** This extension began as a ZeroClaw plugin and still speaks ZeroClaw's built-in REST bridge (`backend = "bridge"` in `~/.zeroclaw/config.toml`). That path is optional and not required for the MCP setup above.
+
+## Supported MCP Tools
+
+The server exposes 21 tools to the LLM (all prefixed with `browser_`). Every
+page-facing tool also takes optional `tabId` and `session` to target a specific
+tab — omit both and PolterTab uses the last tab it navigated, falling back to
+your active tab.
+
+### Page actions
+
+| Action | Parameters | Description |
+| -------- | ----------- | ------------- |
+| `browser_navigate` | `url` (required) | Navigate to a URL |
+| `browser_click` | `selector` (required) | Click an element (CSS/XPath/text) |
+| `browser_fill` | `selector`, `value` (required), `submit` | Fill an input field, optionally submitting its form |
+| `browser_hover` | `selector` (required) | Hover over an element |
+| `browser_scroll` | `direction` (required), `amount`, `selector` | Scroll page or element — `up`/`down`/`left`/`right`/`top`/`bottom` |
+| `browser_smart_scroll` | `direction` (required), `amount` | Scroll, then wait 2s for lazy-loaded network data to arrive |
+
+### Reading the page
+
+| Action | Parameters | Description |
+| -------- | ----------- | ------------- |
+| `browser_scrape` | `selector`, `attribute`, `multiple` | Scrape given elements, or the whole page (title, meta, links, headings, body text) |
+| `browser_snapshot` | — | Ref-tagged tree of visible and interactive nodes, capped at 400 |
+| `browser_get_text` | `selector` (required) | Text content of one element |
+| `browser_get_title` | — | Page title and URL |
+| `browser_get_url` | — | Page URL and title |
+| `browser_screenshot` | — | Visible tab as base64 PNG (focuses the tab) |
+
+### Network capture
+
+For sites whose DOM is obfuscated or virtualized, read the JSON driving the UI
+instead of scraping elements that may not exist.
+
+| Action | Parameters | Description |
+| -------- | ----------- | ------------- |
+| `browser_set_intercept_patterns` | `patterns` (required) | URL substrings to capture, e.g. `["graphql", "/api/v1/"]`. Defaults to `["graphql", "/api/", "voyager", "feed"]` |
+| `browser_get_network_state` | `clear`, `output_file` | Captured raw JSON for the tab. `output_file` writes to `~/.poltertab/downloads/` and returns just the path, keeping large payloads out of the context window |
+
+### Sessions
+
+A session is a named tab. Giving each agent its own session stops concurrent
+agents fighting over one tab; closed tabs are recreated from the stored URL on
+next use.
+
+| Action | Parameters | Description |
+| -------- | ----------- | ------------- |
+| `browser_session_create` | `name` (required), `url` | Create a session, or bind one to the active tab |
+| `browser_session_switch` | `name` (required) | Make a session active, recovering its tab if closed |
+| `browser_session_list` | — | All sessions, each `alive`, `recoverable`, or `expired` |
+| `browser_session_close` | `name` (required) | Close a session and its tab |
+| `browser_session_context` | — | Active session's tab, URL and title |
+
+### Site memory
+
+| Action | Parameters | Description |
+| -------- | ----------- | ------------- |
+| `browser_get_site_memory` | `hostname` (or `domain`) | Recorded obstacles and fixes for a domain |
+| `browser_save_site_memory` | `hostname` (or `domain`), `obstacle`, `solution` | Record what broke on a site and how it was solved |
+
+### Selector Resolution
+
+Selectors are resolved in order:
+
+1. **CSS selector** — `#id`, `.class`, `div > span`
+2. **XPath** — `//div[@class="foo"]`
+3. **Text match** — exact text content of an element
+
+## CLI Wrapper (Legacy)
+
+`zc-browser.sh` lets you send commands directly to the legacy ZeroClaw REST bridge for testing (only relevant if you use the optional ZeroClaw bridge path above):
+
+```bash
+./zc-browser.sh navigate url=https://example.com
+./zc-browser.sh scrape selector="h1"
+./zc-browser.sh get_title
+./zc-browser.sh health
+```
+
+## Troubleshooting & Options
+
+**Running several agents at once:**
+The first MCP server to bind port `7822` becomes the **primary** and owns the
+connection to the extension. Later servers find the port taken and switch
+themselves into **secondary** mode, proxying their commands through the primary,
+so concurrent agents share one browser with no extra configuration. Each
+secondary auto-injects a per-agent `session` so agents get their own tabs. Up to
+5 secondaries are accepted, and if the primary exits one of them promotes itself
+to replace it. The extension popup lists whichever agents are connected.
+
+**Changing the WebSocket Port:**
+Only needed when something that *isn't* PolterTab already holds `7822` —
+PolterTab servers share that port by design (see above). Both sides must move:
+
+1. Click the Extension icon in Chrome -> **Settings**.
+2. Change the WebSocket Port to a free port (e.g. `7824`) and click **Save** —
+   the extension reconnects immediately, no reload needed.
+3. Update your MCP Server configuration to pass the new port.
+   - Using env var: `MCP_BROWSER_WS_PORT=7824 node index.js`
+   - Using CLI arg: `node index.js --port 7824`
+   - In Claude Desktop config:
+
+   ```json
+   "args": ["/absolute/path/to/poltertab/mcp-server/index.js", "--port", "7824"]
+   ```
+
+**Extension not connecting:**
+
+- Ensure the MCP Server is running and pointing to the correct port.
+- Reload the extension from `chrome://extensions/`
+
+**Commands timing out / Restricted Pages:**
+
+- Ensure you have an active tab open in Chrome.
+- Chrome extensions **cannot** interact with `chrome://` URLs, the Chrome Web Store, or certain restricted pages. The MCP server will cleanly report "Cannot interact with this page" back to the agent in these cases.
+
+## Project Structure
+
+```
+poltertab/
+├── package.json               # Published npm package (deps + bin)
+├── bin/
+│   ├── poltertab.js           # Entry: bare = MCP server, `setup` = wizard
+│   └── setup.js               # Installer (skill, CLAUDE.md, MCP registration)
+├── skills/
+│   └── browser-navigation-strategy/   # Shipped skill, installed by the wizard
+├── assets/
+│   └── claude-md-snippet.md   # The CLAUDE.md section the wizard appends
+├── mcp-server/
+│   ├── index.js               # MCP server (stdio) + WebSocket hub
+│   └── test/run.js            # Extension + server regression suite
+├── test/
+│   └── setup.test.js          # Installer regression suite
+├── chrome-extension/
+│   ├── manifest.json          # MV3 manifest
+│   ├── background.js          # WebSocket client, session manager, command router
+│   ├── content_script.js      # DOM extractor + action executor (isolated world)
+│   ├── interceptor.js         # fetch/XHR capture (main world)
+│   ├── popup.html/js          # Connected-agents UI
+│   ├── options.html/js        # Port configuration UI
+│   └── icons/
+├── zc-browser.sh              # CLI wrapper (legacy)
+└── README.md
+```
+
+## Where your data lives
+
+Nothing the server accumulates is stored inside the package:
+
+```
+~/.poltertab/
+├── navigation_memory/   # Per-domain obstacles and fixes (browser_save_site_memory)
+└── downloads/           # output_file payloads from browser_get_network_state
+```
+
+This matters for a global npm install. The package sits in `node_modules/`, so
+anything written beside the code is deleted by the next `npm update -g` — site
+memory would read as amnesia after every upgrade, and scraped payloads would be
+buried somewhere you would never look for them.
+
+Set `POLTERTAB_HOME` to move the whole tree. Upgrading from a version that kept
+memory in `mcp-server/navigation_memory/`? It is copied forward on first start,
+and an existing note at the destination always wins.
+
+## Releasing
+
+Publishing is driven by GitHub Releases. The version string decides the npm
+channel, so the git tag is the only thing you have to get right:
+
+| Version | npm tag | Installed by |
+|---|---|---|
+| `1.2.0` | `latest` | `npm install -g poltertab` |
+| `1.2.0-rc.1` | `rc` | `npm install -g poltertab@rc` |
+| `1.2.0-beta.1` | `beta` | `npm install -g poltertab@beta` |
+| `1.2.0-alpha.1` | `alpha` | `npm install -g poltertab@alpha` |
+
+To cut one:
+
+```bash
+npm version 1.2.0-beta.1     # bumps package.json, syncs the manifest, tags
+git push --follow-tags
+gh release create v1.2.0-beta.1 --generate-notes --prerelease
+```
+
+`npm version` runs `scripts/sync-manifest-version.js`, which keeps
+`chrome-extension/manifest.json` in step. The two files cannot hold the same
+string — Chrome rejects a manifest version with a prerelease identifier — so the
+numeric base goes in `version` and the full string in `version_name`.
+
+Publishing the release then runs the workflow: tests, a version-consistency
+check, `npm publish --provenance` on the resolved tag, and the extension zip
+gets built and attached to the release.
+
+The checks refuse to publish rather than guess. A tag that disagrees with
+`package.json`, a manifest left behind, or a stable version on a release marked
+*pre-release* all fail the run — that last one because it would otherwise land on
+`latest` and become the default install for everyone.
+
+Use the workflow's manual trigger (`dry_run: true`) to rehearse all of it
+without publishing.
+
+## Tests
+
+```bash
+npm install
+npm test
+```
+
+No framework and no browser needed. Two suites run:
+
+- `mcp-server/test/run.js` — content-script injection idempotence, shadow DOM
+  piercing, cross-frame search, the tab-navigation load race, and the MCP server
+  end to end. It spawns real server processes against a fake extension on port
+  `7931`, so it never disturbs a PolterTab already running on `7822`.
+- `test/setup.test.js` — the installer: scope resolution, skill install, and
+  `CLAUDE.md` idempotence. Every case runs in a throwaway temp directory, so a
+  leaked write cannot reach your real `~/.claude`.

package/assets/claude-md-snippet.md

@@ -0,0 +1,17 @@
+<!-- poltertab -->
+## Browser Control (PolterTab)
+
+PolterTab drives the user's real Chrome profile through MCP tools prefixed
+`browser_` — already-logged-in sessions, in a window the user can see. There is
+no headless browser to launch.
+
+Start with `browser_snapshot` to see the page (it pierces shadow DOM and child
+frames), then act with `browser_click`, `browser_fill`, `browser_navigate`, or
+`browser_scrape`. For virtualized or obfuscated pages, prefer
+`browser_smart_scroll` + `browser_get_network_state` over DOM scraping.
+
+Read the `browser-navigation-strategy` skill before working a complex site.
+
+Because this is the user's live browser, confirm before anything that sends,
+buys, posts, or deletes.
+<!-- /poltertab -->

package/bin/poltertab.js

@@ -0,0 +1,32 @@
+#!/usr/bin/env node
+// Single entry point for both halves of the package.
+//
+//   poltertab          start the MCP server on stdio — this is what goes in the
+//                      MCP client config, which is why it is the bare default
+//   poltertab setup    interactive installer
+//
+// The server must own stdout: it is the JSON-RPC channel. Nothing in this file
+// prints on the default path.
+
+const arg = process.argv[2];
+
+if (arg === "setup") {
+  require("./setup.js").run(process.argv.slice(3)).catch((err) => {
+    console.error(`\n  setup failed: ${err.message}\n`);
+    process.exit(1);
+  });
+} else if (arg === "--version" || arg === "-v") {
+  console.log(require("../package.json").version);
+} else if (arg === "--help" || arg === "-h") {
+  console.log(`
+  poltertab — browser control for AI agents
+
+    poltertab           start the MCP server (stdio)
+    poltertab setup     install skill, CLAUDE.md section, and MCP registration
+    poltertab --version
+
+  setup flags: --global | --project  (skips the prompt)
+`);
+} else {
+  require("../mcp-server/index.js");
+}

package/bin/setup.js

@@ -0,0 +1,216 @@
+// `poltertab setup` — interactive installer.
+//
+// Three things have to land for PolterTab to work end to end:
+//   1. the navigation-strategy skill, so the agent knows how to drive a browser
+//   2. a CLAUDE.md section, so it knows the tools exist at all
+//   3. an MCP server registration, so the tools are actually connected
+//
+// The fourth thing — the Chrome extension — cannot be installed from a
+// terminal, so we hand over a link and stop.
+//
+// Everything here is re-runnable. A user who runs setup twice (or upgrades and
+// runs it again) must not end up with two copies of the snippet or a corrupted
+// config, so each step checks for its own prior work.
+
+const fs = require("fs");
+const os = require("os");
+const path = require("path");
+const readline = require("readline");
+const { spawnSync } = require("child_process");
+
+const PKG = path.join(__dirname, "..");
+const SKILL_SRC = path.join(PKG, "skills");
+const SNIPPET_SRC = path.join(PKG, "assets", "claude-md-snippet.md");
+
+// Bump to the Chrome Web Store listing once it clears review. The GitHub
+// release stays valid either way, so this is a one-line switch.
+const EXTENSION_URL = "https://github.com/abhinav162/poltertab/releases/latest";
+
+// Identifies our section in a CLAUDE.md we do not own. Presence means
+// "already installed" — this is the whole idempotency check for step 2.
+const MARKER = "<!-- poltertab -->";
+
+const c = {
+  dim: (s) => `\x1b[2m${s}\x1b[0m`,
+  bold: (s) => `\x1b[1m${s}\x1b[0m`,
+  green: (s) => `\x1b[32m${s}\x1b[0m`,
+  yellow: (s) => `\x1b[33m${s}\x1b[0m`,
+  cyan: (s) => `\x1b[36m${s}\x1b[0m`,
+};
+
+// --- steps -----------------------------------------------------------------
+
+// Global installs live under the home directory and apply everywhere. Project
+// installs live in the working directory, so a repo can carry browser access
+// without the user granting it to every other project on the machine.
+//
+// Note the asymmetry: skills always sit in `.claude/skills`, but project
+// instructions sit at `./CLAUDE.md` while global ones sit at
+// `~/.claude/CLAUDE.md`. Claude Code loads those two paths; a project-level
+// `.claude/CLAUDE.md` is read by nothing.
+function resolvePaths(scope, { home = os.homedir(), cwd = process.cwd() } = {}) {
+  if (scope === "global") {
+    return {
+      skillsDir: path.join(home, ".claude", "skills"),
+      claudeMd: path.join(home, ".claude", "CLAUDE.md"),
+      mcpScope: "user",
+    };
+  }
+  if (scope === "project") {
+    return {
+      skillsDir: path.join(cwd, ".claude", "skills"),
+      claudeMd: path.join(cwd, "CLAUDE.md"),
+      mcpScope: "project",
+    };
+  }
+  throw new Error(`Unknown install scope: ${scope}`);
+}
+
+function installSkill(skillsDir) {
+  const name = "browser-navigation-strategy";
+  const dest = path.join(skillsDir, name);
+  fs.mkdirSync(dest, { recursive: true });
+  fs.copyFileSync(
+    path.join(SKILL_SRC, name, "SKILL.md"),
+    path.join(dest, "SKILL.md"),
+  );
+  return path.join(dest, "SKILL.md");
+}
+
+// Returns "created" | "appended" | "skipped" so the caller can report honestly
+// rather than claiming it wrote something it left alone.
+function updateClaudeMd(claudeMd) {
+  const snippet = fs.readFileSync(SNIPPET_SRC, "utf8").trimEnd() + "\n";
+
+  if (!fs.existsSync(claudeMd)) {
+    fs.mkdirSync(path.dirname(claudeMd), { recursive: true });
+    fs.writeFileSync(claudeMd, snippet);
+    return "created";
+  }
+
+  const existing = fs.readFileSync(claudeMd, "utf8");
+  if (existing.includes(MARKER)) return "skipped";
+
+  // A file that does not end in a newline would otherwise run straight into
+  // our heading and swallow it into the user's last paragraph.
+  const gap = existing.endsWith("\n") ? "\n" : "\n\n";
+  fs.appendFileSync(claudeMd, gap + snippet);
+  return "appended";
+}
+
+// Registration goes through the `claude` CLI on purpose. The user-scope config
+// lives in ~/.claude.json alongside a large amount of unrelated Claude Code
+// state; rewriting that file ourselves risks clobbering it on a bad parse or a
+// concurrent write. `claude mcp add` owns that file and is safe to delegate to.
+function registerServer(mcpScope) {
+  const r = spawnSync(
+    "claude",
+    ["mcp", "add", "--scope", mcpScope, "poltertab", "poltertab"],
+    { encoding: "utf8" },
+  );
+
+  if (r.error && r.error.code === "ENOENT") {
+    return { ok: false, reason: "claude CLI not found on PATH" };
+  }
+  if (r.status !== 0) {
+    const out = `${r.stderr || ""}${r.stdout || ""}`.trim();
+    // Re-running setup hits this: the server is already registered, which is
+    // the desired end state, not a failure.
+    if (/already exists/i.test(out)) return { ok: true, already: true };
+    return { ok: false, reason: out.split("\n")[0] || `exit ${r.status}` };
+  }
+  return { ok: true };
+}
+
+// --- wizard ----------------------------------------------------------------
+
+function ask(rl, question) {
+  return new Promise((resolve) => rl.question(question, resolve));
+}
+
+async function chooseScope(rl) {
+  console.log(`${c.bold("Where should PolterTab be available?")}\n`);
+  console.log(`  ${c.cyan("1")}  All projects        ${c.dim("(~/.claude)")}`);
+  console.log(`  ${c.cyan("2")}  This project only   ${c.dim(process.cwd())}\n`);
+
+  for (;;) {
+    const a = (await ask(rl, "  Choose [1]: ")).trim();
+    if (a === "" || a === "1") return "global";
+    if (a === "2") return "project";
+    console.log(c.yellow("  Enter 1 or 2."));
+  }
+}
+
+async function run(argv = []) {
+  console.log(`\n  ${c.bold("PolterTab")} — browser control for AI agents\n`);
+
+  const rl = readline.createInterface({
+    input: process.stdin,
+    output: process.stdout,
+  });
+
+  let scope;
+  try {
+    scope = argv.includes("--global")
+      ? "global"
+      : argv.includes("--project")
+        ? "project"
+        : await chooseScope(rl);
+  } finally {
+    rl.close();
+  }
+
+  const paths = resolvePaths(scope);
+  console.log("");
+
+  // Each step reports what it actually did. A step that fails is reported with
+  // the manual alternative rather than aborting the rest of the install —
+  // partial setup the user can finish beats no setup at all.
+  try {
+    const skill = installSkill(paths.skillsDir);
+    console.log(`  ${c.green("✓")} skill installed      ${c.dim(skill)}`);
+  } catch (err) {
+    console.log(`  ${c.yellow("!")} skill install failed ${c.dim(err.message)}`);
+  }
+
+  try {
+    const what = updateClaudeMd(paths.claudeMd);
+    const label = { created: "created", appended: "updated", skipped: "already present" }[what];
+    console.log(`  ${c.green("✓")} CLAUDE.md ${label.padEnd(10)} ${c.dim(paths.claudeMd)}`);
+  } catch (err) {
+    console.log(`  ${c.yellow("!")} CLAUDE.md failed     ${c.dim(err.message)}`);
+  }
+
+  const reg = registerServer(paths.mcpScope);
+  if (reg.ok) {
+    const label = reg.already ? "already registered" : "registered";
+    console.log(`  ${c.green("✓")} MCP server ${label}  ${c.dim(`scope: ${paths.mcpScope}`)}`);
+  } else {
+    console.log(`  ${c.yellow("!")} MCP server not registered — ${reg.reason}`);
+    console.log(c.dim(`      run: claude mcp add --scope ${paths.mcpScope} poltertab poltertab`));
+  }
+
+  console.log(`\n  ${c.bold("One step left — install the Chrome extension:")}`);
+  console.log(`  ${c.cyan(EXTENSION_URL)}`);
+  console.log(c.dim("      unzip it, then chrome://extensions → Developer mode → Load unpacked\n"));
+  console.log(`  ${c.dim("Restart Claude Code to pick up the new tools.")}\n`);
+}
+
+module.exports = {
+  run,
+  resolvePaths,
+  installSkill,
+  updateClaudeMd,
+  registerServer,
+  MARKER,
+  EXTENSION_URL,
+};
+
+// Guard so the test suite can require this file without triggering a wizard
+// that would prompt on stdin and write to the real ~/.claude.
+if (require.main === module) {
+  run(process.argv.slice(3)).catch((err) => {
+    console.error(`\n  setup failed: ${err.message}\n`);
+    process.exit(1);
+  });
+}