@btraut/browser-bridge 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Brent Traut
+
+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,117 @@
+# Browser Bridge
+
+Local Chrome control for coding agents. Browser Bridge provides a CLI and an
+optional MCP server that drive a real Chrome instance and read page state
+through a Chrome extension.
+
+## Requirements
+
+- Node.js 20+
+- Chrome (stable)
+- Browser Bridge extension (Chrome Web Store; listing coming soon)
+- Local-only usage (all services bind to 127.0.0.1)
+
+## Install
+
+```bash
+npm i -g @btraut/browser-bridge
+browser-bridge --help
+```
+
+## Quickstart
+
+1. Install the Chrome Web Store extension (listing coming soon). For local
+   testing without the store, you can load unpacked from:
+   - this repo: `packages/extension`
+   - npm install: `$(npm root -g)/@btraut/browser-bridge/extension`
+2. Install the Browser Bridge skill (see below).
+3. (Optional) Add Browser Bridge to your MCP client (Codex or Claude Code below).
+4. Run a quick CLI check:
+
+```bash
+browser-bridge session create
+# Use the session_id from the output for the next commands.
+browser-bridge drive navigate --session-id <id> --url https://example.com
+browser-bridge inspect dom-snapshot --session-id <id>
+browser-bridge session close --session-id <id>
+```
+
+## Skills (Codex + Claude Code)
+
+Copy the Browser Bridge skill into your agent skills directory:
+
+```bash
+# From this repo:
+# cp -R docs/skills/browser-bridge ~/.agents/skills/browser-bridge
+# cp -R docs/skills/browser-bridge ~/.claude/skills/browser-bridge
+
+# From npm (global install):
+cp -R "$(npm root -g)/@btraut/browser-bridge/skills/browser-bridge" ~/.agents/skills/browser-bridge
+cp -R "$(npm root -g)/@btraut/browser-bridge/skills/browser-bridge" ~/.claude/skills/browser-bridge
+```
+
+Restart your agent app if it does not pick up the new skill automatically.
+
+## MCP Server (Optional)
+
+The MCP server runs over stdio and forwards tool calls to Core. It is optional,
+since you can use the CLI directly. MCP clients launch it automatically when
+needed, so you typically do not run it yourself.
+
+- Manual start (debugging): `browser-bridge mcp`
+- Use your MCP client to call `tools/list`, then `session.create`
+- Override Core host/port with `--host`, `--port`, or `BROWSER_BRIDGE_CORE_HOST` /
+  `BROWSER_BRIDGE_CORE_PORT`.
+
+## Add MCP (Codex CLI)
+
+```bash
+codex mcp add browser-bridge -- browser-bridge mcp
+```
+
+Optional custom host/port:
+
+```bash
+codex mcp add browser-bridge \
+  --env BROWSER_BRIDGE_CORE_HOST=127.0.0.1 \
+  --env BROWSER_BRIDGE_CORE_PORT=3210 \
+  -- browser-bridge mcp
+```
+
+## Add MCP (Claude Code)
+
+```bash
+claude mcp add --transport stdio browser-bridge -- browser-bridge mcp
+```
+
+Optional custom host/port:
+
+```bash
+claude mcp add --transport stdio browser-bridge \
+  --env BROWSER_BRIDGE_CORE_HOST=127.0.0.1 \
+  --env BROWSER_BRIDGE_CORE_PORT=3210 \
+  -- browser-bridge mcp
+```
+
+## Diagnostics
+
+- CLI: `browser-bridge diagnostics doctor --session-id <id>`
+- Reports extension and debugger status alongside session state.
+
+## Security Model (v1)
+
+- Extension <-> Core WebSocket has no authentication; trust local machine only.
+- Do not expose the port or run the Core daemon on shared hosts.
+
+## Development Notes
+
+If you are contributing locally, load the extension unpacked:
+
+1. Open Chrome and navigate to `chrome://extensions`.
+2. Enable **Developer mode**.
+3. Click **Load unpacked** and select `packages/extension` (repo).
+4. Confirm the extension's background service worker is running.
+5. Start the Core daemon (or run `browser-bridge session create`) so the
+   extension can connect to `127.0.0.1`.
+
+Additional manual test flows live in `docs/manual-test.md`.

package/dist/api.d.ts

@@ -0,0 +1,35 @@
+export type CoreServerStartOptions = {
+  host?: string;
+  port?: number;
+};
+
+export type CoreServerHandle = {
+  host: string;
+  port: number;
+  // Intentionally opaque: avoid forcing consumers to install @types/* packages.
+  server: unknown;
+};
+
+export declare const startCoreServer: (
+  options?: CoreServerStartOptions
+) => Promise<CoreServerHandle>;
+
+export type McpAdapterOptions = {
+  name?: string;
+  version?: string;
+  host?: string;
+  port?: number | string;
+  timeoutMs?: number;
+  // Advanced: allow providing a preconfigured Core client.
+  coreClient?: unknown;
+};
+
+export type McpAdapterStartHandle = {
+  server: unknown;
+  client: unknown;
+  transport: unknown;
+};
+
+export declare const startMcpServer: (
+  options?: McpAdapterOptions
+) => Promise<McpAdapterStartHandle>;