chromeflow 0.1.13 → 0.1.17

package/CLAUDE.md

@@ -49,6 +49,7 @@ Do NOT ask "should I open the browser?" — just do it. The user expects seamles
 3. For each step:
    a. Claude acts directly:
         click_element("Save")               — press buttons/links Claude can press
+        wait_for_selector(".success") or get_page_text() — ALWAYS confirm after click; click_element returns after 600ms regardless of outcome
         fill_input("Product name", "Pro")   — fill fields Claude knows the answer to
         clear_overlays()                    — call this immediately after fill_input succeeds
         scroll_page("down")                 — reveal off-screen content then retry
@@ -102,6 +103,7 @@ Use the absolute path for `envPath` — it's the Claude Code working directory +
 ## Error handling
 - After any action → `get_page_text()` to check for errors (not `take_screenshot`)
 - After `click_element("Save")` / form submission → use `get_page_text()` or `wait_for_selector` to confirm. Never use `wait_for_navigation` — most form saves don't navigate.
+- After `click_element` → always confirm with `wait_for_selector(".selector")` or `get_page_text()`. `click_element` returns success after 600ms even if the action had no effect.
 - `click_element` not found → `scroll_page("down")` then retry
 - Still not found → `get_elements()` to get exact coords, then `highlight_region(x,y,w,h,msg)` using those coords. Only use `take_screenshot()` if you need to visually inspect the page.
 - `fill_input` not found → `click_element(hint)` to focus the field, then retry `fill_input`. If still failing, use `find_and_highlight(hint, "Click here — I'll fill it in")` (NO `valueToType`) then `wait_for_click()` then retry `fill_input` — after the user focuses the field by clicking, the active-element fallback fills it automatically. `find_and_highlight` uses DOM positioning (pixel-perfect) — only fall back to `take_screenshot` + `highlight_region` if `find_and_highlight` returns false. After `fill_input` succeeds, immediately call `clear_overlays()` to remove the highlight. Only use `valueToType` when the user genuinely must type the value themselves (e.g. password, personal data).

package/README.md

