chromeflow 0.7.1 → 0.9.8

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Andrew Robertson (NeoDrewX)
+
+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

@@ -1,173 +1,68 @@
-<p align="center">
-  <img src="assets/icon.png" width="120" alt="Chromeflow" />
-</p>
+# chromeflow — MCP server
 
-<h1 align="center">Chromeflow</h1>
+The standalone npm package for the [Chromeflow](https://chromeflow.run) MCP server. Lets Claude Code, Codex CLI, or any MCP-compatible agent drive your real Chrome browser with sessions intact — clicks, fills forms, captures API keys to `.env`, downloads authenticated files.
 
-When Claude needs you to set up Stripe, grab API keys, configure a third-party service, or do anything in a browser — Chromeflow takes over. It highlights what to click, fills in fields it knows, clicks buttons automatically, uploads files, and writes captured values straight to your `.env`.
+## Recommended install — the plugin
 
-## Why Chromeflow?
+For **Claude Code**:
 
-Existing browser automation tools (Playwright, Browser Use, Puppeteer) launch a **fresh, empty browser** — no cookies, no sessions, no extensions. Every time they start, you're logged out of everything and can't handle 2FA.
-
-Chromeflow works in **your actual Chrome browser**, where you're already logged into Stripe, AWS, Supabase, and everything else. Claude automates what it can (clicking buttons, filling forms, uploading files) and pauses for anything that needs you (passwords, 2FA, payment details).
-
-| | Chromeflow | Playwright / Browser Use |
-|---|---|---|
-| **Browser** | Your real Chrome (sessions intact) | Fresh instance, logged out of everything |
-| **Auth / 2FA** | Already handled — pauses when needed | Can't handle — blocks completely |
-| **Page understanding** | DOM queries (fast, cheap, reliable) | Screenshots + vision model (slow, expensive) |
-| **Human-in-the-loop** | Highlights, pauses on sensitive input | Fully autonomous, no interaction |
-| **Integration** | MCP server for Claude Code | Standalone, not Claude Code aware |
-| **Credential capture** | Reads API keys → writes to `.env` | Not designed for this |
-
-## How it works
-
-Chromeflow is two things that work together:
-
-- **MCP server** — gives Claude Code a set of browser tools (`open_page`, `click_element`, `fill_form`, `set_file_input`, `read_element`, `write_to_env`, etc.)
-- **Chrome extension** — receives those commands and acts on the active tab (highlights, clicks, fills, uploads files, captures screenshots)
-
-Claude drives the flow. You only touch the browser for things that genuinely need you — login, passwords, payment details, personal choices.
-
-## Setup
-
-**1. Run the setup wizard** from your project directory:
-
-```bash
-npx chromeflow setup
+```
+/plugin marketplace add https://gitlab.com/NeoDrew/chromeflow.git
+/plugin install 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. Install the Chrome extension** (one time):
-
-The setup wizard opens the Chrome Web Store for you — click **Add to Chrome**.
-
-Or install directly: [chromewebstore.google.com/detail/chromeflow/lkdchdgkbkodliefobkkhiegjdiidime](https://chromewebstore.google.com/detail/chromeflow/lkdchdgkbkodliefobkkhiegjdiidime)
-
-The extension persists across Chrome restarts. You only do this once.
-
-**3. Restart Claude Code.**
-
-That's it. Claude will automatically reach for Chromeflow whenever a task needs browser interaction.
-
-## Usage
-
-Just ask Claude normally:
-
-> "Set up Stripe for this project — create a product with monthly and annual pricing, capture the price IDs into .env"
-
-> "Go to Supabase and get my project's anon key and service role key"
-
-> "Help me configure SendGrid webhooks for this app"
-
-Claude will navigate, highlight steps, click what it can, pause for anything sensitive, and write values to your `.env` automatically.
-
-## What Claude can do
-
-| Capability | Tools |
-|------------|-------|
-| Navigate pages, open new tabs | `open_page`, `list_tabs`, `switch_to_tab` |
-| Click buttons and links | `click_element` (with `nth` for duplicates) |
-| Fill single fields | `fill_input` (with `nth` for duplicates) |
-| Fill multiple fields in one call | `fill_form` |
-| Upload files (even hidden inputs) | `set_file_input` |
-| Read page content as text | `get_page_text` (with `selector` scoping) |
-| Inspect all form fields | `get_form_fields` |
-| Scroll to a known element | `scroll_to_element` |
-| Highlight elements for the user | `highlight_region`, `find_and_highlight` |
-| Wait for the user to click | `wait_for_click` |
-| Wait for async changes | `wait_for_selector` |
-| Run arbitrary JS | `execute_script` |
-| Read browser console output | `get_console_logs` |
-| Capture credentials to `.env` | `read_element`, `write_to_env` |
-| Screenshot (Claude-only by default; pass `copy_to_clipboard` / `save_to` to share) | `take_screenshot` |
-| Screenshot the terminal window | `capture_terminal` |
-| Save/restore form state across tabs | `save_page_state`, `restore_page_state` |
-
-### File uploads
-
-`set_file_input` uses Chrome DevTools Protocol to bypass the browser's file-input script restriction — the same mechanism used by Playwright and Puppeteer. It works even when the `<input type=file>` is hidden behind a custom drag-and-drop zone.
+For **Codex CLI**:
 
 ```
-set_file_input("Upload", "/Users/you/Downloads/task.zip")
+codex plugin marketplace add https://gitlab.com/NeoDrew/chromeflow.git
+/plugins
 ```
 
-### Terminal screenshots
-
-`capture_terminal` screenshots the terminal window (Terminal, iTerm2, Warp, VS Code, Ghostty, etc.) and saves it as a PNG. Use this with `set_file_input` to upload terminal output to a web form.
-
-### Dedicated Claude window
-
-Click the Chromeflow extension icon and use **"Use this window for Claude"** to lock Claude's browser operations to a specific Chrome window. This lets you freely use other Chrome windows without Claude interfering.
-
-### Running multiple Claude Code instances in parallel
-
-Chromeflow supports up to 11 Claude Code sessions running in parallel, each automating a different Chrome window without touching the others.
-
-**How it works:**
-- Each CC session spawns its own Chromeflow MCP server, which auto-discovers a free port in the range `7878-7888` (first session gets 7878, second gets 7879, etc.).
-- The Chrome extension maintains one WebSocket connection per port and tracks per-port window assignments.
-- Every browser tool call is routed to the Chrome window assigned to the port the request came in on.
+The plugin bundles the MCP server, the usage skill, permission allowlists, and the SessionStart hook in a single install. No npm dependency, no per-project setup.
 
-**Setup:**
-1. Start your first Claude Code session as normal — its Chromeflow will claim port 7878.
-2. Start a second CC session in another terminal — its Chromeflow auto-falls-back to 7879.
-3. Click the Chromeflow extension icon. The popup now shows **one row per instance** (Port 7878, Port 7879, ...) each with a green dot when live.
-4. In Chrome **window A**, open the popup and click **"Use this window"** next to Port 7878.
-5. Switch to **window B**, open the popup, and click **"Use this window"** next to Port 7879.
+## Manual install — this package
 
-That's it. Each CC session now drives its own Chrome window — you can run a DataAnnotation task in one window while the other session fills out a Stripe dashboard in another, with zero collision.
-
-Single-instance usage is unchanged and fully backwards compatible — the old per-window assignment is auto-migrated on first load.
-
-## Adding to another project
-
-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:
+For environments where the plugin isn't an option (custom MCP clients, hand-crafted `.mcp.json`, CI test harnesses), install this npm package and wire it manually.
 
 ```bash
-npx chromeflow setup
+npm install -g chromeflow
+# or run on demand
+npx -y chromeflow
 ```
 
-## Commands
+Then add to your MCP-client config (`.mcp.json`, `mcp.config`, or wherever your agent looks):
+
+```json
+{
+  "mcpServers": {
+    "chromeflow": {
+      "command": "npx",
+      "args": ["-y", "chromeflow"]
+    }
+  }
+}
+```
 
-| 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) |
+You still need the [Chromeflow Chrome extension](https://chromewebstore.google.com/detail/chromeflow/lkdchdgkbkodliefobkkhiegjdiidime) installed — it's the part that actually drives Chrome. The MCP server is a stdio↔WebSocket bridge between your agent and the extension.
 
-## Development
+## What's in this package
 
-```bash
-git clone https://github.com/NeoDrew/chromeflow
-cd chromeflow
-npm install
-npm run build
-```
+A single bundled file: `bin/chromeflow.mjs` (~890 KB ESM), built from `packages/mcp-server/src/` via esbuild. Reading source? See the [GitLab repository](https://gitlab.com/NeoDrew/chromeflow).
 
-Then run setup using the local build:
+## Tools exposed (v0.9.5)
 
-```bash
-node packages/mcp-server/dist/index.js setup
-```
-
-To rebuild on changes:
+28 MCP tools across navigation, reading, interaction, waiting, privileged network, highlight + handoff, and utility. The full catalogue lives in [CLAUDE.md](https://gitlab.com/NeoDrew/chromeflow/-/blob/main/CLAUDE.md) — read that before writing an agent that calls these tools.
 
-```bash
-npm run dev:mcp   # watches mcp-server
-npm run dev:ext   # watches extension
-```
+## Links
 
-After rebuilding the extension, reload it from `chrome://extensions`.
+- **Website**: https://chromeflow.run
+- **Compare to Playwright / Browser Use / Puppeteer**: https://chromeflow.run/compare
+- **Use cases** (Stripe, Canvas, OAuth, API keys): https://chromeflow.run/use-cases
+- **FAQ**: https://chromeflow.run/faq
+- **GitLab**: https://gitlab.com/NeoDrew/chromeflow
+- **Chrome Web Store**: https://chromewebstore.google.com/detail/chromeflow/lkdchdgkbkodliefobkkhiegjdiidime
+- **MCP Registry**: `run.chromeflow/chromeflow` (DNS-verified namespace via chromeflow.run)
 
-## Requirements
+## License
 
-- Claude Code
-- Chrome (or any Chromium browser)
-- Node.js 22+
+MIT — see [LICENSE](https://gitlab.com/NeoDrew/chromeflow/-/blob/main/LICENSE).