@bastani/atomic 0.8.26-alpha.5 → 0.8.26-alpha.7

package/CHANGELOG.md

@@ -2,6 +2,30 @@
 
 ## [Unreleased]
 
+## [0.8.26-alpha.7] - 2026-06-07
+
+### Added
+
+- Added `/context-compact`, a fixed no-argument deletion-only compaction command that validates model-proposed logical deletion targets, preserves retained transcript content verbatim, and records `context_compaction` session entries.
+
+### Changed
+
+- Bumped the `@earendil-works/pi-agent-core`, `@earendil-works/pi-ai`, and `@earendil-works/pi-tui` dependencies to 0.78.1.
+
+### Fixed
+
+- Fixed auto-compaction so queued in-progress work resumes without requiring a manual follow-up prompt ([#1280](https://github.com/bastani-inc/atomic/issues/1280)).
+
+### Removed
+
+- Removed the temporary manual `@earendil-works/pi-tui` patch, patched-dependency configuration, and bundled patched TUI packaging fallback.
+
+## [0.8.26-alpha.6] - 2026-06-06
+
+### Changed
+
+- Bumped package version for the Atomic 0.8.26-alpha.6 prerelease.
+
 ## [0.8.26-alpha.5] - 2026-06-06
 
 ### Changed

package/README.md

@@ -180,6 +180,7 @@ Type `/` in the editor to trigger commands. [Extensions](#extensions) can regist
 | `/fork` | Create a new session from a previous user message |
 | `/clone` | Duplicate the current active branch into a new session |
 | `/compact [prompt]` | Manually compact context, optional custom instructions |
+| `/context-compact` | Delete safe older transcript objects verbatim; no arguments |
 | `/copy` | Copy last assistant message to clipboard |
 | `/export [file]` | Export session to HTML file |
 | `/share` | Upload as private GitHub gist with shareable HTML link |
@@ -258,13 +259,15 @@ Use `/session` in interactive mode to see the current session ID before reusing
 
 ### Compaction
 
-Long sessions can exhaust context windows. Compaction summarizes older messages while keeping recent ones.
+Long sessions can exhaust context windows. Summary compaction summarizes older messages while keeping recent ones.
 
-**Manual:** `/compact` or `/compact <custom instructions>`
+**Manual summary:** `/compact` or `/compact <custom instructions>`
 
-**Automatic:** Enabled by default. Triggers on context overflow (recovers and retries) or when approaching the limit (proactive). Configure via `/settings` or `settings.json`.
+**Manual verbatim deletion:** `/context-compact` asks the selected model for deletion targets using a fixed internal prompt, validates the plan locally, and applies logical deletions only. It has no prompt arguments; `/context-compact anything` is invalid/ignored rather than treated as instructions.
 
-Compaction is lossy. The full history remains in the JSONL file; use `/tree` to revisit. Customize compaction behavior via [extensions](#extensions). See [docs/compaction.md](docs/compaction.md) for internals.
+**Automatic:** Enabled by default. Triggers on context overflow (recovers and retries) or when approaching the limit (proactive). Configure via `/settings` or `settings.json`. Automatic compaction remains summary-based.
+
+Summary compaction is lossy. `/context-compact` preserves retained transcript content verbatim, but the full history still remains in the JSONL file; use `/tree` to revisit. Customize summary compaction behavior via [extensions](#extensions). See [docs/compaction.md](docs/compaction.md) for internals.
 
 ---
 

package/dist/builtin/intercom/CHANGELOG.md

@@ -4,6 +4,18 @@ All notable changes to the `pi-intercom` extension will be documented in this fi
 
 ## [Unreleased]
 
+## [0.8.26-alpha.7] - 2026-06-07
+
+### Changed
+
+- Bumped package version for the Atomic 0.8.26-alpha.7 prerelease.
+
+## [0.8.26-alpha.6] - 2026-06-06
+
+### Changed
+
+- Bumped package version for the Atomic 0.8.26-alpha.6 prerelease.
+
 ## [0.8.26-alpha.5] - 2026-06-06
 
 ### Changed

package/dist/builtin/intercom/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bastani/intercom",
-  "version": "0.8.26-alpha.5",
+  "version": "0.8.26-alpha.7",
   "private": true,
   "description": "Atomic extension providing a private coordination channel between parent and child agent sessions. Fork of: https://github.com/nicobailon/pi-intercom",
   "contributors": [
@@ -39,7 +39,7 @@
   },
   "peerDependencies": {
     "@bastani/atomic": "*",
-    "@earendil-works/pi-tui": "*"
+    "@earendil-works/pi-tui": "^0.78.1"
   },
   "peerDependenciesMeta": {
     "@bastani/atomic": {

package/dist/builtin/mcp/CHANGELOG.md

@@ -7,6 +7,18 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.8.26-alpha.7] - 2026-06-07
+
+### Changed
+
+- Bumped package version for the Atomic 0.8.26-alpha.7 prerelease.
+
+## [0.8.26-alpha.6] - 2026-06-06
+
+### Changed
+
+- Bumped package version for the Atomic 0.8.26-alpha.6 prerelease.
+
 ## [0.8.26-alpha.5] - 2026-06-06
 
 ### Changed

package/dist/builtin/mcp/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bastani/mcp",
-  "version": "0.8.26-alpha.5",
+  "version": "0.8.26-alpha.7",
   "private": true,
   "description": "Atomic extension that adapts MCP (Model Context Protocol) servers into the coding agent. Fork of: https://github.com/nicobailon/pi-mcp-adapter",
   "contributors": [
@@ -32,8 +32,8 @@
   },
   "peerDependencies": {
     "@bastani/atomic": "*",
-    "@earendil-works/pi-ai": "*",
-    "@earendil-works/pi-tui": "*",
+    "@earendil-works/pi-ai": "^0.78.1",
+    "@earendil-works/pi-tui": "^0.78.1",
     "zod": "^3.25.0 || ^4.0.0"
   },
   "peerDependenciesMeta": {

package/dist/builtin/subagents/CHANGELOG.md

@@ -2,6 +2,18 @@
 
 ## [Unreleased]
 
+## [0.8.26-alpha.7] - 2026-06-07
+
+### Added
+
+- Replaced the bundled browser-use subagent integration with the first-party `browser` skill for web interaction workflows.
+
+## [0.8.26-alpha.6] - 2026-06-06
+
+### Changed
+
+- Bumped package version for the Atomic 0.8.26-alpha.6 prerelease.
+
 ## [0.8.26-alpha.5] - 2026-06-06
 
 ### Changed

package/dist/builtin/subagents/agents/codebase-online-researcher.md

@@ -4,7 +4,7 @@ description: Online research for up-to-date documentation and library-source kno
 tools: read, grep, find, ls, bash, write, web_search, fetch_content, get_search_content
 model: openai/gpt-5.5:low
 fallbackModels: openai-codex/gpt-5.5:low, github-copilot/gpt-5.5:low, anthropic/claude-opus-4-8:low, github-copilot/claude-opus-4.7:low
-skills: browser-use
+skills: browser
 ---
 
 You are an expert research specialist focused on finding accurate, relevant information from authoritative sources — including open-source library internals with GitHub permalinks. You have three web tools available from the `pi-web-access` extension:
@@ -13,11 +13,11 @@ You are an expert research specialist focused on finding accurate, relevant info
 - `fetch_content` — fetch a specific URL and return clean reader-mode text/markdown (HTML pages, GitHub issues/PRs, Stack Overflow, npm, arXiv, Reddit, Wikipedia, JSON endpoints, PDFs, RSS/Atom, YouTube). `fetch_content` on a GitHub repo URL also clones the repo locally under `/tmp/pi-github-repos/<owner>/<repo>` and returns the file tree. Prefer this over a raw HTTP fetch.
 - `get_search_content` — fetch the underlying content for the most promising results of a previous `web_search` in one call.
 
-For JS-heavy or auth-gated pages, fall back to invoking `browser-use` through `bash` (the `browser-use` skill is available).
+For JS-heavy or auth-gated pages, load the `browser` skill and invoke its `browse` CLI through `bash`.
 
 <EXTREMELY_IMPORTANT>
 - PREFER `fetch_content` for static pages; it's faster and cheaper than spinning up a real browser.
-- Reach for the `browser-use` skill via `bash` ONLY when a real DOM/JS is required.
+- Reach for the `browser` skill's `browse` CLI via `bash` ONLY when a real DOM/JS is required.
 - ALWAYS check `research/web/` for a recent cached copy before fetching anything new.
 - EVERY code-related claim about an open-source library needs a GitHub **permalink with a full commit SHA** — branch links break when code changes.
 </EXTREMELY_IMPORTANT>
@@ -39,7 +39,7 @@ When fetching any external page, apply these techniques in order. They produce p
 1. **`fetch_content <url>` first.** Returns clean reader-mode text/markdown for nearly every well-formed page (and handles PDFs and JSON). Try it before anything else.
 2. **Check `/llms.txt`.** Many modern docs sites publish an AI-friendly index at `/llms.txt` (spec: [llmstxt.org](https://llmstxt.org/llms.txt)). `fetch_content https://<site>/llms.txt` often links directly to the most relevant pages in plain text, saving a round-trip through the full site.
 3. **Request Markdown via `Accept: text/markdown`.** Sites behind Cloudflare with [Markdown for Agents](https://developers.cloudflare.com/fundamentals/reference/markdown-for-agents/) return pre-converted Markdown when you set the header. Use `bash` with `curl <url> -H "Accept: text/markdown"` (look for `content-type: text/markdown` and the `x-markdown-tokens` header).
-4. **Fall back to a real browser.** Drive `browser-use` through `bash` and load the `browser-use` skill to render and interact with JS-heavy or auth-gated pages.
+4. **Fall back to a real browser.** Load the `browser` skill and drive its `browse` CLI through `bash` to render and interact with JS-heavy or auth-gated pages.
 
 ## Persisting Findings — Store useful documents in `research/web/`
 
@@ -49,7 +49,7 @@ When you fetch a document that is worth keeping for future sessions (reference d
 ---
 source_url: <original URL>
 fetched_at: <YYYY-MM-DD>
-fetch_method: read | llms.txt | markdown-accept-header | browser | browser-use
+fetch_method: read | llms.txt | markdown-accept-header | browser | browse
 topic: <short description>
 ---
 ```
@@ -166,12 +166,12 @@ When you receive a research query:
 2. **Check the local cache first**. Look in `research/web/` for existing documents on the topic. If a recent (still-relevant) copy exists, cite it before re-fetching.
 3. **Execute strategic searches**.
     - Identify the authoritative source (e.g. the library's official docs site, its GitHub repo, its release notes).
-    - Apply the Web Fetch Strategy: `fetch_content <url>` → `/llms.txt` → `Accept: text/markdown` → `browser-use` fallback.
+    - Apply the Web Fetch Strategy: `fetch_content <url>` → `/llms.txt` → `Accept: text/markdown` → `browser` fallback.
     - Use multiple query variations to capture different perspectives via `web_search`.
     - Use `get_search_content` to bulk-fetch the underlying content of the top results of a `web_search` in one shot.
     - For source repositories, prefer raw GitHub URLs (`https://raw.githubusercontent.com/<owner>/<repo>/<ref>/<path>`) over the HTML UI. For library internals, clone via `fetch_content` and use `grep`/`read` + permalinks.
 4. **Fetch and analyze content**.
-    - Use `fetch_content <url>` (or `browser-use` via `bash` when interactivity is required) to pull the full content of promising sources.
+    - Use `fetch_content <url>` (or the browser skill's `browse` CLI via `bash` when interactivity is required) to pull the full content of promising sources.
     - Prioritize official documentation, reputable technical blogs, and authoritative sources.
     - Extract specific quotes and sections relevant to the query.
     - Note publication dates to ensure currency of information.
@@ -290,7 +290,7 @@ For library-source answers, every code claim should look like the citation examp
 ## Search Efficiency
 
 - Check `research/web/` for an existing copy before fetching anything new.
-- Start by fetching the authoritative source (`fetch_content <url>` → `/llms.txt` → `Accept: text/markdown` → `browser-use`) rather than search-engine-style exploration.
+- Start by fetching the authoritative source (`fetch_content <url>` → `/llms.txt` → `Accept: text/markdown` → `browser`) rather than search-engine-style exploration.
 - Use `fetch_content` (or `get_search_content` after a `web_search`) to pull full content from the most promising 3-5 web pages.
 - Reuse already-cloned repos under `/tmp/pi-github-repos/` instead of re-cloning.
 - If initial results are insufficient, refine search terms and try again.
@@ -313,4 +313,4 @@ For library-source answers, every code claim should look like the citation examp
 | Page returns 403 / bot block   | Gemini fallback triggers automatically; no action needed if Gemini is configured.                              |
 | `web_search` fails             | Check provider config; try explicit `provider: "gemini"` if a Perplexity key is missing.                       |
 
-Remember: you are the user's expert guide to technical research. Lean on `fetch_content` first with the `/llms.txt` → `Accept: text/markdown` → `browser-use` fallback chain to efficiently pull authoritative content, clone open-source repos when implementation evidence is needed, store anything reusable under `research/web/`, and deliver comprehensive, up-to-date answers with exact citations and GitHub permalinks. Answer directly — skip preamble like "I'll help you with…" and go straight to findings.
+Remember: you are the user's expert guide to technical research. Lean on `fetch_content` first with the `/llms.txt` → `Accept: text/markdown` → `browser` fallback chain to efficiently pull authoritative content, clone open-source repos when implementation evidence is needed, store anything reusable under `research/web/`, and deliver comprehensive, up-to-date answers with exact citations and GitHub permalinks. Answer directly — skip preamble like "I'll help you with…" and go straight to findings.

package/dist/builtin/subagents/agents/debugger.md

@@ -4,7 +4,7 @@ description: Debug errors, test failures, and unexpected behavior. Use PROACTIVE
 tools: read, edit, write, grep, find, ls, bash, web_search, fetch_content, get_search_content
 model: openai/gpt-5.5:xhigh
 fallbackModels: openai-codex/gpt-5.5:xhigh, github-copilot/gpt-5.5:xhigh, anthropic/claude-opus-4-8:xhigh, github-copilot/claude-opus-4.7:xhigh
-skills: tdd, browser-use, tmux
+skills: tdd, browser, tmux
 ---
 
 You are tasked with debugging and identifying errors, test failures, and unexpected behavior in the codebase. Your goal is to identify root causes, generate a report detailing the issues and proposed fixes, and fix the problem from that report.
@@ -13,13 +13,13 @@ You are tasked with debugging and identifying errors, test failures, and unexpec
 
 - `tdd` — load the TDD skill before creating or modifying any tests.
 - `tmux` load the tmux skill for debugging terminal environment or TUI apps.
-- `browser-use` — load the browser-use skill for debugging web apps. Assume the `browser-use` CLI is installed; if it fails, fall back to `bunx browser-use` or `npx browser-use`.
+- `browser` — load the browser skill for debugging web apps. Assume the `browse` CLI is installed; if it fails, follow the skill setup (`which browse || npm install -g browse`) or use `npx browse`.
 - `fetch_content <url>` — the `pi-web-access` fetch tool returns reader-mode text/markdown for URLs (HTML, JSON, PDFs, GitHub issues/PRs, npm, arXiv, RSS, Reddit, Stack Overflow, etc.). Prefer it over a real browser when you only need page content.
 - `web_search` / `get_search_content` — issue web queries and bulk-fetch the top results for triage.
-- `browser-use` (via `bash`) — full Chromium when you need JS execution, auth, or interactive actions. Prefer the CLI's observe verbs over screenshots for understanding page state.
+- `browse` (via `bash` after loading the `browser` skill) — full Chromium when you need JS execution, auth, or interactive actions. Prefer snapshots/structured state over screenshots for understanding page state.
 
 <EXTREMELY_IMPORTANT>
-- PREFER `fetch_content <url>` for static content. Only reach for the `browser-use` skill when you need JS execution, authentication, or interactive page actions.
+- PREFER `fetch_content <url>` for static content. Only reach for the `browser` skill's `browse` CLI when you need JS execution, authentication, or interactive page actions.
 - ALWAYS `tdd` BEFORE creating or modifying any tests.
 - NEVER suppress a failing test to make it pass. Reproduce the failure first; only then fix the underlying defect.
 </EXTREMELY_IMPORTANT>
@@ -45,7 +45,7 @@ When you need to consult docs, forums, or issue trackers, apply these techniques
 1. **`fetch_content <url>` first.** The `pi-web-access` fetch tool returns clean reader-mode text/markdown for HTML, GitHub issues/PRs, Stack Overflow, npm, arXiv, RSS, Wikipedia, Reddit, JSON endpoints, and PDFs — no browser needed.
 2. **Check `/llms.txt`.** Many modern docs sites publish an AI-friendly index at `/llms.txt` (spec: [llmstxt.org](https://llmstxt.org/llms.txt)). Try `fetch_content https://<site>/llms.txt` before anything else; it often links directly to the most relevant pages in plain text.
 3. **`Accept: text/markdown` header.** Some sites behind Cloudflare serve pre-converted Markdown via the header. If `fetch_content` returns thin or noisy content, try `bash` with `curl <url> -H "Accept: text/markdown"`.
-4. **Fall back to the browser-use skill** — only when JS execution, login, or interactive actions are required.
+4. **Fall back to the browser skill** — only when JS execution, login, or interactive actions are required.
 
 **Persist useful findings to `research/web/`:** When you fetch a document worth keeping for future sessions (error-message writeups, API schemas, troubleshooting guides, release notes), save it to `research/web/<YYYY-MM-DD>-<kebab-case-topic>.md` with a short header noting the source URL and fetch date. Future debugging sessions can then reuse the lookup without re-fetching.
 
@@ -79,7 +79,7 @@ Debugging process:
 - Form and test hypotheses
 - Add strategic debug logging or drive the project's own debugger (`bun --inspect`, `node --inspect-brk`, `python -m pdb`, etc.) through `bash` instead of `print` spam
 - Inspect variable state by capturing it through the project's debugger session in `bash` or by writing a short repro script
-- Use the web research order above (`fetch_content <url>` → `/llms.txt` → `Accept: text/markdown` → browser-use) to look up external library docs, error messages, Stack Overflow threads, and GitHub issues
+- Use the web research order above (`fetch_content <url>` → `/llms.txt` → `Accept: text/markdown` → browser) to look up external library docs, error messages, Stack Overflow threads, and GitHub issues
 
 For each issue, provide:
 

package/dist/builtin/subagents/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bastani/subagents",
-  "version": "0.8.26-alpha.5",
+  "version": "0.8.26-alpha.7",
   "private": true,
   "description": "Atomic extension for delegating tasks to subagents with chains, parallel execution, and TUI clarification. Fork of: https://github.com/nicobailon/pi-subagents",
   "contributors": [
@@ -38,9 +38,9 @@
   },
   "peerDependencies": {
     "@bastani/atomic": "*",
-    "@earendil-works/pi-agent-core": "*",
-    "@earendil-works/pi-ai": "*",
-    "@earendil-works/pi-tui": "*"
+    "@earendil-works/pi-agent-core": "^0.78.1",
+    "@earendil-works/pi-ai": "^0.78.1",
+    "@earendil-works/pi-tui": "^0.78.1"
   },
   "peerDependenciesMeta": {
     "@bastani/atomic": {

package/dist/builtin/subagents/prompts/parallel-handoff-plan.md

@@ -38,7 +38,7 @@ External researcher (`codebase-online-researcher`):
 
 - Study linked projects, docs, issues, examples, source code, or prompt guidance.
 - Identify the behavior, API, implementation files, constraints, and transferable ideas.
-- Use `fetch_content` first, then `/llms.txt`, then `Accept: text/markdown`, and only fall back to `browser-use` when JS execution or auth is required.
+- Use `fetch_content` first, then `/llms.txt`, then `Accept: text/markdown`, and only fall back to `browser` when JS execution or auth is required.
 - Persist any high-value fetch to `research/web/<YYYY-MM-DD>-<topic>.md`.
 - Return source links, repo paths, key evidence, risks, and what matters for this implementation.
 

package/dist/builtin/subagents/skills/browser/EXAMPLES.md

@@ -0,0 +1,151 @@
+# Browser Automation Examples
+
+Common browser automation workflows using the `browse` CLI. Each example demonstrates a distinct pattern using real commands.
+
+For localhost and other local dev flows, start with `browse open <url> --local` for a clean isolated browser. Use `browse open <url> --auto-connect` only when the agent should attach to an existing debuggable Chrome session for cookies or login state.
+
+## Example 1: Extract Data from a Page
+
+**User request**: "Get the product details from example.com/product/123"
+
+```bash
+browse open https://example.com/product/123
+browse snapshot                          # read page structure + element refs
+browse get text "body"                   # extract all visible text content
+browse stop
+```
+
+Parse the text output to extract structured data (name, price, description, etc.).
+
+For a specific section, use a CSS selector:
+
+```bash
+browse get text ".product-details"       # text from a specific container
+```
+
+**Note**: `browse get text` requires a CSS selector — use `"body"` for all page text.
+
+## Example 2: Fill and Submit a Form
+
+**User request**: "Fill out the contact form on example.com with my information"
+
+```bash
+browse open https://example.com/contact
+browse snapshot                          # find form fields and their refs
+browse click @0-3                        # click the Name input (ref from snapshot)
+browse type "John Doe"
+browse press Tab                         # move to next field
+browse type "john@example.com"
+browse fill "#message" "I would like to inquire about your services"
+browse snapshot                          # verify fields are filled
+browse click @0-8                        # click Submit button (ref from snapshot)
+browse snapshot                          # confirm submission result
+browse stop
+```
+
+**Key pattern**: Use `browse snapshot` before interacting to discover element refs, then `browse click <ref>` and `browse type` to interact.
+
+## Example 3: Multi-Step Navigation
+
+**User request**: "Get headlines from the first 3 pages of results on example.com/news"
+
+```bash
+browse open https://example.com/news
+browse snapshot                          # read page 1 content
+browse get text ".headline"              # extract headlines
+
+browse snapshot                          # find "Next" button ref
+browse click @0-12                       # click Next (ref from snapshot)
+browse wait load                         # wait for page 2 to load
+browse get text ".headline"              # extract page 2 headlines
+
+browse snapshot                          # find Next again (ref may change)
+browse click @0-15                       # click Next
+browse wait load
+browse get text ".headline"              # extract page 3 headlines
+
+browse stop
+```
+
+**Key pattern**: Re-run `browse snapshot` after each navigation because element refs change when the page updates.
+
+## Example 4: Escalate to Remote Mode
+
+**User request**: "Scrape pricing from competitor.com" (a site with Cloudflare protection)
+
+```bash
+# Attempt 1: local mode
+browse open https://competitor.com/pricing --local
+browse snapshot
+# Output shows: "Checking your browser..." (Cloudflare interstitial)
+# or: page content is empty / access denied
+browse stop
+```
+
+The agent detects bot protection and tells the user:
+
+> This site has Cloudflare bot detection. Browserbase remote mode can use Browserbase Identity with a Verified browser and residential proxies. Want me to set it up?
+
+If the user agrees:
+
+```bash
+# Set Browserbase credentials
+export BROWSERBASE_API_KEY="bb_live_..."
+
+# Retry in remote mode
+browse open https://competitor.com/pricing --remote
+browse snapshot                          # full page content now accessible
+browse get text ".pricing-table"
+browse stop
+```
+
+## Example 5: Persist Login with Context ID
+
+**User request**: "Log into my dashboard and save the session so I don't have to log in again next time"
+
+This uses Browserbase contexts to persist cookies and storage across sessions. Requires remote mode.
+
+```bash
+# Session 1: Log in and persist state
+SESSION_JSON="$(browse cloud sessions create --context-id ctx_abc123 --persist --keep-alive)"
+SESSION_ID="$(echo "$SESSION_JSON" | jq -r .id)"
+CONNECT_URL="$(echo "$SESSION_JSON" | jq -r .connectUrl)"
+
+browse open https://app.example.com/login --cdp "$CONNECT_URL"
+browse snapshot                          # find login form fields
+browse click @0-3                        # click email input
+browse type "user@example.com"
+browse press Tab
+browse type "my-password"
+browse click @0-7                        # click Sign In button
+browse wait load
+browse snapshot                          # confirm logged-in dashboard
+browse stop
+browse cloud sessions update "$SESSION_ID" --status REQUEST_RELEASE  # state is saved back to ctx_abc123
+```
+
+In a later session, reuse the same context — already authenticated:
+
+```bash
+# Session 2: Resume with saved state (already logged in)
+SESSION_JSON="$(browse cloud sessions create --context-id ctx_abc123 --keep-alive)"
+SESSION_ID="$(echo "$SESSION_JSON" | jq -r .id)"
+CONNECT_URL="$(echo "$SESSION_JSON" | jq -r .connectUrl)"
+
+browse open https://app.example.com/dashboard --cdp "$CONNECT_URL"
+browse snapshot                          # dashboard loads — no login needed
+browse get text ".welcome-message"
+browse stop
+browse cloud sessions update "$SESSION_ID" --status REQUEST_RELEASE
+```
+
+**Key pattern**: Use `browse cloud sessions create --context-id <id> --persist` for the first Browserbase session to save auth state, then attach with `browse open ... --cdp "$CONNECT_URL"`. On subsequent sessions, create with the same `--context-id` and omit `--persist` if you don't want changes saved back.
+
+## Tips
+
+- **Snapshot first**: Always run `browse snapshot` before interacting — it gives you the accessibility tree with element refs
+- **Use refs to click**: `browse click @0-5` is more reliable than trying to describe elements
+- **Re-snapshot after actions**: Element refs change when the page updates
+- **`get text` for data extraction**: Use `browse get text [selector]` to pull text content from specific elements
+- **`stop` when done**: Always `browse stop` to clean up the browser session
+- **Prefer snapshot over screenshot**: Snapshot is fast and structured; screenshot is slow and uses vision tokens. Only screenshot when you need visual context (layout, images, debugging)

package/dist/builtin/subagents/skills/browser/LICENSE.txt

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Browserbase, Inc.
+
+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.