agentic-browser 1.0.3 → 1.1.0

package/AGENTS.md

@@ -59,8 +59,10 @@ AgenticBrowserCore → ControlApi → SessionManager → BrowserController (CDP)
 ```
 
 1. `createAgenticBrowserCore()` builds AppContext + ChromeCdpBrowserController
-2. Commands execute via CDP `Runtime.evaluate` on the browser page
-3. Results are recorded as evidence, indexed per-domain for memory search
+2. `createSession` either launches a new Chrome (`browser.launch()`) or connects to existing one (`browser.connect(cdpUrl)`) based on config
+3. Commands execute via CDP `Runtime.evaluate` on the browser page
+4. Results are recorded as evidence, indexed per-domain for memory search
+5. Connected sessions (pid=0) skip `process.kill` on terminate — the user's browser stays open
 
 ## Code Conventions
 
@@ -108,6 +110,8 @@ AgenticBrowserCore → ControlApi → SessionManager → BrowserController (CDP)
 
 - `AGENTIC_BROWSER_LOG_DIR` — base dir for sessions/memory/events (default: `.agentic-browser`)
 - `AGENTIC_BROWSER_CHROME_EXECUTABLE_PATH` — explicit Chrome path (auto-discovered if not set)
+- `AGENTIC_BROWSER_CDP_URL` — connect to an already-running Chrome via CDP (e.g. `http://127.0.0.1:9222`)
+- `AGENTIC_BROWSER_USER_PROFILE` — use real Chrome profile (`default`, `true`, or absolute path)
 
 ## MCP Server
 

package/README.md

@@ -37,12 +37,72 @@ npm run lint
 npm test
 ```
 
+## Connect to Existing Chrome / Use Your Profile
+
+By default, agentic-browser launches a fresh Chrome instance with an isolated profile. You can instead **connect to an already-running Chrome** or **launch Chrome with your real profile** (bookmarks, cookies, extensions, saved passwords).
+
+### Connect to a running Chrome
+
+Start Chrome yourself with remote debugging enabled:
+
+```bash
+# macOS
+/Applications/Google\ Chrome.app/Contents/MacOS/Google\ Chrome --remote-debugging-port=9222
+
+# Linux
+google-chrome --remote-debugging-port=9222
+
+# Windows
+chrome.exe --remote-debugging-port=9222
+```
+
+Then connect agentic-browser to it:
+
+```bash
+agentic-browser agent start --cdp-url http://127.0.0.1:9222
+# or low-level:
+agentic-browser session:start --cdp-url http://127.0.0.1:9222
+```
+
+When connected this way, stopping the session will **not** kill your Chrome process.
+
+### Launch Chrome with your real profile
+
+```bash
+# Use your default Chrome profile
+agentic-browser agent start --user-profile default
+
+# Use a specific profile directory
+agentic-browser agent start --user-profile /path/to/chrome/profile
+```
+
+The default profile path is resolved per platform:
+- **macOS:** `~/Library/Application Support/Google/Chrome`
+- **Linux:** `~/.config/google-chrome`
+- **Windows:** `%LOCALAPPDATA%\Google\Chrome\User Data`
+
+### Environment variables
+
+Both options can also be set via environment variables:
+
+```bash
+# Connect to existing Chrome
+export AGENTIC_BROWSER_CDP_URL=http://127.0.0.1:9222
+
+# Use default Chrome profile (set to "default", "true", or an absolute path)
+export AGENTIC_BROWSER_USER_PROFILE=default
+```
+
+CLI flags take precedence over environment variables.
+
 ## Agent Commands (Recommended for LLMs)
 
 The `agent` subcommand manages session state, auto-restarts on disconnect, generates command IDs, and retries failed commands automatically:
 
 ```bash
 agentic-browser agent start
+agentic-browser agent start --cdp-url http://127.0.0.1:9222
+agentic-browser agent start --user-profile default
 agentic-browser agent status
 agentic-browser agent run navigate '{"url":"https://example.com"}'
 agentic-browser agent run interact '{"action":"click","selector":"#login"}'
@@ -120,6 +180,8 @@ For direct control without session state management:
 
 ```bash
 agentic-browser session:start
+agentic-browser session:start --cdp-url http://127.0.0.1:9222
+agentic-browser session:start --user-profile default
 ```
 
 ### 2. Read Session Status
