@bastani/atomic 0.8.26-alpha.6 → 0.8.26-alpha.8

package/docs/workflows.md

@@ -154,7 +154,7 @@ For the builtin result tables below, `deep-research-codebase`, `goal`, and `ralp
 | `deep-research-codebase` | Scout + research-history chain → parallel specialist waves → aggregator. Indexes the whole repo and synthesizes findings. | Broad or cross-cutting research before you decide what to change. Prefer `/skill:research-codebase` for one subsystem. |
 | `goal` | Persisted goal ledger → bounded worker turns → receipts → three-reviewer gate → deterministic reducer → final report. | Small-to-medium scope changes when you can identify the work surface, state the exact outcome, and name the validation that proves it is done — for example tests, lint/typecheck, docs builds, or observable behavior. |
 | `ralph` | RFC planning → sub-agent orchestration → simplification → parallel review → optional final-stage PR handoff. | Larger migrations, broad refactors, multi-package changes, and spec-to-reviewed-change work where you want Atomic to plan the approach, delegate implementation through sub-agents, simplify, review, iterate, and optionally allow only the final `pull-request` stage to attempt PR creation with `create_pr=true`. |
-| `open-claude-design` | Design-system onboarding → reference import → HTML generation → impeccable-driven refinement → quality gate → rich HTML handoff. Renders a live `preview.html` you can iterate against (opens through `browser-use` when available). | UI, page, component, theme, or design-token work that benefits from generation + critique loops. |
+| `open-claude-design` | Design-system onboarding → reference import → HTML generation → impeccable-driven refinement → quality gate → rich HTML handoff. Renders a live `preview.html` you can iterate against (opens through `browser` when available). | UI, page, component, theme, or design-token work that benefits from generation + critique loops. |
 
 ### `deep-research-codebase`
 
@@ -1020,6 +1020,25 @@ Builder basics:
 
 Author workflows to create at least one tracked stage by calling `ctx.task()`, `ctx.chain()`, `ctx.parallel()`, `ctx.stage()`, or `ctx.workflow()` in the run body so each run has graph nodes to inspect, attach to, interrupt, resume, and render.
 
+### Guiding Principles
+
+- Stage prompts should be locally scoped: describe only the current stage's objective, inputs, expected outputs, and success criteria.
+- Avoid references to other stages unless the current stage explicitly receives and needs that information.
+- Avoid workflow-specific or stage-specific vocabulary that is not explained inside the current prompt.
+- Use clear software engineering terminology in self-described prompts.
+- Avoid hard-coded regular expressions for condition matching when gating reviews or model outputs.
+- Prefer structured output schemas for review/gate decisions whenever model output needs to be evaluated.
+- Treat atomic workflow units as language model stages, not deterministic tools.
+- When deterministic gates are needed, create small dedicated stages that instruct a model to run a specific tool or perform a specific check. This keeps gates adaptive to the current codebase while preserving explicit workflow structure.
+
+### Context engineering guidance
+
+Workflow guidance should also cover the context passed between stages:
+
+- Prefer creating files or artifacts for substantial handoffs, then instruct the next stage to read the file, instead of dumping large text output directly into the next stage prompt or context.
+- Prefer forked context for non-reviewer stages so long-running implementation work can preserve coherency and continuity.
+- Prefer a clean context window for reviewer stages so earlier implementation stages do not bias the reviewer. Reviewers should evaluate the supplied artifacts, changed files, tests, and explicit criteria as independently as possible.
+
 ### Inputs
 
 Inputs are declared with TypeBox `Type.*` schemas passed to `.input(key, schema)`. `Type` is re-exported from `@bastani/workflows` (along with the `Static` and `TSchema` type helpers), so you do not import from `typebox` directly in workflow files. Workflow packages still declare `typebox` as a peer dependency so the SDK's shipped types resolve under `tsc` — see [Programmatic Usage](#programmatic-usage). Common input schemas map to picker kinds and accepted runtime values:
@@ -1480,6 +1499,20 @@ registry.get("alpha");
 
 A workflow is an information-flow system, not just a list of prompts. Most workflow failures come from missing, stale, oversized, or poorly-routed context. Design every stage boundary deliberately.
 
+### Locally Scoped Stage Prompts
+
+Stage prompts should be local contracts, not miniature descriptions of the entire workflow runtime. Write prompts as if the stage could be executed independently from a fresh session with only the listed inputs. Include:
+
+- the stage's current objective and what is out of scope for this stage
+- the exact files, artifacts, child outputs, or user inputs it may use
+- the expected output format or structured-output tool/schema it must return
+- the checks, tools, or deterministic commands it should run when relevant
+- the success criteria that let this stage stop
+
+Avoid unrelated workflow internals such as reducer algorithms, future PR stages, sibling reviewer names, loop implementation details, or project-specific nicknames unless they are explicitly part of the current stage contract. If a term such as a gate name, ledger field, or workflow nickname is necessary, define it in the prompt before using it.
+
+Choose context mode deliberately. Use `context: "fork"` or `forkFromSessionFile` for coherent long-running implementation stages that need continuity from their own earlier work. Use `context: "fresh"` for unbiased reviewer, evaluator, and gate stages so they inspect the current files and explicit artifacts rather than inheriting the implementer's assumptions. When continuity is needed across fresh stages, pass it explicitly through files, declared outputs, and `reads`.
+
 ### Context Fundamentals
 
 Treat context as a finite attention budget. Include only information needed for the current decision, place critical constraints near the beginning or end of prompts, and use progressive disclosure instead of loading every possible reference up front.
@@ -1523,6 +1556,8 @@ A good compressed handoff includes:
 
 Use `output`, `outputMode: "file-only"`, `reads`, and `chainDir` for large research bundles, logs, or reviewer outputs. Keep summaries compact and let downstream stages read full artifacts only when needed. In the downstream stage prompt, explicitly say something like `Read the file at ${artifactPath} before continuing.` Do not inject full session tails, all previous stage outputs, or every prior review round into later prompts by default; pass the latest relevant artifact paths and make older history discoverable from a ledger or index file.
 
+Substantial handoffs should travel through files or durable artifacts instead of hidden transcript assumptions. This keeps stage prompts small, makes review/audit possible, and lets later stages reread the authoritative material without depending on what a previous model happened to summarize.
+
 ```ts
 const researchPath = ".atomic/workflows/runs/context-demo/research.md";
 await ctx.task("researcher", {
@@ -1586,6 +1621,10 @@ Build validation into the workflow instead of waiting for a final manual check.
 - reviewer stages: fresh-context reviewers that inspect artifacts and current files
 - LLM-as-judge stages: direct scoring, pairwise comparison, or rubric-based grading for subjective outputs
 
+Prefer structured output schemas or structured-output tools for model review and gate decisions. Do not make correctness depend on brittle regular-expression matching against free-form prose such as “looks good”, “approved”, or “PASS”. A schema with explicit booleans/enums, findings arrays, confidence, evidence fields, and error reporting is easier to validate, replay, and safely default to “not approved” when malformed.
+
+Use small dedicated model stages for adaptive gates when deterministic code alone cannot decide what to check. For example, a stage can read an artifact, inspect the repo, run a named tool or command, and then emit a structured decision. Keep that stage's prompt narrow: tell it the specific check to perform, the files/tools it may use, and the structured decision it must return.
+
 When using LLM judges, mitigate bias by defining score anchors, asking for evidence, calibrating against examples, and keeping length/order effects in mind. Track pass rates and failures over time for reusable workflows.
 
 ### Tools, MCP, Memory, and Hosted Execution
@@ -1618,12 +1657,13 @@ Before implementing or shipping a non-trivial workflow, answer these questions:
 - **Inputs:** Which values should be declared as inputs? What is the narrowest schema type? Which defaults are safe?
 - **Starter pattern:** Which [workflow starter pattern](#workflow-starter-patterns) best matches the task, and where does the actual design intentionally diverge?
 - **Stage decomposition:** For each stage, what question does it answer, what context does it need, what output should it return, and what model/tool/MCP requirements does it have?
+- **Local stage contract:** Can this stage prompt stand alone with its current objective, inputs/artifacts, expected outputs, tools/checks, and success criteria, without unexplained workflow internals or future-stage assumptions?
 - **Information flow:** For every edge between stages, is `previous` enough, or should the handoff use structured returns, files, `reads`, `output`, or `outputMode`?
 - **Output contract:** Which outputs should be declared with `.output(...)`, which stage/task/child results should `.run()` return for those keys, and what runtime type must each value have? If another workflow may call this workflow as a child, which non-default outputs should the parent rely on?
 - **Context size:** Can downstream stages succeed from the handoff alone? Should large transcripts, logs, or research bundles be summarized or saved as artifacts?
 - **Control flow:** Should the workflow use `ctx.chain`, `ctx.parallel`, `ctx.ui`, bounded loops, `failFast`, or `fallbackModels`?
 - **User experience:** Are stage names readable in status and graph views? Is the final output compact? Are important artifacts saved with stable paths?
-- **Validation:** What success criteria, review gates, deterministic checks, or evaluator stages prove the workflow did the right thing?
+- **Validation:** What success criteria, review gates, deterministic checks, or evaluator stages prove the workflow did the right thing? Are model gates schema-backed instead of regex/prose-matched, and do adaptive gates run as focused model stages with explicit tool/check instructions?
 
 Good workflows are information-flow systems, not just prompt sequences. Keep stage prompts focused, preserve evidence with file paths or artifacts, and pass only the context each downstream stage needs.
 
@@ -1639,4 +1679,6 @@ Good workflows are information-flow systems, not just prompt sequences. Keep sta
 - Do not expect named workflow runs to block the chat turn; they are background tasks.
 - Do not call `kill` when the user asks to interrupt or pause resumably.
 - Keep stage names readable because they appear in workflow status and UI.
+- Do not write stage prompts that depend on hidden workflow-wide awareness; make each model stage locally scoped and self-described.
+- Do not parse model gate decisions from ad-hoc prose with regular expressions; use structured output schemas/tools or a focused checking stage that returns a structured decision.
 - Return compact structured output and save large artifacts to files.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bastani/atomic",
-  "version": "0.8.26-alpha.6",
+  "version": "0.8.26-alpha.8",
   "description": "Atomic coding agent CLI with read, bash, edit, write tools and session management",
   "type": "module",
   "atomicConfig": {
@@ -63,16 +63,13 @@
     "copy-builtin-workflows": "bun run copy-builtin-packages",
     "docs:check": "bun run scripts/validate-docs-links.ts",
     "verify:workflow-types": "bun run scripts/verify-workflow-sdk-types.ts",
-    "verify:bundled-pi-tui": "bun run scripts/verify-bundled-pi-tui-install.ts",
     "test": "vitest --run",
-    "prepack": "bun run scripts/materialize-bundled-pi-tui.ts",
-    "postpack": "bun run scripts/materialize-bundled-pi-tui.ts --clean",
     "prepublishOnly": "bun run clean && bun run build"
   },
   "dependencies": {
-    "@earendil-works/pi-agent-core": "^0.78.0",
-    "@earendil-works/pi-ai": "^0.78.0",
-    "@earendil-works/pi-tui": "^0.78.0",
+    "@earendil-works/pi-agent-core": "^0.78.1",
+    "@earendil-works/pi-ai": "^0.78.1",
+    "@earendil-works/pi-tui": "^0.78.1",
     "@modelcontextprotocol/ext-apps": "^1.7.2",
     "@modelcontextprotocol/sdk": "^1.25.1",
     "@mozilla/readability": "^0.6.0",
@@ -97,11 +94,6 @@
     "yaml": "^2.9.0",
     "zod": "^3.25.0 || ^4.0.0"
   },
-  "bundleDependencies": [
-    "@earendil-works/pi-tui",
-    "get-east-asian-width",
-    "marked"
-  ],
   "overrides": {
     "rimraf": "6.1.2",
     "gaxios": {

package/dist/builtin/subagents/skills/browser-use/SKILL.md

@@ -1,234 +0,0 @@
----
-name: browser-use
-description: Automates browser interactions for web testing, form filling, screenshots, and data extraction. Use when the user needs to navigate websites, interact with web pages, fill forms, take screenshots, or extract information from web pages.
-allowed-tools: Bash(browser-use:*)
----
-
-# Browser Automation with browser-use CLI
-
-The `browser-use` command provides fast, persistent browser automation. A background daemon keeps the browser open across commands, giving ~50ms latency per call.
-
-## Prerequisites
-
-```bash
-browser-use doctor    # Verify installation
-```
-
-For setup details, see https://github.com/browser-use/browser-use/blob/main/browser_use/skill_cli/README.md
-
-## Core Workflow
-
-1. **Navigate**: `browser-use open <url>` — launches headless browser and opens page
-2. **Inspect**: `browser-use state` — returns clickable elements with indices
-3. **Interact**: use indices from state (`browser-use click 5`, `browser-use input 3 "text"`)
-4. **Verify**: `browser-use state` or `browser-use screenshot` to confirm
-5. **Repeat**: browser stays open between commands
-
-If a command fails, run `browser-use close` first to clear any broken session, then retry.
-
-To use the user's existing Chrome (preserves logins/cookies): run `browser-use connect` first.
-To use a cloud browser instead: run `browser-use cloud connect` first.
-After either, commands work the same way.
-
-### If `browser-use connect` fails
-
-When `browser-use connect` cannot find a running Chrome with remote debugging, prompt the user with two options:
-
-1. **Use their real Chrome browser** — they need to enable remote debugging first:
-   - Open `chrome://inspect/#remote-debugging` in Chrome, or relaunch Chrome with `--remote-debugging-port=9222`
-   - Then retry `browser-use connect`
-2. **Use managed Chromium with their Chrome profile** — no Chrome setup needed:
-   - Run `browser-use profile list` to show available profiles
-   - Ask which profile they want, then use `browser-use --profile "ProfileName" open <url>`
-   - This launches a separate Chromium instance with their profile data (cookies, logins, extensions)
-
-Let the user choose — don't assume one path over the other.
-
-## Browser Modes
-
-```bash
-browser-use open <url>                         # Default: headless Chromium (no setup needed)
-browser-use --headed open <url>                # Visible window (for debugging)
-browser-use connect                            # Connect to user's Chrome (preserves logins/cookies)
-browser-use cloud connect                      # Cloud browser (zero-config, requires API key)
-browser-use --profile "Default" open <url>     # Real Chrome with specific profile
-```
-
-After `connect` or `cloud connect`, all subsequent commands go to that browser — no extra flags needed.
-
-## Commands
-
-```bash
-# Navigation
-browser-use open <url>                    # Navigate to URL
-browser-use back                          # Go back in history
-browser-use scroll down                   # Scroll down (--amount N for pixels)
-browser-use scroll up                     # Scroll up
-browser-use tab list                      # List all tabs
-browser-use tab new [url]                 # Open a new tab (blank or with URL)
-browser-use tab switch <index>            # Switch to tab by index
-browser-use tab close <index> [index...]  # Close one or more tabs
-
-# Page State — always run state first to get element indices
-browser-use state                         # URL, title, clickable elements with indices
-browser-use screenshot [path.png]         # Screenshot (base64 if no path, --full for full page)
-
-# Interactions — use indices from state
-browser-use click <index>                 # Click element by index
-browser-use click <x> <y>                 # Click at pixel coordinates
-browser-use type "text"                   # Type into focused element
-browser-use input <index> "text"          # Click element, clear existing text, then type
-browser-use input <index> ""              # Clear a field without typing new text
-browser-use keys "Enter"                  # Send keyboard keys (also "Control+a", etc.)
-browser-use select <index> "option"       # Select dropdown option
-browser-use upload <index> <path>         # Upload file to file input
-browser-use hover <index>                 # Hover over element
-browser-use dblclick <index>              # Double-click element
-browser-use rightclick <index>            # Right-click element
-
-# Data Extraction
-browser-use eval "js code"                # Execute JavaScript, return result
-browser-use get title                     # Page title
-browser-use get html [--selector "h1"]    # Page HTML (or scoped to selector)
-browser-use get text <index>              # Element text content
-browser-use get value <index>             # Input/textarea value
-browser-use get attributes <index>        # Element attributes
-browser-use get bbox <index>              # Bounding box (x, y, width, height)
-
-# Wait
-browser-use wait selector "css"           # Wait for element (--state visible|hidden|attached|detached, --timeout ms)
-browser-use wait text "text"              # Wait for text to appear
-
-# Cookies
-browser-use cookies get [--url <url>]     # Get cookies (optionally filtered)
-browser-use cookies set <name> <value>    # Set cookie (--domain, --secure, --http-only, --same-site, --expires)
-browser-use cookies clear [--url <url>]   # Clear cookies
-browser-use cookies export <file>         # Export to JSON
-browser-use cookies import <file>         # Import from JSON
-
-# Session
-browser-use close                         # Close browser and stop daemon
-browser-use sessions                      # List active sessions
-browser-use close --all                   # Close all sessions
-```
-
-For advanced browser control (CDP, device emulation, tab activation), see `references/cdp-python.md`.
-
-## Cloud API
-
-```bash
-browser-use cloud connect                 # Provision cloud browser and connect (zero-config)
-browser-use cloud login <api-key>         # Save API key (or set BROWSER_USE_API_KEY)
-browser-use cloud logout                  # Remove API key
-browser-use cloud v2 GET /browsers        # REST passthrough (v2 or v3)
-browser-use cloud v2 POST /tasks '{"task":"...","url":"..."}'
-browser-use cloud v2 poll <task-id>       # Poll task until done
-browser-use cloud v2 --help               # Show API endpoints
-```
-
-`cloud connect` provisions a cloud browser with a persistent profile (auto-created on first use), connects via CDP, and prints a live URL. `browser-use close` disconnects AND stops the cloud browser. For custom browser settings (proxy, timeout, specific profile), use `cloud v2 POST /browsers` directly with the desired parameters.
-
-### Agent Self-Registration
-
-Only use this if you don't already have an API key (check `browser-use doctor` to see if api_key is set). If already logged in, skip this entirely.
-
-1. `browser-use cloud signup` — get a challenge
-2. Solve the challenge
-3. `browser-use cloud signup --verify <challenge-id> <answer>` — verify and save API key
-4. `browser-use cloud signup --claim` — generate URL for a human to claim the account
-
-## Tunnels
-
-```bash
-browser-use tunnel <port>                 # Start Cloudflare tunnel (idempotent)
-browser-use tunnel list                   # Show active tunnels
-browser-use tunnel stop <port>            # Stop tunnel
-browser-use tunnel stop --all             # Stop all tunnels
-```
-
-## Profile Management
-
-```bash
-browser-use profile list                  # List detected browsers and profiles
-browser-use profile sync --all            # Sync profiles to cloud
-browser-use profile update                # Download/update profile-use binary
-```
-
-## Command Chaining
-
-Commands can be chained with `&&`. The browser persists via the daemon, so chaining is safe and efficient.
-
-```bash
-browser-use open https://example.com && browser-use state
-browser-use input 5 "user@example.com" && browser-use input 6 "password" && browser-use click 7
-```
-
-Chain when you don't need intermediate output. Run separately when you need to parse `state` to discover indices first.
-
-## Common Workflows
-
-### Authenticated Browsing
-
-When a task requires an authenticated site (Gmail, GitHub, internal tools), use Chrome profiles:
-
-```bash
-browser-use profile list                           # Check available profiles
-# Ask the user which profile to use, then:
-browser-use --profile "Default" open https://github.com  # Already logged in
-```
-
-### Exposing Local Dev Servers
-
-```bash
-browser-use tunnel 3000                            # → https://abc.trycloudflare.com
-browser-use open https://abc.trycloudflare.com     # Browse the tunnel
-```
-
-## Multiple Browsers
-
-For subagent workflows or running multiple browsers in parallel, use `--session NAME`. Each session gets its own browser. See `references/multi-session.md`.
-
-## Configuration
-
-```bash
-browser-use config list                            # Show all config values
-browser-use config set cloud_connect_proxy jp      # Set a value
-browser-use config get cloud_connect_proxy         # Get a value
-browser-use config unset cloud_connect_timeout     # Remove a value
-browser-use doctor                                 # Shows config + diagnostics
-browser-use setup                                  # Interactive post-install setup
-```
-
-Config stored in `~/.browser-use/config.json`.
-
-## Global Options
-
-| Option | Description |
-|--------|-------------|
-| `--headed` | Show browser window |
-| `--profile [NAME]` | Use real Chrome (bare `--profile` uses "Default") |
-| `--cdp-url <url>` | Connect via CDP URL (`http://` or `ws://`) |
-| `--session NAME` | Target a named session (default: "default") |
-| `--json` | Output as JSON |
-| `--mcp` | Run as MCP server via stdin/stdout |
-
-## Tips
-
-1. **Always run `state` first** to see available elements and their indices
-2. **Use `--headed` for debugging** to see what the browser is doing
-3. **Sessions persist** — browser stays open between commands
-4. **CLI aliases**: `bu`, `browser`, and `browseruse` all work
-5. **If commands fail**, run `browser-use close` first, then retry
-
-## Troubleshooting
-
-- **Browser won't start?** `browser-use close` then `browser-use --headed open <url>`
-- **Element not found?** `browser-use scroll down` then `browser-use state`
-- **Run diagnostics:** `browser-use doctor`
-
-## Cleanup
-
-```bash
-browser-use close                         # Close browser session
-browser-use tunnel stop --all             # Stop tunnels (if any)
-```

package/dist/builtin/subagents/skills/browser-use/references/cdp-python.md

@@ -1,76 +0,0 @@
-# Raw CDP & Python Session Reference
-
-The CLI commands handle most browser interactions. Use `browser-use python` with raw CDP when you need browser-level control the CLI doesn't expose — activating a tab so the user sees it, intercepting network requests, emulating devices, or working with Chrome target IDs directly.
-
-## How the Python session works
-
-`browser-use python "statement"` executes one Python statement per call. Variables persist across calls — set a value in one call, use it in the next.
-
-A `browser` object is pre-injected with sync wrappers for common operations (`browser.goto()`, `browser.click()`, etc.). For anything beyond those, two internals give you full access:
-
-- `browser._run(coroutine)` — run any async coroutine synchronously (60s timeout)
-- `browser._session` — the raw `BrowserSession` with full CDP client access
-
-## Getting a CDP client
-
-```bash
-browser-use python "cdp = browser._run(browser._session.get_or_create_cdp_session())"
-```
-
-After this, `cdp` persists across calls. Use `cdp.cdp_client.send.<Domain>.<method>()` for any CDP command and `cdp.session_id` for the session parameter.
-
-## Recipes
-
-### Activate a tab (make it visible to the user)
-
-The CLI's `tab switch` only changes the agent's internal focus — Chrome's visible tab doesn't change. To actually show the user a specific tab:
-
-```bash
-# Get all targets to find the target ID
-browser-use python "targets = browser._session.session_manager.get_all_page_targets()"
-browser-use python "print([(i, t.url) for i, t in enumerate(targets)])"
-
-# Activate target at index 1 so the user sees it
-browser-use python "cdp = browser._run(browser._session.get_or_create_cdp_session(target_id=None, focus=False))"
-browser-use python "browser._run(cdp.cdp_client.send.Target.activateTarget(params={'targetId': targets[1].target_id}))"
-```
-
-### List all tabs with target IDs
-
-```bash
-browser-use python "targets = browser._session.session_manager.get_all_page_targets()"
-browser-use python "
-for i, t in enumerate(targets):
-    print(f'{i}: {t.target_id[:12]}... {t.url}')
-"
-```
-
-### Run JavaScript and get the result
-
-```bash
-browser-use python "cdp = browser._run(browser._session.get_or_create_cdp_session())"
-browser-use python "result = browser._run(cdp.cdp_client.send.Runtime.evaluate(params={'expression': 'document.title', 'returnByValue': True}, session_id=cdp.session_id))"
-browser-use python "print(result['result']['value'])"
-```
-
-### Emulate a mobile device
-
-```bash
-browser-use python "cdp = browser._run(browser._session.get_or_create_cdp_session())"
-browser-use python "browser._run(cdp.cdp_client.send.Emulation.setDeviceMetricsOverride(params={'width': 375, 'height': 812, 'deviceScaleFactor': 3, 'mobile': True}, session_id=cdp.session_id))"
-```
-
-### Get cookies via CDP
-
-```bash
-browser-use python "cdp = browser._run(browser._session.get_or_create_cdp_session())"
-browser-use python "cookies = browser._run(cdp.cdp_client.send.Network.getCookies(params={}, session_id=cdp.session_id))"
-browser-use python "print(cookies)"
-```
-
-## Tips
-
-- Each `browser-use python` call is one statement. Multi-line strings work for `for` loops and `if` blocks, but you can't mix statements and expressions. Use multiple calls.
-- Variables persist: set `cdp = ...` in one call, use `cdp` in the next.
-- The `browser._run()` bridge has a 60-second timeout. For long operations, increase it or use the async internals directly.
-- All CDP domains are available via `cdp.cdp_client.send.<Domain>.<method>()`. See the [Chrome DevTools Protocol docs](https://chromedevtools.github.io/devtools-protocol/) for the full API.

package/dist/builtin/subagents/skills/browser-use/references/multi-session.md

@@ -1,92 +0,0 @@
-# Multiple Browser Sessions
-
-## Why use multiple sessions
-
-When you need more than one browser at a time:
-- Cloud browser for scraping + local Chrome for authenticated tasks
-- Two different Chrome profiles simultaneously
-- Isolated browser for testing that won't affect the user's browsing
-- Running a headed browser for debugging while headless runs in background
-
-## How sessions are isolated
-
-Each `--session NAME` gets:
-- Its own daemon process
-- Its own Unix socket (`~/.browser-use/{name}.sock`)
-- Its own PID file and state file
-- Its own browser instance (completely independent)
-- Its own tab ownership state (multi-agent locks don't cross sessions)
-
-## The `--session` flag
-
-Must be passed on every command targeting that session:
-
-```bash
-browser-use --session work open <url>      # goes to 'work' daemon
-browser-use --session work state           # reads from 'work' daemon
-browser-use state                          # goes to 'default' daemon (different browser)
-```
-
-If you forget `--session`, the command goes to the `default` session. This is the most common mistake — you'll interact with the wrong browser.
-
-## Combining sessions with browser modes
-
-```bash
-# Session 1: cloud browser
-browser-use --session cloud cloud connect
-
-# Session 2: connect to user's Chrome
-browser-use --session chrome connect
-
-# Session 3: headed Chromium for debugging
-browser-use --session debug --headed open <url>
-```
-
-Each session is fully independent. The cloud session talks to a remote browser, the chrome session talks to the user's Chrome, and the debug session manages its own Chromium — all running simultaneously.
-
-## Listing and managing sessions
-
-```bash
-browser-use sessions
-```
-
-Output:
-```
-SESSION          PHASE          PID      CONFIG
-cloud            running        12345    cloud
-chrome           running        12346    cdp
-debug            ready          12347    headed
-```
-
-PHASE shows the daemon lifecycle state: `initializing`, `ready`, `starting`, `running`, `shutting_down`, `stopped`, `failed`.
-
-```bash
-browser-use --session cloud close           # close one session
-browser-use close --all                     # close every session
-```
-
-## Common patterns
-
-**Cloud + local authenticated:**
-```bash
-browser-use --session scraper cloud connect
-browser-use --session scraper open https://example.com
-# ... scrape data ...
-
-browser-use --session auth --profile "Default" open https://github.com
-browser-use --session auth state
-# ... interact with authenticated site ...
-```
-
-**Throwaway test browser:**
-```bash
-browser-use --session test --headed open https://localhost:3000
-# ... test, debug, inspect ...
-browser-use --session test close    # done, clean up
-```
-
-**Environment variable:**
-```bash
-export BROWSER_USE_SESSION=work
-browser-use open <url>              # uses 'work' session without --session flag
-```