agentic-browser 1.1.0 → 1.2.0

package/README.md

@@ -37,13 +37,15 @@ npm run lint
 npm test
 ```
 
-## Connect to Existing Chrome / Use Your Profile
+## Use Your Existing Chrome
 
-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).
+By default, agentic-browser launches a fresh Chrome with a throwaway profile. If you want to use your logged-in sessions, cookies, or extensions, there are two ways:
 
-### Connect to a running Chrome
+### Option 1: Control your running Chrome (recommended)
 
-Start Chrome yourself with remote debugging enabled:
+This lets agentic-browser take over your already-open Chrome — no need to quit it, no need to log in again.
+
+**Step 1.** Quit Chrome, then relaunch it with remote debugging enabled:
 
 ```bash
 # macOS
@@ -56,44 +58,44 @@ google-chrome --remote-debugging-port=9222
 chrome.exe --remote-debugging-port=9222
 ```
 
-Then connect agentic-browser to it:
+Chrome opens normally with all your tabs, extensions, and sessions intact.
+
+**Step 2.** Connect agentic-browser:
 
 ```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.
+Stopping the session will **not** close your Chrome.
 
-### Launch Chrome with your real profile
+### Option 2: Launch a new Chrome with your profile
+
+**Important:** You must quit Chrome first. Chrome locks its profile directory — if Chrome is already running, this command will fail.
 
 ```bash
-# Use your default Chrome profile
+# Quit Chrome, then:
 agentic-browser agent start --user-profile default
+```
+
+This launches a new Chrome window using your default profile. You can also pass a custom profile path:
 
-# Use a specific profile directory
+```bash
 agentic-browser agent start --user-profile /path/to/chrome/profile
 ```
 
-The default profile path is resolved per platform:
+Default profile locations 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:
+These options can also be set via environment variables (CLI flags take precedence):
 
-```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.
+| Variable                       | Example                        | Description                     |
+| ------------------------------ | ------------------------------ | ------------------------------- |
+| `AGENTIC_BROWSER_CDP_URL`      | `http://127.0.0.1:9222`       | Connect to a running Chrome     |
+| `AGENTIC_BROWSER_USER_PROFILE` | `default` or an absolute path  | Launch with a real profile      |
 
 ## Agent Commands (Recommended for LLMs)
 
@@ -282,29 +284,25 @@ const memory = core.searchMemory({
 await core.stopSession(session.sessionId);
 ```
 
-### Connect to existing Chrome programmatically
+### Connect to your running Chrome
 
 ```ts
-import { createAgenticBrowserCore } from "agentic-browser";
-
-// Connect to a Chrome instance running with --remote-debugging-port=9222
+// Chrome must be 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
+// Stopping the session will NOT close your Chrome
 ```
 
-### Use default Chrome profile programmatically
+### Launch Chrome with your real profile
 
 ```ts
-import { createAgenticBrowserCore } from "agentic-browser";
-
+// Chrome must be closed first
 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

package/dist/cli/index.mjs

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-import { r as createCliRuntime } from "../runtime-B_7vsUma.mjs";
+import { r as createCliRuntime } from "../runtime-D6awVhGy.mjs";
 import fs from "node:fs";
 import path from "node:path";
 import crypto from "node:crypto";

package/dist/index.mjs

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

package/dist/mcp/index.mjs

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

package/dist/{runtime-B_7vsUma.mjs → runtime-D6awVhGy.mjs}

@@ -232,6 +232,8 @@ var ChromeCdpBrowserController = class {
 		else if (userProfileDir) profileDir = userProfileDir;
 		else profileDir = path.join(this.baseDir, "profiles", sessionId);
 		fs.mkdirSync(profileDir, { recursive: true });
+		const lockFile = path.join(profileDir, "SingletonLock");
+		if (fs.existsSync(lockFile)) throw new Error(`Chrome profile is already in use (lock file exists: ${lockFile}). Quit the running Chrome instance first, or use --cdp-url to connect to it instead.`);
 		const launchAttempts = [
 			{
 				withExtension: true,

package/package.json

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