@@ -220,6 +282,31 @@ const memory = core.searchMemory({
 await core.stopSession(session.sessionId);
 ```
 
+### Connect to existing Chrome programmatically
+
+```ts
+import { createAgenticBrowserCore } from "agentic-browser";
+
+// Connect to a Chrome instance running with --remote-debugging-port=9222
+const core = createAgenticBrowserCore({
+  env: { ...process.env, AGENTIC_BROWSER_CDP_URL: "http://127.0.0.1:9222" },
+});
+const session = await core.startSession();
+// session is now controlling the existing Chrome — stopping won't kill it
+```
+
+### Use default Chrome profile programmatically
+
+```ts
+import { createAgenticBrowserCore } from "agentic-browser";
+
+const core = createAgenticBrowserCore({
+  env: { ...process.env, AGENTIC_BROWSER_USER_PROFILE: "default" },
+});
+const session = await core.startSession();
+// Chrome launched with your real profile (cookies, bookmarks, extensions)
+```
+
 ## Documentation
 
 ```bash

package/dist/cli/index.mjs

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-import { r as createCliRuntime } from "../runtime-4pX1c4Cs.mjs";
+import { r as createCliRuntime } from "../runtime-B_7vsUma.mjs";
 import fs from "node:fs";
 import path from "node:path";
 import crypto from "node:crypto";
@@ -243,7 +243,9 @@ async function main() {
 	const runtime = createCliRuntime();
 	const program = new Command();
 	program.name("agentic-browser").description("Agentic browser CLI");
-	program.command("session:start").action(async () => {
+	program.command("session:start").option("--cdp-url <url>", "connect to existing Chrome via CDP endpoint URL").option("--user-profile <path>", "use 'default' for system Chrome profile or an absolute path").action(async (options) => {
+		if (options.cdpUrl) runtime.context.config.cdpUrl = options.cdpUrl;
+		if (options.userProfile) runtime.context.config.userProfileDir = options.userProfile === "true" || options.userProfile === "default" ? "default" : options.userProfile;
 		const result = await runSessionStart(runtime, { browser: "chrome" });
 		console.log(JSON.stringify(result));
 	});
@@ -308,7 +310,9 @@ async function main() {
 		console.log(JSON.stringify(result));
 	});
 	const agent = program.command("agent").description("Stateful agent wrapper with session persistence and auto-retry");
-	agent.command("start").action(async () => {
+	agent.command("start").option("--cdp-url <url>", "connect to existing Chrome via CDP endpoint URL").option("--user-profile <path>", "use 'default' for system Chrome profile or an absolute path").action(async (options) => {
+		if (options.cdpUrl) runtime.context.config.cdpUrl = options.cdpUrl;
+		if (options.userProfile) runtime.context.config.userProfileDir = options.userProfile === "true" || options.userProfile === "default" ? "default" : options.userProfile;
 		const result = await agentStart(runtime);
 		console.log(JSON.stringify(result));
 	});

package/dist/index.mjs

@@ -1,4 +1,4 @@
 #!/usr/bin/env node
-import { i as createMockAgenticBrowserCore, n as createAgenticBrowserCore, t as AgenticBrowserCore } from "./runtime-4pX1c4Cs.mjs";
+import { i as createMockAgenticBrowserCore, n as createAgenticBrowserCore, t as AgenticBrowserCore } from "./runtime-B_7vsUma.mjs";
 
 export { AgenticBrowserCore, createAgenticBrowserCore, createMockAgenticBrowserCore };

package/dist/mcp/index.mjs

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-import { n as createAgenticBrowserCore } from "../runtime-4pX1c4Cs.mjs";
+import { n as createAgenticBrowserCore } from "../runtime-B_7vsUma.mjs";
 import { z } from "zod";
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";

package/dist/{runtime-4pX1c4Cs.mjs → runtime-B_7vsUma.mjs}

@@ -2,6 +2,7 @@
 import { spawn } from "node:child_process";
 import fs from "node:fs";
 import net from "node:net";
+import os from "node:os";
 import path from "node:path";
 import WebSocket, { WebSocketServer } from "ws";
 import { URL as URL$1, fileURLToPath } from "node:url";
@@ -157,6 +158,13 @@ async function getFreePort() {
 		});
 	});
 }
+function resolveDefaultProfileDir() {
+	const platform = os.platform();
+	const home = os.homedir();
+	if (platform === "darwin") return path.join(home, "Library", "Application Support", "Google", "Chrome");
+	if (platform === "win32") return path.join(process.env.LOCALAPPDATA ?? path.join(home, "AppData", "Local"), "Google", "Chrome", "User Data");
+	return path.join(home, ".config", "google-chrome");
+}
 var ChromeCdpBrowserController = class {
 	connections = /* @__PURE__ */ new Map();
 	constructor(baseDir, connectionFactory = CdpConnection.connect) {
@@ -191,6 +199,19 @@ var ChromeCdpBrowserController = class {
 	closeConnection(targetWsUrl) {
 		this.dropConnection(targetWsUrl);
 	}
+	async connect(cdpUrl) {
+		const parsed = new URL(cdpUrl);
+		const port = Number.parseInt(parsed.port, 10);
+		if (!port) throw new Error(`Invalid CDP URL: could not extract port from ${cdpUrl}`);
+		await waitForDebugger(port);
+		const targetWsUrl = await createTarget(cdpUrl);
+		await evaluateExpression(targetWsUrl, "window.location.href");
+		return {
+			pid: 0,
+			cdpUrl,
+			targetWsUrl
+		};
+	}
 	async ensureEnabled(targetWsUrl) {
 		const cached = this.connections.get(targetWsUrl);
 		if (!cached) return;
@@ -203,10 +224,13 @@ var ChromeCdpBrowserController = class {
 			cached.enabled.runtime = true;
 		}
 	}
-	async launch(sessionId, explicitPath) {
+	async launch(sessionId, explicitPath, userProfileDir) {
 		const executablePath = discoverChrome(explicitPath);
 		const extension = loadControlExtension();
-		const profileDir = path.join(this.baseDir, "profiles", sessionId);
+		let profileDir;
+		if (userProfileDir === "default") profileDir = resolveDefaultProfileDir();
+		else if (userProfileDir) profileDir = userProfileDir;
+		else profileDir = path.join(this.baseDir, "profiles", sessionId);
 		fs.mkdirSync(profileDir, { recursive: true });
 		const launchAttempts = [
 			{
@@ -640,6 +664,7 @@ var ChromeCdpBrowserController = class {
 		}
 	}
 	terminate(pid) {
+		if (pid === 0) return;
 		try {
 			process.kill(pid, "SIGTERM");
 		} catch {}
@@ -662,6 +687,19 @@ var MockBrowserController = class {
 			targetWsUrl
 		};
 	}
+	async connect(cdpUrl) {
+		this.pages.set(cdpUrl, {
+			url: "about:blank",
+			title: "about:blank",
+			text: "",
+			html: "<html><body></body></html>"
+		});
+		return {
+			pid: 0,
+			cdpUrl,
+			targetWsUrl: cdpUrl
+		};
+	}
 	async navigate(cdpUrl, url) {
 		const page = this.pages.get(cdpUrl);
 		if (!page) throw new Error("mock page missing");
@@ -785,7 +823,7 @@ var SessionManager = class {
 		if (active && active.session.status !== "terminated") throw new Error("A managed session is already active");
 		const sessionId = crypto.randomUUID();
 		const token = this.ctx.tokenService.issue(sessionId);
-		const launched = await this.browser.launch(sessionId, this.ctx.config.browserExecutablePath);
+		const launched = this.ctx.config.cdpUrl ? await this.browser.connect(this.ctx.config.cdpUrl) : await this.browser.launch(sessionId, this.ctx.config.browserExecutablePath, this.ctx.config.userProfileDir);
 		const session = {
 			sessionId,
 			status: "ready",
@@ -1136,12 +1174,18 @@ function loadConfig(env = process.env) {
 	const commandTimeoutMs = Number.parseInt(env.AGENTIC_BROWSER_COMMAND_TIMEOUT_MS ?? `${DEFAULT_TIMEOUT_MS}`, 10);
 	if (Number.isNaN(wsPort) || wsPort <= 0) throw new Error("AGENTIC_BROWSER_WS_PORT must be a positive integer");
 	if (Number.isNaN(commandTimeoutMs) || commandTimeoutMs <= 0) throw new Error("AGENTIC_BROWSER_COMMAND_TIMEOUT_MS must be a positive integer");
+	const userProfile = env.AGENTIC_BROWSER_USER_PROFILE;
+	let userProfileDir;
+	if (userProfile === "true" || userProfile === "default") userProfileDir = "default";
+	else if (userProfile && path.isAbsolute(userProfile)) userProfileDir = userProfile;
 	return {
 		host: env.AGENTIC_BROWSER_HOST ?? "127.0.0.1",
 		wsPort,
 		commandTimeoutMs,
 		logDir: env.AGENTIC_BROWSER_LOG_DIR ?? path.resolve(process.cwd(), ".agentic-browser"),
-		browserExecutablePath: env.AGENTIC_BROWSER_CHROME_PATH
+		browserExecutablePath: env.AGENTIC_BROWSER_CHROME_PATH,
+		cdpUrl: env.AGENTIC_BROWSER_CDP_URL,
+		userProfileDir
 	};
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agentic-browser",
-  "version": "1.0.3",
+  "version": "1.1.0",
   "license": "MIT",
   "repository": {
     "type": "git",