@@ -19,7 +19,11 @@ Claude drives the flow. You only touch the browser for things that genuinely nee
 npx chromeflow setup
 ```
 
-This registers the MCP server in `~/.claude.json` and writes a `CLAUDE.md` into your project so Claude knows when and how to use Chromeflow.
+This:
+- Registers the MCP server in `~/.claude.json`
+- Writes `CLAUDE.md` into your project so Claude knows when and how to use Chromeflow
+- Adds a hint to `~/.claude/CLAUDE.md` so Claude will suggest `npx chromeflow setup` in any project that isn't yet configured
+- Pre-approves Chromeflow tools in `.claude/settings.local.json` (no per-action prompts)
 
 **2. Load the Chrome extension** (one time):
 
@@ -48,13 +52,19 @@ Claude will navigate, highlight steps, click what it can, pause for anything sen
 
 ## Adding to another project
 
-Run the setup wizard from the new project's directory:
+Run setup from the new project's directory — the MCP server is already registered globally, this just drops `CLAUDE.md` and tool permissions into the project:
 
 ```bash
 npx chromeflow setup
 ```
 
-The MCP server is already registered globally — this just adds `CLAUDE.md` to the project.
+## Commands
+
+| Command | What it does |
+|---------|-------------|
+| `npx chromeflow setup` | Register MCP server, write project `CLAUDE.md`, pre-approve tools |
+| `npx chromeflow update` | Refresh the project `CLAUDE.md` with the latest instructions |
+| `npx chromeflow uninstall` | Remove all Chromeflow config (MCP entry, `CLAUDE.md` sections, tool permissions) |
 
 ## Development
 

package/dist/index.js

@@ -6,7 +6,7 @@ import { registerBrowserTools } from "./tools/browser.js";
 import { registerHighlightTools } from "./tools/highlight.js";
 import { registerCaptureTools } from "./tools/capture.js";
 import { registerFlowTools } from "./tools/flow.js";
-import { runSetup, runUpdate } from "./setup.js";
+import { runSetup, runUpdate, runUninstall } from "./setup.js";
 if (process.argv[2] === "setup") {
   runSetup().catch((err) => {
     console.error(err);
@@ -17,6 +17,11 @@ if (process.argv[2] === "setup") {
     console.error(err);
     process.exit(1);
   });
+} else if (process.argv[2] === "uninstall") {
+  runUninstall().catch((err) => {
+    console.error(err);
+    process.exit(1);
+  });
 } else {
   main().catch((err) => {
     console.error("[chromeflow] Fatal error:", err);
@@ -27,7 +32,7 @@ async function main() {
   const bridge = new WsBridge();
   const server = new McpServer({
     name: "chromeflow",
-    version: "0.1.13"
+    version: "0.1.14"
   });
   registerBrowserTools(server, bridge);
   registerHighlightTools(server, bridge);

package/dist/setup.js

@@ -1,4 +1,4 @@
-import { readFileSync, writeFileSync, existsSync } from "fs";
+import { readFileSync, writeFileSync, existsSync, mkdirSync } from "fs";
 import { homedir } from "os";
 import { join, resolve, dirname } from "path";
 import { fileURLToPath } from "url";
@@ -139,6 +139,50 @@ function patchProjectClaudeMd(cwd, force = false) {
   writeFileSync(claudeMdPath, content);
   return "created";
 }
+const CHROMEFLOW_TOOLS = [
+  "open_page",
+  "take_screenshot",
+  "clear_overlays",
+  "get_elements",
+  "execute_script",
+  "fill_input",
+  "read_element",
+  "get_page_text",
+  "write_to_env",
+  "scroll_page",
+  "click_element",
+  "wait_for_click",
+  "wait_for_selector",
+  "mark_step_done",
+  "find_and_highlight",
+  "highlight_region",
+  "show_guide_panel"
+].map((t) => `mcp__chromeflow__${t}`);
+function patchSettingsLocalJson(cwd) {
+  const claudeDir = join(cwd, ".claude");
+  const settingsPath = join(claudeDir, "settings.local.json");
+  let settings = {};
+  if (existsSync(settingsPath)) {
+    try {
+      settings = JSON.parse(readFileSync(settingsPath, "utf8"));
+    } catch {
+      settings = {};
+    }
+  }
+  if (!settings.permissions || typeof settings.permissions !== "object") {
+    settings.permissions = {};
+  }
+  const perms = settings.permissions;
+  const existing = Array.isArray(perms.allow) ? perms.allow : [];
+  const withoutChromeflow = existing.filter((t) => !t.startsWith("mcp__chromeflow__"));
+  const merged = [...withoutChromeflow, ...CHROMEFLOW_TOOLS];
+  const changed = merged.length !== existing.length || CHROMEFLOW_TOOLS.some((t) => !existing.includes(t));
+  if (!changed) return "already-present";
+  perms.allow = merged;
+  if (!existsSync(claudeDir)) mkdirSync(claudeDir, { recursive: true });
+  writeFileSync(settingsPath, JSON.stringify(settings, null, 2) + "\n");
+  return "updated";
+}
 function tryOpenExtensionsPage() {
   try {
     execSync('open -a "Google Chrome" "chrome://extensions"', { stdio: "ignore" });
@@ -152,11 +196,31 @@ function tryOpenExtensionsPage() {
     }
   }
 }
+function patchGlobalClaudeMd() {
+  const globalClaudeMdPath = join(HOME, ".claude", "CLAUDE.md");
+  const hint = `## Chromeflow
+
+chromeflow is installed globally as an MCP server.
+
+If you are working in a project and the project's CLAUDE.md does not contain chromeflow
+instructions, tell the user: "Run \`npx chromeflow setup\` in this project directory to
+configure chromeflow for it."
+`;
+  if (existsSync(globalClaudeMdPath)) {
+    const existing = readFileSync(globalClaudeMdPath, "utf8");
+    if (existing.includes("chromeflow")) return "already-present";
+    writeFileSync(globalClaudeMdPath, existing.trimEnd() + "\n\n" + hint);
+    return "appended";
+  }
+  const dir = join(HOME, ".claude");
+  if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
+  writeFileSync(globalClaudeMdPath, hint);
+  return "created";
+}
 async function runSetup() {
   const scriptPath = fileURLToPath(import.meta.url);
   const distDir = dirname(scriptPath);
   const serverScriptPath = resolve(distDir, "index.js");
-  const extensionDistPath = resolve(distDir, "..", "..", "extension", "dist");
   console.log("\nChromeflow Setup\n" + "\u2500".repeat(40));
   patchClaudeJson(serverScriptPath);
   const viaNpx = isRunningViaNpx();
@@ -164,6 +228,7 @@ async function runSetup() {
   console.log(viaNpx ? `  \u2192 npx -y chromeflow (auto-updates)` : `  \u2192 node ${serverScriptPath}`);
   const cwd = process.cwd();
   const mdResult = patchProjectClaudeMd(cwd);
+  const settingsResult = patchSettingsLocalJson(cwd);
   if (mdResult === "already-present") {
     console.log("\u2713 CLAUDE.md already has chromeflow instructions (run `npx chromeflow update` to refresh)");
   } else if (mdResult === "appended") {
@@ -171,6 +236,11 @@ async function runSetup() {
   } else {
     console.log(`\u2713 Created ${join(cwd, "CLAUDE.md")}`);
   }
+  if (settingsResult === "already-present") {
+    console.log("\u2713 .claude/settings.local.json already allows chromeflow tools");
+  } else {
+    console.log("\u2713 Added chromeflow tools to .claude/settings.local.json (no approval prompts)");
+  }
   console.log("\nChrome extension (one-time manual step):");
   const opened = tryOpenExtensionsPage();
   if (opened) {
@@ -178,11 +248,71 @@ async function runSetup() {
   } else {
     console.log("  Open chrome://extensions in Chrome.");
   }
+  const extensionDistPath = resolve(dirname(fileURLToPath(import.meta.url)), "..", "..", "extension", "dist");
   console.log("  1. Enable Developer mode (top-right toggle)");
   console.log("  2. Click 'Load unpacked'");
   console.log(`  3. Select: ${extensionDistPath}`);
+  const globalResult = patchGlobalClaudeMd();
+  if (globalResult === "already-present") {
+    console.log("\u2713 ~/.claude/CLAUDE.md already has chromeflow hint");
+  } else if (globalResult === "appended") {
+    console.log("\u2713 Appended chromeflow hint to ~/.claude/CLAUDE.md");
+  } else {
+    console.log("\u2713 Created ~/.claude/CLAUDE.md with chromeflow hint");
+  }
   console.log("\nDone. Restart Claude Code to activate chromeflow.\n");
 }
+async function runUninstall() {
+  const cwd = process.cwd();
+  console.log("\nChromeflow Uninstall\n" + "\u2500".repeat(40));
+  if (existsSync(CLAUDE_JSON_PATH)) {
+    try {
+      const config = JSON.parse(readFileSync(CLAUDE_JSON_PATH, "utf8"));
+      if (config.mcpServers && typeof config.mcpServers === "object") {
+        delete config.mcpServers.chromeflow;
+      }
+      writeFileSync(CLAUDE_JSON_PATH, JSON.stringify(config, null, 2) + "\n");
+      console.log("\u2713 Removed chromeflow MCP server from ~/.claude.json");
+    } catch {
+      console.log("  Could not update ~/.claude.json (skipping)");
+    }
+  }
+  const claudeMdPath = join(cwd, "CLAUDE.md");
+  if (existsSync(claudeMdPath)) {
+    const existing = readFileSync(claudeMdPath, "utf8");
+    if (existing.includes("# Chromeflow")) {
+      const idx = existing.indexOf("# Chromeflow");
+      const before = existing.slice(0, idx).trimEnd();
+      writeFileSync(claudeMdPath, before ? before + "\n" : "");
+      console.log(`\u2713 Removed chromeflow section from ${claudeMdPath}`);
+    }
+  }
+  const settingsPath = join(cwd, ".claude", "settings.local.json");
+  if (existsSync(settingsPath)) {
+    try {
+      const settings = JSON.parse(readFileSync(settingsPath, "utf8"));
+      const perms = settings.permissions;
+      if (perms && Array.isArray(perms.allow)) {
+        perms.allow = perms.allow.filter((t) => !t.startsWith("mcp__chromeflow__"));
+      }
+      writeFileSync(settingsPath, JSON.stringify(settings, null, 2) + "\n");
+      console.log("\u2713 Removed chromeflow tools from .claude/settings.local.json");
+    } catch {
+      console.log("  Could not update .claude/settings.local.json (skipping)");
+    }
+  }
+  const globalClaudeMdPath = join(HOME, ".claude", "CLAUDE.md");
+  if (existsSync(globalClaudeMdPath)) {
+    const existing = readFileSync(globalClaudeMdPath, "utf8");
+    if (existing.includes("## Chromeflow")) {
+      const idx = existing.indexOf("## Chromeflow");
+      const before = existing.slice(0, idx).trimEnd();
+      writeFileSync(globalClaudeMdPath, before ? before + "\n" : "");
+      console.log("\u2713 Removed chromeflow hint from ~/.claude/CLAUDE.md");
+    }
+  }
+  console.log("\nDone. Restart Claude Code to complete removal.\n");
+}
 async function runUpdate() {
   const cwd = process.cwd();
   console.log("\nChromeflow Update\n" + "\u2500".repeat(40));
@@ -194,9 +324,16 @@ async function runUpdate() {
   } else {
     console.log(`\u2713 Created ${join(cwd, "CLAUDE.md")}`);
   }
+  const settingsResult = patchSettingsLocalJson(cwd);
+  if (settingsResult === "already-present") {
+    console.log("\u2713 .claude/settings.local.json already up to date");
+  } else {
+    console.log("\u2713 Updated chromeflow tools in .claude/settings.local.json");
+  }
   console.log("Done.\n");
 }
 export {
   runSetup,
+  runUninstall,
   runUpdate
 };

package/dist/ws-bridge.js

@@ -62,7 +62,9 @@ class WsBridge {
         this.client = null;
         for (const [id, pending] of this.pending) {
           clearTimeout(pending.timer);
-          pending.reject(new Error("Extension disconnected"));
+          pending.reject(new Error(
+            "Chrome extension disconnected. Reload the chromeflow extension in Chrome and try again."
+          ));
           this.pending.delete(id);
         }
       });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "chromeflow",
-  "version": "0.1.13",
+  "version": "0.1.17",
   "description": "Browser guidance MCP server for Claude Code — highlights, clicks, fills, and captures from the web so you don't have to.",
   "type": "module",
   "bin": {