fix(cli): fix hdiutil mount detection, update README with install/launch/init flow

Replaces GoReleaser (Pro-only monorepo feature) with plain go build.
Tested: RC release created successfully on branch with all 6 binaries.

.github/workflows/release-agent-extension.yml

@@ -0,0 +1,148 @@
+name: Release Agent Extension
+
+on:
+  workflow_dispatch:
+
+concurrency:
+  group: release-agent-extension
+  cancel-in-progress: false
+
+jobs:
+  release:
+    if: github.ref == 'refs/heads/main'
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+      pull-requests: write
+    defaults:
+      run:
+        working-directory: packages/browseros-agent/apps/agent
+
+    steps:
+      - uses: actions/checkout@v6
+        with:
+          fetch-depth: 0
+
+      - uses: oven-sh/setup-bun@v2
+
+      - name: Install dependencies
+        run: bun ci
+        working-directory: packages/browseros-agent
+
+      - name: Build and zip extension
+        run: bun run codegen && bun run zip
+        env:
+          VITE_PUBLIC_BROWSEROS_API: https://api.browseros.com
+
+      - name: Get version and zip path
+        id: version
+        run: |
+          echo "version=$(node -p "require('./package.json').version")" >> "$GITHUB_OUTPUT"
+          echo "release_sha=$(git rev-parse HEAD)" >> "$GITHUB_OUTPUT"
+          ZIP_FILE=$(ls "$(pwd)/dist/"*-chrome.zip | head -n 1)
+          echo "zip_path=$ZIP_FILE" >> "$GITHUB_OUTPUT"
+          echo "zip_name=$(basename "$ZIP_FILE")" >> "$GITHUB_OUTPUT"
+
+      - name: Generate release notes
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: |
+          AGENT_PATH="packages/browseros-agent/apps/agent"
+          CURRENT_TAG="agent-extension-v${{ steps.version.outputs.version }}"
+          PREV_TAG=$(git tag -l "agent-extension-v*" --sort=-v:refname | grep -v "^${CURRENT_TAG}$" | head -n 1)
+
+          if [ -z "$PREV_TAG" ]; then
+            echo "Initial release" > /tmp/release-notes.md
+          else
+            COMMITS=$(git log "$PREV_TAG"..HEAD --pretty=format:"%H" -- "$AGENT_PATH")
+
+            if [ -z "$COMMITS" ]; then
+              echo "No notable changes." > /tmp/release-notes.md
+            else
+              echo "## What's Changed" > /tmp/release-notes.md
+              echo "" >> /tmp/release-notes.md
+
+              while IFS= read -r SHA; do
+                SUBJECT=$(git log -1 --pretty=format:"%s" "$SHA")
+                PR_NUM=$(gh api "/repos/${{ github.repository }}/commits/${SHA}/pulls" --jq '.[0].number // empty' 2>/dev/null)
+
+                # Skip PR number if already in the commit subject (squash merges include it)
+                if [ -n "$PR_NUM" ] && ! echo "$SUBJECT" | grep -qF "(#${PR_NUM})"; then
+                  echo "- ${SUBJECT} (#${PR_NUM})" >> /tmp/release-notes.md
+                else
+                  echo "- ${SUBJECT}" >> /tmp/release-notes.md
+                fi
+              done <<< "$COMMITS"
+            fi
+          fi
+        working-directory: ${{ github.workspace }}
+
+      - name: Create GitHub release
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: |
+          TAG="agent-extension-v${{ steps.version.outputs.version }}"
+          RELEASE_SHA="${{ steps.version.outputs.release_sha }}"
+          TITLE="BrowserOS Agent Extension v${{ steps.version.outputs.version }}"
+
+          if git rev-parse "$TAG" >/dev/null 2>&1; then
+            echo "Tag $TAG already exists, skipping tag creation"
+          else
+            git tag "$TAG" "$RELEASE_SHA"
+          fi
+
+          if git ls-remote --tags origin "$TAG" | grep -q "$TAG"; then
+            echo "Tag $TAG already on remote, skipping push"
+          else
+            git push origin "$TAG"
+          fi
+
+          if gh release view "$TAG" >/dev/null 2>&1; then
+            echo "Release $TAG already exists, updating"
+            gh release edit "$TAG" --title "$TITLE" --notes-file /tmp/release-notes.md
+            gh release upload "$TAG" "${{ steps.version.outputs.zip_path }}" --clobber
+          else
+            gh release create "$TAG" \
+              --title "$TITLE" \
+              --notes-file /tmp/release-notes.md \
+              "${{ steps.version.outputs.zip_path }}"
+          fi
+        working-directory: ${{ github.workspace }}
+
+      - name: Update CHANGELOG.md via PR
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: |
+          VERSION="${{ steps.version.outputs.version }}"
+          DATE=$(date -u +"%Y-%m-%d")
+          BRANCH="docs/agent-extension-changelog-v${VERSION}"
+          CHANGELOG="packages/browseros-agent/apps/agent/CHANGELOG.md"
+
+          git checkout main
+
+          {
+            head -n 1 "$CHANGELOG"
+            echo ""
+            echo "## v${VERSION} (${DATE})"
+            echo ""
+            cat /tmp/release-notes.md
+            echo ""
+            tail -n +2 "$CHANGELOG"
+          } > /tmp/new-changelog.md
+          mv /tmp/new-changelog.md "$CHANGELOG"
+
+          git config user.name "github-actions[bot]"
+          git config user.email "github-actions[bot]@users.noreply.github.com"
+          git checkout -b "$BRANCH"
+          git add "$CHANGELOG"
+          git commit -m "docs: update agent extension changelog for v${VERSION}"
+          git push origin "$BRANCH"
+
+          gh pr create \
+            --title "docs: update agent extension changelog for v${VERSION}" \
+            --body "Auto-generated changelog update for BrowserOS Agent Extension v${VERSION}." \
+            --base main \
+            --head "$BRANCH"
+
+          gh pr merge "$BRANCH" --squash --auto || true
+        working-directory: ${{ github.workspace }}

.github/workflows/release-agent-sdk.yml

@@ -79,27 +79,14 @@ jobs:
                 # Find associated PR number
                 PR_NUM=$(gh api "/repos/${{ github.repository }}/commits/${SHA}/pulls" --jq '.[0].number // empty' 2>/dev/null)
 
-                # Format line
-                if [ -n "$PR_NUM" ]; then
-                  echo "- ${SUBJECT} (#${PR_NUM}) @${GITHUB_USER:-$AUTHOR}" >> /tmp/release-notes.md
+                # Format line: skip PR number if already in the commit subject
+                # (squash merges include "(#123)" in the subject automatically)
+                if [ -n "$PR_NUM" ] && ! echo "$SUBJECT" | grep -qF "(#${PR_NUM})"; then
+                  echo "- ${SUBJECT} (#${PR_NUM})" >> /tmp/release-notes.md
                 else
-                  echo "- ${SUBJECT} (${SHA:0:7}) @${GITHUB_USER:-$AUTHOR}" >> /tmp/release-notes.md
-                fi
-
-                # Collect unique contributors (exact word match to avoid substring collisions)
-                HANDLE="${GITHUB_USER:-$AUTHOR}"
-                if ! echo "$CONTRIBUTORS" | grep -qw "$HANDLE"; then
-                  CONTRIBUTORS="${CONTRIBUTORS} ${HANDLE}"
+                  echo "- ${SUBJECT}" >> /tmp/release-notes.md
                 fi
               done <<< "$COMMITS"
-
-              # Add contributors section
-              echo "" >> /tmp/release-notes.md
-              echo "## Contributors" >> /tmp/release-notes.md
-              echo "" >> /tmp/release-notes.md
-              for CONTRIB in $CONTRIBUTORS; do
-                echo "- @${CONTRIB}" >> /tmp/release-notes.md
-              done
             fi
           fi
         working-directory: ${{ github.workspace }}

.github/workflows/release-cli.yml

@@ -1,16 +1,24 @@
 name: Release CLI
 
 on:
-  push:
-    tags:
-      - "cli/v*"
+  workflow_dispatch:
+    inputs:
+      version:
+        description: "Release version (e.g. 0.1.0)"
+        required: true
+        type: string
 
-permissions:
-  contents: write
+concurrency:
+  group: release-cli
+  cancel-in-progress: false
 
 jobs:
   release:
+    if: github.ref == 'refs/heads/main'
     runs-on: ubuntu-latest
+    permissions:
+      contents: write
+      pull-requests: write
     defaults:
       run:
         working-directory: packages/browseros-agent/apps/cli
@@ -30,10 +38,106 @@ jobs:
       - name: Run vet
         run: go vet ./...
 
-      - uses: goreleaser/goreleaser-action@v6
-        with:
-          version: "~> v2"
-          args: release --clean
-          workdir: packages/browseros-agent/apps/cli
+      - name: Build all platforms
+        run: |
+          VERSION="${{ inputs.version }}"
+          LDFLAGS="-s -w -X main.version=${VERSION}"
+          DIST="dist"
+          mkdir -p "$DIST"
+
+          for pair in darwin/amd64 darwin/arm64 linux/amd64 linux/arm64 windows/amd64 windows/arm64; do
+            OS="${pair%/*}"
+            ARCH="${pair#*/}"
+            BIN="browseros-cli"
+            EXT=""
+            if [ "$OS" = "windows" ]; then EXT=".exe"; fi
+
+            echo "Building ${OS}/${ARCH}..."
+            GOOS=$OS GOARCH=$ARCH CGO_ENABLED=0 go build -trimpath -ldflags "$LDFLAGS" -o "${DIST}/${BIN}${EXT}" .
+
+            ARCHIVE="browseros-cli_${VERSION}_${OS}_${ARCH}"
+            if [ "$OS" = "windows" ]; then
+              (cd "$DIST" && zip "${ARCHIVE}.zip" "${BIN}${EXT}")
+            else
+              (cd "$DIST" && tar czf "${ARCHIVE}.tar.gz" "${BIN}")
+            fi
+            rm "${DIST}/${BIN}${EXT}"
+          done
+
+          (cd "$DIST" && sha256sum *.tar.gz *.zip > checksums.txt)
+          echo "=== Built artifacts ==="
+          ls -lh "$DIST"
+
+      - name: Generate release notes
         env:
-          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: |
+          CLI_PATH="packages/browseros-agent/apps/cli"
+          TAG="browseros-cli-v${{ inputs.version }}"
+          CHANGELOG_FILE="/tmp/release-changelog.md"
+          PREV_TAG=$(git tag -l "browseros-cli-v*" --sort=-v:refname | grep -v "^${TAG}$" | head -n 1)
+
+          if [ -z "$PREV_TAG" ]; then
+            echo "Initial release of browseros-cli." > "$CHANGELOG_FILE"
+          else
+            COMMITS=$(git log "$PREV_TAG"..HEAD --pretty=format:"%H" -- "$CLI_PATH")
+
+            if [ -z "$COMMITS" ]; then
+              echo "No notable changes." > "$CHANGELOG_FILE"
+            else
+              echo "## What's Changed" > "$CHANGELOG_FILE"
+              echo "" >> "$CHANGELOG_FILE"
+
+              while IFS= read -r SHA; do
+                SUBJECT=$(git log -1 --pretty=format:"%s" "$SHA")
+                PR_NUM=$(gh api "/repos/${{ github.repository }}/commits/${SHA}/pulls" --jq '.[0].number // empty' 2>/dev/null)
+
+                if [ -n "$PR_NUM" ] && ! echo "$SUBJECT" | grep -qF "(#${PR_NUM})"; then
+                  echo "- ${SUBJECT} (#${PR_NUM})" >> "$CHANGELOG_FILE"
+                else
+                  echo "- ${SUBJECT}" >> "$CHANGELOG_FILE"
+                fi
+              done <<< "$COMMITS"
+            fi
+          fi
+
+          cat "$CHANGELOG_FILE" > /tmp/release-notes.md
+          cat >> /tmp/release-notes.md <<'EOF'
+
+          ## Install `browseros-cli`
+
+          ### macOS / Linux
+
+          ```bash
+          curl -fsSL https://cdn.browseros.com/cli/install.sh | bash
+          ```
+
+          ### Windows
+
+          ```powershell
+          irm https://cdn.browseros.com/cli/install.ps1 | iex
+          ```
+
+          After install, run `browseros-cli init` to point the CLI at your BrowserOS MCP server.
+          EOF
+        working-directory: ${{ github.workspace }}
+
+      - name: Create tag and release
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: |
+          TAG="browseros-cli-v${{ inputs.version }}"
+          git config user.name "github-actions[bot]"
+          git config user.email "github-actions[bot]@users.noreply.github.com"
+
+          if ! git rev-parse "$TAG" >/dev/null 2>&1; then
+            git tag -a "$TAG" -m "browseros-cli v${{ inputs.version }}"
+            git push origin "$TAG"
+          fi
+
+          CLI_DIST="packages/browseros-agent/apps/cli/dist"
+          gh release create "$TAG" \
+            --title "browseros-cli v${{ inputs.version }}" \
+            --notes-file /tmp/release-notes.md \
+            ${CLI_DIST}/*
+        working-directory: ${{ github.workspace }}

README.md

@@ -6,6 +6,7 @@
 [![Slack](https://img.shields.io/badge/Slack-Join%20us-4A154B?logo=slack&logoColor=white)](https://dub.sh/browserOS-slack)
 [![Twitter](https://img.shields.io/twitter/follow/browserOS_ai?style=social)](https://twitter.com/browseros_ai)
 [![License: AGPL v3](https://img.shields.io/badge/License-AGPL%20v3-blue.svg)](LICENSE)
+[![Docs](https://img.shields.io/badge/Docs-docs.browseros.com-blue)](https://docs.browseros.com)
 <br></br>
 <a href="https://files.browseros.com/download/BrowserOS.dmg">
   <img src="https://img.shields.io/badge/Download-macOS-black?style=flat&logo=apple&logoColor=white" alt="Download for macOS (beta)" />
@@ -22,146 +23,183 @@
 <br />
 </div>
 
-##
-🌐 BrowserOS is an open-source Chromium fork that runs AI agents natively. **The privacy-first alternative to ChatGPT Atlas, Perplexity Comet, and Dia.**
+BrowserOS is an open-source Chromium fork that runs AI agents natively. **The privacy-first alternative to ChatGPT Atlas, Perplexity Comet, and Dia.**
 
-🔒 Use your own API keys or run local models with Ollama. Your data never leaves your machine.
+Use your own API keys or run local models with Ollama. Your data never leaves your machine.
 
-💡 Join our [Discord](https://discord.gg/YKwjt5vuKr) or [Slack](https://dub.sh/browserOS-slack) and help us build! Have feature requests? [Suggest here](https://github.com/browseros-ai/BrowserOS/issues/99).
+> **[Documentation](https://docs.browseros.com)** · **[Discord](https://discord.gg/YKwjt5vuKr)** · **[Slack](https://dub.sh/browserOS-slack)** · **[Twitter](https://x.com/browserOS_ai)** · **[Feature Requests](https://github.com/browseros-ai/BrowserOS/issues/99)**
 
-## Quick start
+## Quick Start
 
-1. Download and install BrowserOS:
-   - [macOS](https://files.browseros.com/download/BrowserOS.dmg)
-   - [Windows](https://files.browseros.com/download/BrowserOS_installer.exe)
-   - [Linux (AppImage)](https://files.browseros.com/download/BrowserOS.AppImage)
-   - [Linux (Debian)](https://cdn.browseros.com/download/BrowserOS.deb)
+1. **Download and install** BrowserOS — [macOS](https://files.browseros.com/download/BrowserOS.dmg) · [Windows](https://files.browseros.com/download/BrowserOS_installer.exe) · [Linux (AppImage)](https://files.browseros.com/download/BrowserOS.AppImage) · [Linux (Debian)](https://cdn.browseros.com/download/BrowserOS.deb)
+2. **Import your Chrome data** (optional) — bookmarks, passwords, extensions all carry over
+3. **Connect your AI provider** — Claude, OpenAI, Gemini, ChatGPT Pro via OAuth, or local models via Ollama/LM Studio
 
-2. Import your Chrome data (optional)
+## Features
 
-3. Connect your AI provider — use Claude, OpenAI, Gemini, or local models via Ollama and LMStudio.
-
-4. Start automating!
-
-## What makes BrowserOS special
-- 🏠 Feels like home — same Chrome interface, all your extensions just work
-- 🤖 AI agents that run on YOUR browser, not in the cloud
-- 🔒 Privacy first — bring your own keys or run local models with Ollama. Your browsing history stays on your machine
-- 🤝 [BrowserOS as MCP server](https://docs.browseros.com/features/use-with-claude-code) — control the browser from `claude-code`, `gemini-cli`, or any MCP client (31 tools)
-- 🔄 [Workflows](https://docs.browseros.com/features/workflows) — build repeatable browser automations with a visual graph builder
-- 📂 [Cowork](https://docs.browseros.com/features/cowork) — combine browser automation with local file operations. Research the web, save reports to your folder
-- ⏰ [Scheduled Tasks](https://docs.browseros.com/features/scheduled-tasks) — run the agent on autopilot, daily or every few minutes
-- 💬 [LLM Hub](https://docs.browseros.com/features/llm-chat-hub) — compare Claude, ChatGPT, and Gemini side-by-side on any page
-- 🛡️ Built-in ad blocker — [10x more protection than Chrome](https://docs.browseros.com/features/ad-blocking) with uBlock Origin + Manifest V2 support
-- 🚀 100% open source under AGPL-3.0
+| Feature | Description | Docs |
+|---------|-------------|------|
+| **AI Agent** | 53+ browser automation tools — navigate, click, type, extract data, all with natural language | [Guide](https://docs.browseros.com/getting-started) |
+| **MCP Server** | Control the browser from Claude Code, Gemini CLI, or any MCP client | [Setup](https://docs.browseros.com/features/use-with-claude-code) |
+| **Workflows** | Build repeatable browser automations with a visual graph builder | [Docs](https://docs.browseros.com/features/workflows) |
+| **Cowork** | Combine browser automation with local file operations — research the web, save reports to your folder | [Docs](https://docs.browseros.com/features/cowork) |
+| **Scheduled Tasks** | Run agents on autopilot — daily, hourly, or every few minutes | [Docs](https://docs.browseros.com/features/scheduled-tasks) |
+| **Memory** | Persistent memory across conversations — your assistant remembers context over time | [Docs](https://docs.browseros.com/features/memory) |
+| **SOUL.md** | Define your AI's personality and instructions in a single markdown file | [Docs](https://docs.browseros.com/features/soul-md) |
+| **LLM Hub** | Compare Claude, ChatGPT, and Gemini responses side-by-side on any page | [Docs](https://docs.browseros.com/features/llm-chat-hub) |
+| **40+ App Integrations** | Gmail, Slack, GitHub, Linear, Notion, Figma, Salesforce, and more via MCP | [Docs](https://docs.browseros.com/features/connect-apps) |
+| **Vertical Tabs** | Side-panel tab management — stay organized even with 100+ tabs open | [Docs](https://docs.browseros.com/features/vertical-tabs) |
+| **Ad Blocking** | uBlock Origin + Manifest V2 support — [10x more protection](https://docs.browseros.com/features/ad-blocking) than Chrome | [Docs](https://docs.browseros.com/features/ad-blocking) |
+| **Cloud Sync** | Sync browser config and agent history across devices | [Docs](https://docs.browseros.com/features/sync) |
+| **Skills** | Custom instruction sets that shape how your AI assistant behaves | [Docs](https://docs.browseros.com/features/skills) |
+| **Smart Nudges** | Contextual suggestions to connect apps and use features at the right moment | [Docs](https://docs.browseros.com/features/smart-nudges) |
 
 ## Demos
 
-### 🤖 BrowserOS agent in action
+### BrowserOS agent in action
 [![BrowserOS agent in action](docs/videos/browserOS-agent-in-action.gif)](https://www.youtube.com/watch?v=SoSFev5R5dI)
 <br/><br/>
 
-### 🎇 Install [BrowserOS as MCP](https://docs.browseros.com/features/use-with-claude-code) and control it from `claude-code`
+### Install [BrowserOS as MCP](https://docs.browseros.com/features/use-with-claude-code) and control it from `claude-code`
 
 https://github.com/user-attachments/assets/c725d6df-1a0d-40eb-a125-ea009bf664dc
 
 <br/><br/>
 
-### 💬 Use BrowserOS to chat
+### Use BrowserOS to chat
 
 https://github.com/user-attachments/assets/726803c5-8e36-420e-8694-c63a2607beca
 
 <br/><br/>
 
-### ⚡ Use BrowserOS to scrape data
+### Use BrowserOS to scrape data
 
 https://github.com/user-attachments/assets/9f038216-bc24-4555-abf1-af2adcb7ebc0
 
 <br/><br/>
 
-## Why We're Building BrowserOS
+## Install `browseros-cli`
 
-For the first time since Netscape pioneered the web in 1994, AI gives us the chance to completely reimagine the browser. We've seen tools like Cursor deliver 10x productivity gains for developers—yet everyday browsing remains frustratingly archaic.
+Use `browseros-cli` to launch and control BrowserOS from the terminal or from AI coding agents like Claude Code.
 
-You're likely juggling 70+ tabs, battling your browser instead of having it assist you. Routine tasks, like ordering something from amazon or filling a form should be handled seamlessly by AI agents.
+**macOS / Linux:**
 
-At BrowserOS, we're convinced that AI should empower you by automating tasks locally and securely—keeping your data private. We are building the best browser for this future!
+```bash
+curl -fsSL https://cdn.browseros.com/cli/install.sh | bash
+```
 
-## How we compare
+**Windows:**
 
-<details>
-<summary><b>vs Chrome</b></summary>
-<br>
-While we're grateful for Google open-sourcing Chromium, but Chrome hasn't evolved much in 10 years. No AI features, no automation, no MCP support.
-</details>
+```powershell
+irm https://cdn.browseros.com/cli/install.ps1 | iex
+```
 
-<details>
-<summary><b>vs Brave</b></summary>
-<br>
-We love what Brave started, but they've spread themselves too thin with crypto, search, VPNs. We're laser-focused on AI-powered browsing.
-</details>
+After install, run `browseros-cli init` to connect the CLI to your running BrowserOS instance.
 
-<details>
-<summary><b>vs Arc/Dia</b></summary>
-<br>
-Many loved Arc, but it was closed source. When they abandoned users, there was no recourse. We're 100% open source - fork it anytime!
-</details>
+## LLM Providers
 
-<details>
-<summary><b>vs Perplexity Comet</b></summary>
-<br>
-They're a search/ad company. Your browser history becomes their product. We keep everything local.
-</details>
+BrowserOS works with any LLM. Bring your own keys, use OAuth, or run models locally.
 
-<details>
-<summary><b>vs ChatGPT Atlas</b></summary>
-<br>
-Your browsing data could be used for ads or to train their models. We keep your history and agent interactions strictly local.
-</details>
+| Provider | Type | Auth |
+|----------|------|------|
+| Kimi K2.5 | Cloud (default) | Built-in |
+| ChatGPT Pro/Plus | Cloud | [OAuth](https://docs.browseros.com/features/chatgpt) |
+| GitHub Copilot | Cloud | [OAuth](https://docs.browseros.com/features/github-copilot) |
+| Qwen Code | Cloud | [OAuth](https://docs.browseros.com/features/qwen-code) |
+| Claude (Anthropic) | Cloud | API key |
+| GPT-4o / o3 (OpenAI) | Cloud | API key |
+| Gemini (Google) | Cloud | API key |
+| Azure OpenAI | Cloud | API key |
+| AWS Bedrock | Cloud | IAM credentials |
+| OpenRouter | Cloud | API key |
+| Ollama | Local | [Setup](https://docs.browseros.com/features/ollama) |
+| LM Studio | Local | [Setup](https://docs.browseros.com/features/lm-studio) |
+
+## How We Compare
+
+| | BrowserOS | Chrome | Brave | Dia | Comet | Atlas |
+|---|:---:|:---:|:---:|:---:|:---:|:---:|
+| Open Source | ✅ | ❌ | ✅ | ❌ | ❌ | ❌ |
+| AI Agent | ✅ | ❌ | ❌ | ❌ | ✅ | ✅ |
+| MCP Server | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ |
+| Visual Workflows | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ |
+| Cowork (files + browser) | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ |
+| Scheduled Tasks | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ |
+| Bring Your Own Keys | ✅ | ❌ | ✅ | ❌ | ❌ | ❌ |
+| Local Models (Ollama) | ✅ | ❌ | ✅ | ❌ | ❌ | ❌ |
+| Local-first Privacy | ✅ | ❌ | ✅ | ❌ | ❌ | ❌ |
+| Ad Blocking (MV2) | ✅ | ❌ | ✅ | ❌ | ✅ | ❌ |
+
+**Detailed comparisons:**
+- [BrowserOS vs Chrome DevTools MCP](https://docs.browseros.com/comparisons/chrome-devtools-mcp) — developer-focused comparison for browser automation
+- [BrowserOS vs Claude Cowork](https://docs.browseros.com/comparisons/claude-cowork) — getting real work done with AI
+- [BrowserOS vs OpenClaw](https://docs.browseros.com/comparisons/openclaw) — everyday AI assistance
+
+## Architecture
+
+BrowserOS is a monorepo with two main subsystems: the **browser** (Chromium fork) and the **agent platform** (TypeScript/Go).
+
+```
+BrowserOS/
+├── packages/browseros/              # Chromium fork + build system (Python)
+│   ├── chromium_patches/            # Patches applied to Chromium source
+│   ├── build/                       # Build CLI and modules
+│   └── resources/                   # Icons, entitlements, signing
+│
+├── packages/browseros-agent/        # Agent platform (TypeScript/Go)
+│   ├── apps/
+│   │   ├── server/                  # MCP server + AI agent loop (Bun)
+│   │   ├── agent/                   # Browser extension UI (WXT + React)
+│   │   ├── cli/                     # CLI tool (Go)
+│   │   ├── eval/                    # Benchmark framework
+│   │   └── controller-ext/          # Chrome API bridge extension
+│   │
+│   └── packages/
+│       ├── agent-sdk/               # Node.js SDK (npm: @browseros-ai/agent-sdk)
+│       ├── cdp-protocol/            # CDP type bindings
+│       └── shared/                  # Shared constants
+```
+
+| Package | What it does |
+|---------|-------------|
+| [`packages/browseros`](packages/browseros/) | Chromium fork — patches, build system, signing |
+| [`apps/server`](packages/browseros-agent/apps/server/) | Bun server exposing 53+ MCP tools and running the AI agent loop |
+| [`apps/agent`](packages/browseros-agent/apps/agent/) | Browser extension — new tab, side panel chat, onboarding, settings |
+| [`apps/cli`](packages/browseros-agent/apps/cli/) | Go CLI — control BrowserOS from the terminal or AI coding agents |
+| [`apps/eval`](packages/browseros-agent/apps/eval/) | Benchmark framework — WebVoyager, Mind2Web evaluation |
+| [`agent-sdk`](packages/browseros-agent/packages/agent-sdk/) | Node.js SDK for browser automation with natural language |
+| [`cdp-protocol`](packages/browseros-agent/packages/cdp-protocol/) | Type-safe Chrome DevTools Protocol bindings |
 
 ## Contributing
 
-We'd love your help making BrowserOS better!
+We'd love your help making BrowserOS better! See our [Contributing Guide](CONTRIBUTING.md) for details.
 
-- 🐛 [Report bugs](https://github.com/browseros-ai/BrowserOS/issues)
-- 💡 [Suggest features](https://github.com/browseros-ai/BrowserOS/issues/99)
-- 💬 [Join Discord](https://discord.gg/YKwjt5vuKr)
-- 🐦 [Follow on Twitter](https://x.com/browserOS_ai)
+- [Report bugs](https://github.com/browseros-ai/BrowserOS/issues)
+- [Suggest features](https://github.com/browseros-ai/BrowserOS/issues/99)
+- [Join Discord](https://discord.gg/YKwjt5vuKr) · [Join Slack](https://dub.sh/browserOS-slack)
+- [Follow on Twitter](https://x.com/browserOS_ai)
+
+**Agent development** (TypeScript/Go) — see the [agent monorepo README](packages/browseros-agent/README.md) for setup instructions.
+
+**Browser development** (C++/Python) — requires ~100GB disk space. See [`packages/browseros`](packages/browseros/) for build instructions.
+
+## Credits
+
+- [ungoogled-chromium](https://github.com/ungoogled-software/ungoogled-chromium) — BrowserOS uses some patches for enhanced privacy. Thanks to everyone behind this project!
+- [The Chromium Project](https://www.chromium.org/) — at the core of BrowserOS, making it possible to exist in the first place.
 
 ## License
 
 BrowserOS is open source under the [AGPL-3.0 license](LICENSE).
 
-## Credits
-
-- [ungoogled-chromium](https://github.com/ungoogled-software/ungoogled-chromium) - BrowserOS uses some patches for enhanced privacy. Thanks to everyone behind this project!
-- [The Chromium Project](https://www.chromium.org/) - At the core of BrowserOS, making it possible to exist in the first place.
-
-## Citation
-
-If you use BrowserOS in your research or project, please cite:
-
-```bibtex
-@software{browseros2025,
-  author = {Sonti, Nithin and Sonti, Nikhil and {BrowserOS-team}},
-  title = {BrowserOS: The open-source Agentic browser},
-  url = {https://github.com/browseros-ai/BrowserOS},
-  year = {2025},
-  publisher = {GitHub},
-  license = {AGPL-3.0},
-}
-```
-
 Copyright &copy; 2025 Felafax, Inc.
 
 ## Stargazers
+
 Thank you to all our supporters!
 
 [![Star History Chart](https://api.star-history.com/svg?repos=browseros-ai/BrowserOS&type=Date)](https://www.star-history.com/#browseros-ai/BrowserOS&Date)
 
-## 
 <p align="center">
 Built with ❤️ from San Francisco
 </p>
-
-

packages/browseros-agent/README.md

@@ -1,8 +1,6 @@
 # BrowserOS Agent
 
-Monorepo for the BrowserOS-agent -- contains 3 packages: agent-UI, server (which contains the agent loop) and controller-extension (which is used by the tools within the agent loop).
-
-> **⚠️ NOTE:** This is only a submodule, the main project is at -- https://github.com/browseros-ai/BrowserOS
+The agent platform powering [BrowserOS](https://github.com/browseros-ai/BrowserOS) — contains the MCP server, agent UI, CLI, evaluation framework, and SDK.
 
 ## Monorepo Structure
 
@@ -10,17 +8,25 @@ Monorepo for the BrowserOS-agent -- contains 3 packages: agent-UI, server (which
 apps/
   server/          # Bun server - MCP endpoints + agent loop
   agent/           # Agent UI (Chrome extension)
+  cli/             # Go CLI for controlling BrowserOS from the terminal
+  eval/            # Evaluation framework for benchmarking agents
   controller-ext/  # BrowserOS Controller (Chrome extension for chrome.* APIs)
 
 packages/
+  agent-sdk/       # Node.js SDK (@browseros-ai/agent-sdk)
+  cdp-protocol/    # Type-safe Chrome DevTools Protocol bindings
   shared/          # Shared constants (ports, timeouts, limits)
 ```
 
 | Package | Description |
 |---------|-------------|
 | `apps/server` | Bun server exposing MCP tools and running the agent loop |
-| `apps/agent` | Agent UI - Chrome extension for the chat interface |
-| `apps/controller-ext` | BrowserOS Controller - Chrome extension that bridges `chrome.*` APIs (tabs, bookmarks, history) to the server via WebSocket |
+| `apps/agent` | Agent UI — Chrome extension for the chat interface |
+| `apps/cli` | Go CLI — control BrowserOS from the terminal or AI coding agents |
+| `apps/eval` | Benchmark framework — WebVoyager, Mind2Web evaluation |
+| `apps/controller-ext` | BrowserOS Controller — bridges `chrome.*` APIs to the server via WebSocket |
+| `packages/agent-sdk` | Node.js SDK for browser automation with natural language |
+| `packages/cdp-protocol` | Auto-generated CDP type bindings used by the server |
 | `packages/shared` | Shared constants used across packages |
 
 ## Architecture

packages/browseros-agent/apps/agent/CHANGELOG.md

@@ -0,0 +1,6 @@
+# BrowserOS Agent Extension
+
+## v0.0.52 (2026-03-26)
+
+Initial release
+

packages/browseros-agent/apps/agent/README.md

@@ -1,16 +1,24 @@
-# BrowserOS Agent Chrome Extension
+# BrowserOS Agent Extension
 
-The official Chrome extension for BrowserOS Agent, providing the UI layer for interacting with BrowserOS Core and Controllers. This extension enables intelligent browser automation, AI-powered search, and seamless integration with multiple LLM providers.
+[![License: AGPL v3](https://img.shields.io/badge/License-AGPL%20v3-blue.svg)](../../../../LICENSE)
+
+The built-in browser extension that powers BrowserOS's AI interface — new tab with unified search, side panel chat, onboarding, and settings. Built with [WXT](https://wxt.dev) and React.
+
+> For user-facing feature documentation, see [docs.browseros.com](https://docs.browseros.com).
 
 ## Features
 
 - **AI-Powered New Tab**: Custom new tab page with unified search across Google and AI assistants
-- **Side Panel Chat**: Full-featured chat interface for interacting with BrowserOS Core
+- **Side Panel Chat**: Full-featured chat interface for interacting with BrowserOS
 - **Multi-Provider Support**: Connect to various LLM providers (OpenAI, Anthropic, Azure, Bedrock, and more)
 - **MCP Integration**: Model Context Protocol support for extending AI capabilities
 - **Visual Feedback**: Animated glow effect on tabs during AI agent operations
 - **Privacy-First**: Local data handling with configurable provider settings
 
+## How It Connects
+
+The extension communicates with the [BrowserOS Server](../../apps/server/) running locally. The server handles the AI agent loop, MCP tools, and CDP connections — the extension provides the UI layer.
+
 ## Project Structure
 
 ```
@@ -80,47 +88,20 @@ Settings dashboard with multiple sections:
 
 Content script that creates a visual indicator (pulsing orange glow) around the browser viewport when an AI agent is actively working on a tab.
 
-## How Tools Are Used
-
-### Bun
-
-Bun is the exclusive runtime and package manager:
-- All scripts use `bun run <script>` instead of npm
-- Package installation via `bun install`
-- Environment files automatically loaded (no dotenv needed)
-- Enforced via `engines` field in `package.json`
-
-```bash
-bun install          # Install dependencies
-bun run dev          # Development mode
-bun run build        # Production build
-bun run lint         # Run Biome linting
-```
-
-### Biome
-
-Unified linter and formatter configured in `biome.json`:
-- **Formatting**: 2-space indentation, single quotes, no semicolons
-- **Linting**: Recommended rules plus custom rules for unused imports/variables
-- **CSS Support**: Tailwind directives parsing enabled
-- **Import Organization**: Automatic import sorting via assist actions
-
-```bash
-bun run lint         # Check for issues
-bun run lint:fix     # Auto-fix issues
-```
-
 ## Development
 
 ### Prerequisites
 
 - [Bun](https://bun.sh) installed
 - Chrome or Chromium-based browser
-- BrowserOS Core running locally (for full functionality)
+- BrowserOS Server running locally (for full functionality)
 
 ### Setup
 
 ```bash
+# Copy environment file
+cp .env.example .env.development
+
 # Install dependencies
 bun install
 
@@ -153,12 +134,30 @@ SENTRY_AUTH_TOKEN=your-token
 
 ### GraphQL Schema
 
-Codegen requires a GraphQL schema. By default it uses the bundled `schema/schema.graphql`, so no extra setup is needed. If you have access to the original API source, you can set the following environment variable
+Codegen requires a GraphQL schema. By default it uses the bundled `schema/schema.graphql`, so no extra setup is needed. If you have access to the original API source, you can set the following environment variable:
 
 ```env
 GRAPHQL_SCHEMA_PATH=/path/to/api-repo/.../schema.graphql
 ```
 
+## Development Tooling
+
+### Bun
+
+Bun is the exclusive runtime and package manager:
+- All scripts use `bun run <script>` instead of npm
+- Package installation via `bun install`
+- Environment files automatically loaded (no dotenv needed)
+- Enforced via `engines` field in `package.json`
+
+### Biome
+
+Unified linter and formatter configured in `biome.json`:
+- **Formatting**: 2-space indentation, single quotes, no semicolons
+- **Linting**: Recommended rules plus custom rules for unused imports/variables
+- **CSS Support**: Tailwind directives parsing enabled
+- **Import Organization**: Automatic import sorting via assist actions
+
 ## Scripts
 
 | Script | Description |
@@ -169,4 +168,5 @@ GRAPHQL_SCHEMA_PATH=/path/to/api-repo/.../schema.graphql
 | `bun run lint` | Run Biome linter |
 | `bun run lint:fix` | Auto-fix linting issues |
 | `bun run typecheck` | Run TypeScript type checking |
+| `bun run codegen` | Generate GraphQL types |
 | `bun run clean:cache` | Clear build caches |

packages/browseros-agent/apps/agent/entrypoints/app/ai-settings/McpPromoBanner.tsx

@@ -17,7 +17,7 @@ export const McpPromoBanner: FC = () => {
   }
 
   return (
-    <div className="relative flex items-center gap-4 rounded-xl border border-border bg-card p-4 shadow-sm transition-all hover:shadow-md">
+    <div className="flex items-center gap-4 rounded-xl border border-border bg-card p-4 shadow-sm transition-all hover:shadow-md">
       <div className="flex h-10 w-10 shrink-0 items-center justify-center rounded-lg bg-[var(--accent-orange)]/10">
         <Server className="h-5 w-5 text-[var(--accent-orange)]" />
       </div>
@@ -48,7 +48,7 @@ export const McpPromoBanner: FC = () => {
       <button
         type="button"
         onClick={() => setDismissed(true)}
-        className="absolute top-2 right-2 rounded-sm p-1 text-muted-foreground opacity-50 transition-opacity hover:opacity-100"
+        className="shrink-0 rounded-sm p-1 text-muted-foreground opacity-50 transition-opacity hover:opacity-100"
       >
         <X className="h-3.5 w-3.5" />
       </button>

packages/browseros-agent/apps/agent/entrypoints/app/login/LogoutPage.tsx

@@ -1,5 +1,5 @@
 import { useQueryClient } from '@tanstack/react-query'
-import localforage from 'localforage'
+import { clear } from 'idb-keyval'
 import { Loader2 } from 'lucide-react'
 import type { FC } from 'react'
 import { useEffect } from 'react'
@@ -25,7 +25,7 @@ export const LogoutPage: FC = () => {
       await providersStorage.removeValue()
       await scheduledJobStorage.removeValue()
       queryClient.clear()
-      await localforage.clear()
+      await clear()
 
       resetIdentity()
       await signOut()

packages/browseros-agent/apps/agent/entrypoints/sidepanel/history/ChatHistory.tsx

@@ -32,6 +32,7 @@ const RemoteChatHistory: FC<{ userId: string }> = ({ userId }) => {
   const {
     data: graphqlData,
     isLoading: isLoadingConversations,
+    isFetching,
     hasNextPage,
     isFetchingNextPage,
     fetchNextPage,
@@ -112,6 +113,7 @@ const RemoteChatHistory: FC<{ userId: string }> = ({ userId }) => {
       hasNextPage={hasNextPage}
       isFetchingNextPage={isFetchingNextPage}
       onLoadMore={fetchNextPage}
+      isRefreshing={isFetching && !isLoadingConversations}
     />
   )
 }

packages/browseros-agent/apps/agent/entrypoints/sidepanel/history/components/ConversationList.tsx

@@ -12,6 +12,7 @@ interface ConversationListProps {
   hasNextPage?: boolean
   isFetchingNextPage?: boolean
   onLoadMore?: () => void
+  isRefreshing?: boolean
 }
 
 export const ConversationList: FC<ConversationListProps> = ({
@@ -21,6 +22,7 @@ export const ConversationList: FC<ConversationListProps> = ({
   hasNextPage,
   isFetchingNextPage,
   onLoadMore,
+  isRefreshing,
 }) => {
   const loadMoreRef = useRef<HTMLDivElement>(null)
 
@@ -57,6 +59,12 @@ export const ConversationList: FC<ConversationListProps> = ({
   return (
     <main className="mt-4 flex h-full flex-1 flex-col space-y-4 overflow-y-auto">
       <div className="w-full p-3">
+        {isRefreshing && (
+          <div className="flex items-center justify-center gap-2 pb-3 text-muted-foreground text-xs">
+            <Loader2 className="h-3 w-3 animate-spin" />
+            <span>Fetching latest conversations</span>
+          </div>
+        )}
         {!hasConversations ? (
           <div className="flex flex-col items-center justify-center py-12 text-center">
             <MessageSquare className="mb-3 h-10 w-10 text-muted-foreground/50" />

packages/browseros-agent/apps/agent/entrypoints/sidepanel/history/graphql/chatHistoryDocument.ts

@@ -11,7 +11,7 @@ export const GetConversationsForHistoryDocument = graphql(`
       nodes {
         rowId
         lastMessagedAt
-        conversationMessages(last: 5, orderBy: ORDER_INDEX_ASC) {
+        conversationMessages(first: 2, orderBy: ORDER_INDEX_DESC) {
           nodes {
             message
           }

packages/browseros-agent/apps/agent/entrypoints/sidepanel/index/useChatSession.ts

@@ -76,8 +76,6 @@ export interface ChatSessionOptions {
   isIntegrationsSynced?: boolean
 }
 
-const NEWTAB_SYSTEM_PROMPT = `IMPORTANT: The user is chatting from the New Tab page. When performing browser actions, ALWAYS open content in a NEW TAB rather than navigating the current tab. The user's new tab page should remain accessible.`
-
 export const useChatSession = (options?: ChatSessionOptions) => {
   const {
     selectedLlmProviderRef,
@@ -344,12 +342,8 @@ export const useChatSession = (options?: ChatSessionOptions) => {
             reasoningEffort: provider?.reasoningEffort,
             reasoningSummary: provider?.reasoningSummary,
             browserContext,
-            userSystemPrompt:
-              options?.origin === 'newtab'
-                ? [personalizationRef.current, NEWTAB_SYSTEM_PROMPT]
-                    .filter(Boolean)
-                    .join('\n\n')
-                : personalizationRef.current,
+            origin: options?.origin ?? 'sidepanel',
+            userSystemPrompt: personalizationRef.current,
             userWorkingDir: workingDirRef.current,
             supportsImages: provider?.supportsImages,
             previousConversation,

packages/browseros-agent/apps/agent/lib/graphql/QueryProvider.tsx

@@ -1,7 +1,10 @@
 import { createAsyncStoragePersister } from '@tanstack/query-async-storage-persister'
 import { QueryClient } from '@tanstack/react-query'
-import { PersistQueryClientProvider } from '@tanstack/react-query-persist-client'
-import localforage from 'localforage'
+import {
+  type AsyncStorage,
+  PersistQueryClientProvider,
+} from '@tanstack/react-query-persist-client'
+import { del, get, set } from 'idb-keyval'
 import type { FC, ReactNode } from 'react'
 
 const queryClient = new QueryClient({
@@ -12,8 +15,14 @@ const queryClient = new QueryClient({
   },
 })
 
+const idbStorage: AsyncStorage<string> = {
+  getItem: (key: string) => get<string>(key).then((v) => v ?? null),
+  setItem: (key: string, value: string) => set(key, value),
+  removeItem: (key: string) => del(key),
+}
+
 const asyncStoragePersister = createAsyncStoragePersister({
-  storage: localforage,
+  storage: idbStorage,
 })
 
 export const QueryProvider: FC<{ children: ReactNode }> = ({ children }) => {

packages/browseros-agent/apps/agent/package.json

@@ -44,9 +44,9 @@
     "@radix-ui/react-use-controllable-state": "^1.2.2",
     "@sentry/react": "^10.31.0",
     "@sentry/vite-plugin": "^4.6.1",
-    "@tanstack/query-async-storage-persister": "^5.90.21",
-    "@tanstack/react-query": "^5.90.19",
-    "@tanstack/react-query-persist-client": "^5.90.21",
+    "@tanstack/query-async-storage-persister": "^5.95.2",
+    "@tanstack/react-query": "^5.95.2",
+    "@tanstack/react-query-persist-client": "^5.95.2",
     "@types/cytoscape": "^3.31.0",
     "@types/dompurify": "^3.2.0",
     "@webext-core/messaging": "^2.3.0",
@@ -69,8 +69,8 @@
     "eventsource-parser": "^3.0.6",
     "graphql": "^16.12.0",
     "hono": "^4.12.3",
+    "idb-keyval": "^6.2.2",
     "klavis": "^2.15.0",
-    "localforage": "^1.10.0",
     "lucide-react": "^0.562.0",
     "motion": "^12.23.24",
     "nanoid": "^5.1.6",

packages/browseros-agent/apps/cli/.env.production.example

@@ -0,0 +1,7 @@
+# Production upload env for CLI installer scripts
+
+R2_ACCOUNT_ID=
+R2_ACCESS_KEY_ID=
+R2_SECRET_ACCESS_KEY=
+R2_BUCKET=browseros
+R2_UPLOAD_PREFIX=cli

packages/browseros-agent/apps/cli/.goreleaser.yml

@@ -2,6 +2,9 @@ version: 2
 
 project_name: browseros-cli
 
+monorepo:
+  tag_prefix: browseros-cli-
+
 builds:
   - main: .
     binary: browseros-cli

packages/browseros-agent/apps/cli/CHANGELOG.md

@@ -0,0 +1 @@
+# BrowserOS CLI

packages/browseros-agent/apps/cli/README.md

@@ -1,25 +1,58 @@
 # browseros-cli
 
-Command-line interface for controlling BrowserOS via MCP. Talks to the BrowserOS MCP server over JSON-RPC 2.0 / StreamableHTTP.
+[![License: AGPL v3](https://img.shields.io/badge/License-AGPL%20v3-blue.svg)](../../../../LICENSE)
 
-## Setup
+Command-line interface for controlling BrowserOS — launch and automate the browser from the terminal or from AI coding agents like Claude Code and Gemini CLI.
+
+Communicates with the BrowserOS MCP server over JSON-RPC 2.0 / StreamableHTTP. All 53+ MCP tools are mapped to CLI commands.
+
+## Install
+
+### macOS / Linux
+
+```bash
+curl -fsSL https://cdn.browseros.com/cli/install.sh | bash
+```
+
+### Windows
+
+```powershell
+irm https://cdn.browseros.com/cli/install.ps1 | iex
+```
+
+### Build from Source
 
 Requires Go 1.25+.
 
 ```bash
-# Build
-make
-
-# First run — configure server connection
-./browseros-cli init
+make            # Build binary
+make install    # Install to $GOPATH/bin
 ```
 
-The `init` command prompts for your MCP server URL. Find it in:
-**BrowserOS → Settings → BrowserOS MCP → Server URL**
+## Quick Start
 
-The port varies per installation (e.g., `http://127.0.0.1:9004/mcp`).
+```bash
+# If BrowserOS is not installed yet
+browseros-cli install                # downloads BrowserOS for your platform
 
-Config is saved to `~/.config/browseros-cli/config.yaml`.
+# If BrowserOS is installed but not running
+browseros-cli launch                 # opens BrowserOS, waits for server
+
+# Configure the CLI (auto-discovers running BrowserOS)
+browseros-cli init --auto            # detects server URL and saves config
+
+# Verify connection
+browseros-cli health
+```
+
+### Other init modes
+
+```bash
+browseros-cli init <url>             # non-interactive — pass URL directly
+browseros-cli init                   # interactive — prompts for URL
+```
+
+Config is saved to `~/.config/browseros-cli/config.yaml`. The CLI also auto-discovers the server from `~/.browseros/server.json` (written by BrowserOS on startup).
 
 ## Usage
 
@@ -67,6 +100,12 @@ browseros-cli history recent
 browseros-cli group list
 ```
 
+## Use as MCP Server
+
+BrowserOS exposes an MCP server that AI coding agents can connect to directly. The CLI is the easiest way to verify the connection and interact with tools from the terminal.
+
+To connect Claude Code, Gemini CLI, or any MCP client, see the [MCP setup guide](https://docs.browseros.com/features/use-with-claude-code).
+
 ## Global Flags
 
 | Flag | Env Var | Description |
@@ -77,9 +116,9 @@ browseros-cli group list
 | `--debug` | `BOS_DEBUG=1` | Debug output |
 | `--timeout, -t` | | Request timeout (default: 2m) |
 
-Priority for server URL: `--server` flag > `BROWSEROS_URL` env > config file
+Priority for server URL: `--server` flag > `BROWSEROS_URL` env > `~/.browseros/server.json` > config file
 
-If no server URL is configured, the CLI exits with setup instructions instead of assuming a localhost port.
+If no server URL is configured, the CLI exits with setup instructions pointing to `install`, `launch`, and `init`.
 
 ## Testing
 
@@ -130,7 +169,9 @@ apps/cli/
 │   └── config.go       # Config file (~/.config/browseros-cli/config.yaml)
 ├── cmd/
 │   ├── root.go         # Root command, global flags
-│   ├── init.go         # Server URL configuration
+│   ├── init.go         # Server URL configuration (URL arg, --auto, interactive)
+│   ├── install.go      # install (download BrowserOS for current platform)
+│   ├── launch.go       # launch (find and start BrowserOS, wait for server)
 │   ├── open.go         # open (new_page / new_hidden_page)
 │   ├── nav.go          # nav, back, forward, reload
 │   ├── pages.go        # pages, active, close
@@ -163,4 +204,8 @@ The CLI communicates with BrowserOS via two HTTP POST requests per command:
 1. `initialize` — MCP handshake
 2. `tools/call` — execute the actual tool
 
-All 54 MCP tools are mapped to CLI commands.
+## Links
+
+- [Documentation](https://docs.browseros.com)
+- [MCP Setup Guide](https://docs.browseros.com/features/use-with-claude-code)
+- [Changelog](./CHANGELOG.md)

packages/browseros-agent/apps/cli/cmd/install.go

@@ -148,7 +148,7 @@ func runPostInstall(path string, deb bool, dim *color.Color) {
 // installMacOS mounts the DMG and copies BrowserOS.app to /Applications.
 func installMacOS(dmgPath string, dim *color.Color) {
 	fmt.Println("Mounting disk image...")
-	mountOut, err := exec.Command("hdiutil", "attach", dmgPath, "-nobrowse", "-quiet").Output()
+	mountOut, err := exec.Command("hdiutil", "attach", dmgPath, "-nobrowse").Output()
 	if err != nil {
 		dim.Println("Could not mount DMG automatically.")
 		dim.Printf("  Open it manually: open %s\n", dmgPath)

packages/browseros-agent/apps/cli/scripts/install.ps1

@@ -0,0 +1,147 @@
+#
+# Install browseros-cli for Windows — downloads the latest release binary.
+#
+# Usage (PowerShell — save and run):
+#   Invoke-WebRequest -Uri "https://cdn.browseros.com/cli/install.ps1" -OutFile install.ps1
+#   .\install.ps1
+#   .\install.ps1 -Version "0.1.0" -Dir "C:\tools\browseros"
+#
+# Usage (one-liner, uses env vars for options):
+#   & { $env:BROWSEROS_VERSION="0.1.0"; irm https://cdn.browseros.com/cli/install.ps1 | iex }
+#
+
+param(
+    [string]$Version = "",
+    [string]$Dir = ""
+)
+
+$ErrorActionPreference = "Stop"
+
+# TLS 1.2 — required for GitHub, older PS 5.1 defaults to TLS 1.0
+[Net.ServicePointManager]::SecurityProtocol = [Net.SecurityProtocolType]::Tls12
+
+$Repo = "browseros-ai/BrowserOS"
+$Binary = "browseros-cli"
+
+# When piped via irm | iex, param() is ignored — fall back to env vars
+if (-not $Version) { $Version = $env:BROWSEROS_VERSION }
+if (-not $Dir) { $Dir = if ($env:BROWSEROS_DIR) { $env:BROWSEROS_DIR } else { "$env:LOCALAPPDATA\browseros-cli\bin" } }
+
+# ── Resolve latest version ───────────────────────────────────────────────────
+
+if (-not $Version) {
+    Write-Host "Fetching latest version..."
+    $releases = Invoke-RestMethod "https://api.github.com/repos/$Repo/releases?per_page=100"
+    $tag = ($releases `
+        | Where-Object { $_.tag_name -match "^browseros-cli-v" -and $_.tag_name -notmatch "-rc" } `
+        | Select-Object -First 1).tag_name
+    if (-not $tag) {
+        Write-Error "Could not determine latest version. Try: -Version 0.1.0"
+        exit 1
+    }
+    $Version = $tag -replace "^browseros-cli-v", ""
+}
+
+Write-Host "Installing browseros-cli v$Version..."
+
+# ── Detect architecture ──────────────────────────────────────────────────────
+
+# $env:PROCESSOR_ARCHITECTURE lies under x64 emulation on ARM64 Windows.
+# Use .NET RuntimeInformation when available, fall back to PROCESSOR_ARCHITEW6432.
+$Arch = "amd64"
+try {
+    $osArch = [System.Runtime.InteropServices.RuntimeInformation]::OSArchitecture
+    if ($osArch -eq [System.Runtime.InteropServices.Architecture]::Arm64) { $Arch = "arm64" }
+} catch {
+    if ($env:PROCESSOR_ARCHITEW6432 -eq "ARM64" -or $env:PROCESSOR_ARCHITECTURE -eq "ARM64") {
+        $Arch = "arm64"
+    }
+}
+
+if (-not [Environment]::Is64BitOperatingSystem) {
+    Write-Error "32-bit Windows is not supported."
+    exit 1
+}
+
+# ── Download and extract ─────────────────────────────────────────────────────
+
+$Tag = "browseros-cli-v$Version"
+$Filename = "${Binary}_${Version}_windows_${Arch}.zip"
+$Url = "https://github.com/$Repo/releases/download/$Tag/$Filename"
+$ChecksumUrl = "https://github.com/$Repo/releases/download/$Tag/checksums.txt"
+$TmpDir = Join-Path ([System.IO.Path]::GetTempPath()) ("browseros-cli-install-" + [System.IO.Path]::GetRandomFileName())
+
+try {
+    New-Item -ItemType Directory -Path $TmpDir | Out-Null
+
+    $ZipPath = Join-Path $TmpDir $Filename
+
+    Write-Host "Downloading $Url..."
+    Invoke-WebRequest -Uri $Url -OutFile $ZipPath -UseBasicParsing
+
+    $ChecksumPath = Join-Path $TmpDir "checksums.txt"
+    $ChecksumAvailable = $true
+    try {
+        Invoke-WebRequest -Uri $ChecksumUrl -OutFile $ChecksumPath -UseBasicParsing
+    } catch {
+        $ChecksumAvailable = $false
+        Write-Warning "Could not fetch checksums.txt; skipping checksum verification. $($_.Exception.Message)"
+    }
+
+    if ($ChecksumAvailable) {
+        $ExpectedChecksum = $null
+        foreach ($line in Get-Content $ChecksumPath) {
+            $parts = $line -split '\s+', 2
+            if ($parts.Length -eq 2 -and $parts[1] -eq $Filename) {
+                $ExpectedChecksum = $parts[0].ToLowerInvariant()
+                break
+            }
+        }
+
+        if ($ExpectedChecksum) {
+            $ActualChecksum = (Get-FileHash -Path $ZipPath -Algorithm SHA256).Hash.ToLowerInvariant()
+            if ($ActualChecksum -ne $ExpectedChecksum) {
+                Write-Error "Checksum mismatch (expected $ExpectedChecksum, got $ActualChecksum)"
+                exit 1
+            }
+            Write-Host "Checksum verified."
+        } else {
+            Write-Warning "Checksum not found in checksums.txt; skipping checksum verification."
+        }
+    }
+
+    Expand-Archive -Path $ZipPath -DestinationPath $TmpDir -Force
+
+    $Exe = Get-ChildItem -Path $TmpDir -Filter "$Binary.exe" -File -Recurse | Select-Object -First 1
+    if (-not $Exe) {
+        Write-Error "Binary not found in archive."
+        exit 1
+    }
+
+    # ── Install ──────────────────────────────────────────────────────────────
+
+    if (-not (Test-Path $Dir)) {
+        New-Item -ItemType Directory -Path $Dir -Force | Out-Null
+    }
+
+    Move-Item -Force $Exe.FullName (Join-Path $Dir "$Binary.exe")
+
+    Write-Host "Installed $Binary.exe to $Dir"
+} finally {
+    if (Test-Path $TmpDir) { Remove-Item -Recurse -Force $TmpDir -ErrorAction SilentlyContinue }
+}
+
+# ── PATH ─────────────────────────────────────────────────────────────────────
+
+$UserPath = [Environment]::GetEnvironmentVariable("Path", "User")
+$PathEntries = $UserPath -split ";" | Where-Object { $_ -ne "" }
+if ($Dir -notin $PathEntries) {
+    Write-Host ""
+    Write-Host "Adding $Dir to your user PATH..."
+    [Environment]::SetEnvironmentVariable("Path", "$Dir;$UserPath", "User")
+    $env:Path = "$Dir;$env:Path"
+    Write-Host "Done. Restart your terminal for PATH changes to take effect."
+}
+
+Write-Host ""
+Write-Host "Run 'browseros-cli --help' to get started."

packages/browseros-agent/apps/cli/scripts/install.sh

@@ -0,0 +1,153 @@
+#!/usr/bin/env bash
+#
+# Install browseros-cli — downloads the latest release binary for your platform.
+#
+# Usage:
+#   curl -fsSL https://cdn.browseros.com/cli/install.sh | bash
+#
+#   # Or with options:
+#   curl -fsSL https://cdn.browseros.com/cli/install.sh | bash -s -- --version 0.1.0 --dir /usr/local/bin
+
+set -euo pipefail
+
+REPO="browseros-ai/BrowserOS"
+BINARY="browseros-cli"
+INSTALL_DIR="${HOME}/.browseros/bin"
+
+# ── Parse arguments ──────────────────────────────────────────────────────────
+
+VERSION=""
+CUSTOM_DIR=""
+
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    --version)
+      [[ $# -lt 2 ]] && { echo "Error: --version requires a value" >&2; exit 1; }
+      VERSION="$2"; shift 2 ;;
+    --dir)
+      [[ $# -lt 2 ]] && { echo "Error: --dir requires a value" >&2; exit 1; }
+      CUSTOM_DIR="$2"; shift 2 ;;
+    --help)
+      echo "Usage: install.sh [--version VERSION] [--dir INSTALL_DIR]"
+      echo ""
+      echo "  --version   Install a specific version (default: latest)"
+      echo "  --dir       Install directory (default: ~/.browseros/bin)"
+      exit 0
+      ;;
+    *) echo "Unknown option: $1" >&2; exit 1 ;;
+  esac
+done
+
+[[ -n "$CUSTOM_DIR" ]] && INSTALL_DIR="$CUSTOM_DIR"
+
+# ── Resolve latest version ───────────────────────────────────────────────────
+
+if [[ -z "$VERSION" ]]; then
+  # Use per_page=1 with a tag name filter via the releases endpoint.
+  # The tags all start with "browseros-cli-v" so we grab page 1 of those.
+  VERSION=$(curl -fsSL "https://api.github.com/repos/${REPO}/releases?per_page=100" \
+    | grep -o '"tag_name": *"browseros-cli-v[^"]*"' \
+    | grep -v -- "-rc" \
+    | head -1 \
+    | sed 's/.*browseros-cli-v//; s/"//')
+
+  if [[ -z "$VERSION" ]]; then
+    echo "Error: could not determine latest version." >&2
+    echo "  Try: install.sh --version 0.1.0" >&2
+    exit 1
+  fi
+fi
+
+echo "Installing browseros-cli v${VERSION}..."
+
+# ── Detect platform ──────────────────────────────────────────────────────────
+
+OS=$(uname -s | tr '[:upper:]' '[:lower:]')
+ARCH=$(uname -m)
+
+case "$OS" in
+  darwin) OS="darwin" ;;
+  linux)  OS="linux" ;;
+  *)      echo "Error: unsupported OS: $OS" >&2; exit 1 ;;
+esac
+
+case "$ARCH" in
+  x86_64|amd64) ARCH="amd64" ;;
+  arm64|aarch64) ARCH="arm64" ;;
+  *)             echo "Error: unsupported architecture: $ARCH" >&2; exit 1 ;;
+esac
+
+# ── Download and extract ─────────────────────────────────────────────────────
+
+FILENAME="${BINARY}_${VERSION}_${OS}_${ARCH}.tar.gz"
+TAG="browseros-cli-v${VERSION}"
+URL="https://github.com/${REPO}/releases/download/${TAG}/${FILENAME}"
+CHECKSUM_URL="https://github.com/${REPO}/releases/download/${TAG}/checksums.txt"
+
+TMPDIR_DL=$(mktemp -d)
+trap 'rm -rf "$TMPDIR_DL"' EXIT
+
+echo "Downloading ${URL}..."
+curl -fSL --progress-bar -o "${TMPDIR_DL}/${FILENAME}" "$URL"
+
+# Verify checksum if sha256sum/shasum is available
+if curl -fsSL -o "${TMPDIR_DL}/checksums.txt" "$CHECKSUM_URL" 2>/dev/null; then
+  expected=$(awk -v filename="$FILENAME" '$2 == filename { print $1; exit }' "${TMPDIR_DL}/checksums.txt")
+  if [[ -n "$expected" ]]; then
+    if command -v sha256sum >/dev/null 2>&1; then
+      actual=$(sha256sum "${TMPDIR_DL}/${FILENAME}" | awk '{print $1}')
+    elif command -v shasum >/dev/null 2>&1; then
+      actual=$(shasum -a 256 "${TMPDIR_DL}/${FILENAME}" | awk '{print $1}')
+    else
+      actual=""
+      echo "Warning: no sha256sum/shasum found; skipping checksum verification." >&2
+    fi
+    if [[ -n "$actual" && "$actual" != "$expected" ]]; then
+      echo "Error: checksum mismatch (expected ${expected}, got ${actual})" >&2
+      exit 1
+    fi
+    [[ -n "$actual" ]] && echo "Checksum verified."
+  else
+    echo "Warning: checksum not found in checksums.txt; skipping verification." >&2
+  fi
+else
+  echo "Warning: could not fetch checksums.txt; skipping checksum verification." >&2
+fi
+
+tar -xzf "${TMPDIR_DL}/${FILENAME}" -C "$TMPDIR_DL"
+
+BINARY_PATH="${TMPDIR_DL}/${BINARY}"
+if [[ ! -f "$BINARY_PATH" ]]; then
+  BINARY_PATH=$(find "$TMPDIR_DL" -type f -name "$BINARY" -print -quit)
+fi
+
+if [[ -z "$BINARY_PATH" || ! -f "$BINARY_PATH" ]]; then
+  echo "Error: binary not found in archive." >&2
+  exit 1
+fi
+
+# ── Install ──────────────────────────────────────────────────────────────────
+
+mkdir -p "$INSTALL_DIR"
+mv "$BINARY_PATH" "${INSTALL_DIR}/${BINARY}"
+chmod +x "${INSTALL_DIR}/${BINARY}"
+
+echo "Installed ${BINARY} to ${INSTALL_DIR}/${BINARY}"
+
+# ── PATH hint ────────────────────────────────────────────────────────────────
+
+if ! echo "$PATH" | tr ':' '\n' | grep -qx "$INSTALL_DIR"; then
+  echo ""
+  echo "Add browseros-cli to your PATH:"
+  echo ""
+
+  SHELL_NAME=$(basename "${SHELL:-/bin/bash}")
+  case "$SHELL_NAME" in
+    zsh)  echo "  echo 'export PATH=\"${INSTALL_DIR}:\$PATH\"' >> ~/.zshrc && source ~/.zshrc" ;;
+    fish) echo "  fish_add_path ${INSTALL_DIR}" ;;
+    *)    echo "  echo 'export PATH=\"${INSTALL_DIR}:\$PATH\"' >> ~/.bashrc && source ~/.bashrc" ;;
+  esac
+fi
+
+echo ""
+echo "Run 'browseros-cli --help' to get started."

packages/browseros-agent/apps/eval/README.md

@@ -1,6 +1,8 @@
 # BrowserOS Eval
 
-Evaluation framework for benchmarking BrowserOS browser automation agents. Runs tasks from standard datasets (WebVoyager, Mind2Web), captures trajectories with screenshots, and grades results automatically.
+[![License: AGPL v3](https://img.shields.io/badge/License-AGPL%20v3-blue.svg)](../../../../LICENSE)
+
+Evaluation framework for benchmarking BrowserOS browser automation agents. Runs tasks from standard datasets ([WebVoyager](https://arxiv.org/abs/2401.13919), [Mind2Web](https://arxiv.org/abs/2306.06070)), captures trajectories with screenshots, and grades results automatically.
 
 ## Prerequisites
 

packages/browseros-agent/apps/server/README.md

@@ -0,0 +1,181 @@
+# BrowserOS Server
+
+MCP server and AI agent loop powering BrowserOS browser automation. This is the core backend — it connects to Chromium via CDP, exposes 53+ MCP tools, and runs the AI agent that interprets natural language into browser actions.
+
+> **Runtime:** [Bun](https://bun.sh) · **Framework:** [Hono](https://hono.dev) · **AI:** [Vercel AI SDK](https://sdk.vercel.ai) · **License:** [AGPL-3.0](../../../../LICENSE)
+
+## Architecture
+
+```
+┌──────────────────────────────────────────────────────────────────────┐
+│                         MCP Clients                                  │
+│           (Agent UI, Claude Code, Gemini CLI, browseros-cli)         │
+└──────────────────────────────────────────────────────────────────────┘
+                                │
+                                │ HTTP / SSE / StreamableHTTP
+                                ▼
+┌──────────────────────────────────────────────────────────────────────┐
+│                    BrowserOS Server (Bun)                             │
+│                                                                      │
+│   /mcp ─────── MCP tool endpoints (53+ tools)                       │
+│   /chat ────── Agent streaming (AI SDK)                              │
+│   /health ─── Health check                                           │
+│                                                                      │
+│   ┌─────────────────────────────────────────────────────────────┐   │
+│   │  Agent Loop                                                  │   │
+│   │  ├── Multi-provider AI SDK (OpenAI, Anthropic, Google, ...) │   │
+│   │  ├── Session & conversation management                       │   │
+│   │  ├── Context overflow handling + compaction                  │   │
+│   │  └── MCP client for external tool servers                    │   │
+│   └─────────────────────────────────────────────────────────────┘   │
+│                                                                      │
+│   ┌────────────────────┐    ┌────────────────────────────────────┐  │
+│   │  CDP Tools          │    │  Controller Tools                  │  │
+│   │  (screenshots,      │    │  (tabs, bookmarks, history,        │  │
+│   │   DOM, network,     │    │   navigation, tab groups)          │  │
+│   │   console, input)   │    │                                    │  │
+│   └────────────────────┘    └────────────────────────────────────┘  │
+└──────────────────────────────────────────────────────────────────────┘
+          │                                         │
+          │ Chrome DevTools Protocol                │ WebSocket
+          ▼                                         ▼
+┌─────────────────────┐              ┌─────────────────────────────────┐
+│   Chromium CDP       │              │   Controller Extension          │
+│  (port 9000)         │              │  (port 9300)                    │
+│                      │              │                                 │
+│  DOM, network,       │              │  chrome.tabs, chrome.history,   │
+│  input, screenshots  │              │  chrome.bookmarks               │
+└─────────────────────┘              └─────────────────────────────────┘
+```
+
+## MCP Tools
+
+53+ tools organized by category:
+
+| Category | Tools |
+|----------|-------|
+| **Navigation** | `new_page`, `navigate`, `go_back`, `go_forward`, `reload` |
+| **Input** | `click`, `type`, `press_key`, `hover`, `scroll`, `drag`, `fill`, `clear`, `focus`, `check`, `uncheck`, `select_option`, `upload_file` |
+| **Observation** | `take_snapshot`, `take_enhanced_snapshot`, `extract_text`, `extract_links` |
+| **Screenshots** | `take_screenshot`, `save_screenshot` |
+| **Evaluation** | `evaluate_script` |
+| **Pages** | `list_pages`, `active_page`, `close_page`, `new_hidden_page` |
+| **Windows** | `window_list`, `window_create`, `window_close`, `window_activate` |
+| **Bookmarks** | `bookmark_list`, `bookmark_create`, `bookmark_remove`, `bookmark_update`, `bookmark_move`, `bookmark_search` |
+| **History** | `history_search`, `history_recent`, `history_delete`, `history_delete_range` |
+| **Tab Groups** | `group_list`, `group_create`, `group_update`, `group_ungroup`, `group_close` |
+| **Filesystem** | `ls`, `read`, `write`, `edit`, `find`, `grep`, `bash` |
+| **Memory** | `read_core`, `update_core`, `read_soul`, `update_soul`, `search_memory`, `write_memory` |
+| **DOM** | `dom`, `dom_search` |
+| **Console** | `get_console_messages` |
+| **Other** | `browseros_info`, `handle_dialog`, `wait_for`, `download`, `export_pdf`, `output_file`, `nudges` |
+
+## Agent Loop
+
+The agent loop uses the [Vercel AI SDK](https://sdk.vercel.ai) to orchestrate multi-step browser automation:
+
+- **Multi-provider support** — OpenAI, Anthropic, Google, Azure, Bedrock, OpenRouter, Ollama, LM Studio, and any OpenAI-compatible endpoint
+- **Session management** — conversations persist in a local SQLite database
+- **Context overflow handling** — automatic message compaction when context windows fill up
+- **MCP client** — connects to external MCP servers for additional tool access (40+ app integrations)
+- **Tool adapter** — bridges MCP tool definitions to AI SDK tool format
+
+### Provider Factory
+
+The provider factory (`src/agent/provider-factory.ts`) creates AI SDK providers from runtime configuration, supporting hot-swapping between providers without restart.
+
+## Skills System
+
+Skills are custom instruction sets that shape agent behavior:
+
+- **Catalog** (`src/skills/catalog.ts`) — registry of available skills
+- **Defaults** (`src/skills/defaults/`) — built-in skill definitions
+- **Loader** (`src/skills/loader.ts`) — loads skills from local and remote sources
+- **Remote sync** (`src/skills/remote-sync.ts`) — syncs skills from the BrowserOS cloud
+
+## Graph Executor (Workflows)
+
+The graph executor (`src/graph/executor.ts`) runs visual workflow graphs built in the BrowserOS workflow editor. Each node in the graph maps to agent actions, conditionals, or data transformations.
+
+## Directory Structure
+
+```
+apps/server/
+├── src/
+│   ├── index.ts               # Server entry point
+│   ├── main.ts                # Server initialization
+│   ├── api/                   # HTTP route handlers
+│   ├── agent/                 # Agent loop
+│   │   ├── ai-sdk-agent.ts    # Main agent implementation
+│   │   ├── provider-factory.ts# LLM provider factory
+│   │   ├── session-store.ts   # Conversation persistence
+│   │   ├── compaction.ts      # Context window management
+│   │   ├── mcp-builder.ts     # External MCP client setup
+│   │   └── tool-adapter.ts    # MCP → AI SDK tool bridge
+│   ├── browser/               # Browser connection layer
+│   ├── tools/                 # MCP tool implementations
+│   │   ├── navigation.ts
+│   │   ├── input.ts
+│   │   ├── snapshot.ts
+│   │   ├── memory/
+│   │   ├── filesystem/
+│   │   └── ...
+│   ├── skills/                # Skills system
+│   ├── graph/                 # Workflow graph executor
+│   ├── lib/                   # Shared utilities
+│   └── rpc.ts                 # JSON-RPC type definitions
+├── tests/
+│   ├── tools/                 # Tool-level tests
+│   ├── sdk/                   # SDK integration tests
+│   └── server.integration.test.ts
+├── graph/                     # Workflow graph definitions
+└── package.json
+```
+
+## Development
+
+### Prerequisites
+
+- [Bun](https://bun.sh) runtime
+- A running BrowserOS instance (for CDP and controller connections)
+
+### Setup
+
+```bash
+# Copy environment files
+cp .env.example .env.development
+
+# Start the server (with hot reload)
+bun run start
+```
+
+See the [agent monorepo README](../../README.md) for full environment variable reference and `process-compose` setup.
+
+### Testing
+
+```bash
+bun run test:tools          # Tool-level tests
+bun run test:integration    # Full integration tests (requires running BrowserOS)
+bun run test:sdk            # SDK integration tests
+```
+
+### Building
+
+```bash
+# Build cross-platform server binaries
+bun run build
+
+# Build for specific targets
+bun scripts/build/server.ts --target=darwin-arm64,linux-x64
+
+# Build without uploading to R2
+bun scripts/build/server.ts --target=all --no-upload
+```
+
+## Ports
+
+| Port | Env Variable | Purpose |
+|------|-------------|---------|
+| 9100 | `BROWSEROS_SERVER_PORT` | HTTP server (MCP, chat, health) |
+| 9000 | `BROWSEROS_CDP_PORT` | Chromium CDP (server connects as client) |
+| 9300 | `BROWSEROS_EXTENSION_PORT` | WebSocket for controller extension |

packages/browseros-agent/apps/server/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@browseros/server",
-  "version": "0.0.79",
+  "version": "0.0.80",
   "description": "BrowserOS server",
   "type": "module",
   "main": "./src/index.ts",

packages/browseros-agent/apps/server/src/agent/ai-sdk-agent.ts

@@ -54,8 +54,14 @@ export class AiSdkAgent {
     private _messages: UIMessage[],
     private _mcpClients: Array<{ close(): Promise<void> }>,
     private conversationId: string,
+    private _toolNames: Set<string>,
   ) {}
 
+  /** Tool names registered on this agent — used to sanitize messages during session rebuilds. */
+  get toolNames(): Set<string> {
+    return this._toolNames
+  }
+
   static async create(config: AiSdkAgentConfig): Promise<AiSdkAgent> {
     const contextWindow =
       config.resolvedConfig.contextWindowSize ??
@@ -92,10 +98,15 @@ export class AiSdkAgent {
     }
 
     // Build browser tools from the unified tool registry
+    const originPageId = config.browserContext?.activeTab?.pageId
     const allBrowserTools = buildBrowserToolSet(
       config.registry,
       config.browser,
       config.resolvedConfig.workingDir,
+      {
+        origin: config.resolvedConfig.origin,
+        originPageId,
+      },
     )
     const browserTools = config.resolvedConfig.chatMode
       ? Object.fromEntries(
@@ -155,10 +166,11 @@ export class AiSdkAgent {
       }
     }
 
-    // Add filesystem tools (Pi coding agent) — skip in chat mode (read-only)
-    const filesystemTools = config.resolvedConfig.chatMode
-      ? {}
-      : buildFilesystemToolSet(config.resolvedConfig.workingDir)
+    // Add filesystem tools — skip in chat mode (read-only) and when no workspace is selected
+    const filesystemTools =
+      !config.resolvedConfig.chatMode && config.resolvedConfig.workingDir
+        ? buildFilesystemToolSet(config.resolvedConfig.workingDir)
+        : {}
     const memoryTools = config.resolvedConfig.chatMode
       ? {}
       : buildMemoryToolSet()
@@ -205,6 +217,7 @@ export class AiSdkAgent {
       connectedApps: config.browserContext?.enabledMcpServers,
       declinedApps: config.resolvedConfig.declinedApps,
       skillsCatalog,
+      origin: config.resolvedConfig.origin,
     })
 
     // Configure compaction for context window management
@@ -263,6 +276,7 @@ export class AiSdkAgent {
       [],
       clients,
       config.resolvedConfig.conversationId,
+      new Set(Object.keys(tools)),
     )
   }
 

packages/browseros-agent/apps/server/src/agent/message-validation.ts

@@ -44,3 +44,37 @@ export function hasMessageContent(message: UIMessage): boolean {
 export function filterValidMessages(messages: UIMessage[]): UIMessage[] {
   return messages.filter(hasMessageContent)
 }
+
+/**
+ * Remove tool parts that reference tools not present in the given toolset.
+ *
+ * When a session is rebuilt with a different set of tools (e.g., workspace
+ * removed mid-conversation or MCP server disconnected), the carried-over
+ * message history may contain tool parts for tools that no longer exist.
+ * The AI SDK validates messages against the current toolset and rejects
+ * parts with no matching schema.
+ *
+ * Tool parts use the type format `tool-${toolName}` (static tools) or
+ * `dynamic-tool` (dynamic tools). This function filters out static tool
+ * parts whose tool name is not in the provided set.
+ */
+export function sanitizeMessagesForToolset(
+  messages: UIMessage[],
+  toolNames: Set<string>,
+): UIMessage[] {
+  return messages
+    .map((msg) => {
+      const filteredParts = msg.parts.filter((part) => {
+        // Static tool parts have type `tool-${toolName}`
+        if (typeof part.type === 'string' && part.type.startsWith('tool-')) {
+          const toolName = part.type.slice(5)
+          if (!toolNames.has(toolName)) return false
+        }
+        return true
+      })
+
+      if (filteredParts.length === msg.parts.length) return msg
+      return { ...msg, parts: filteredParts }
+    })
+    .filter(hasMessageContent)
+}

packages/browseros-agent/apps/server/src/agent/prompt.ts

@@ -193,19 +193,41 @@ You have persistent memory across sessions and an evolving personality. See the
 
 function getExecution(
   _exclude: Set<string>,
-  _options?: BuildSystemPromptOptions,
+  options?: BuildSystemPromptOptions,
 ): string {
-  return `<execution>
+  const isNewTab = options?.origin === 'newtab'
+
+  let executionContent = `<execution>
 ## Execution
 
 ### Philosophy
 - Execute tasks end-to-end. Don't delegate ("I found the button, you can click it").
 - Don't ask permission for routine steps. Act, then report.
 - Do not refuse by default, attempt tasks even when outcomes are uncertain.
-- For ambiguous/unclear requests, ask one targeted clarifying question.
+- For ambiguous/unclear requests, ask one targeted clarifying question.`
+
+  if (isNewTab) {
+    executionContent += `
+
+### New-Tab Origin Rules
+You are operating from the user's **New Tab page**. The active tab (Page ID from Browser Context) is the chat UI itself.
+
+**CRITICAL RULES:**
+1. **NEVER call \`navigate_page\` on the active tab** — this would destroy the chat UI and navigate the user away.
+2. **NEVER call \`close_page\` on the active tab** — same reason.
+3. For ALL browsing tasks (including single-page lookups), use \`new_page\` (background) to open URLs.
+4. For single-page lookups, open a background tab, extract data, then close it.
+5. For multi-page research, open background tabs and group them with \`group_tabs\`.
+
+### Multi-tab workflow`
+  } else {
+    executionContent += `
 - Stay on the current page for single-page tasks. Use \`navigate_page\` to move within one tab.
 
-### Multi-tab workflow
+### Multi-tab workflow`
+  }
+
+  executionContent += `
 When a task requires working on multiple pages simultaneously:
 1. **Inform the user** that you're creating background tabs for the task.
 2. **Open new tabs in background** using \`new_page\` (opens in background by default) — never steal focus from the user's current tab.
@@ -216,15 +238,23 @@ When a task requires working on multiple pages simultaneously:
 7. **Never force-switch the user's active tab.** If you need user interaction on a background tab (e.g., login, CAPTCHA), tell the user which tab needs attention and let them switch manually.
 8. **Never navigate the user's current tab** during a multi-tab task. The current tab is the user's anchor — use it only for reading (snapshots, content extraction). All navigation should happen on background tabs.
 
-**Do NOT use \`create_hidden_window\` or \`new_hidden_page\` for user-requested tasks.** Hidden windows are invisible to the user and cannot be screenshotted. Use \`new_page\` (background mode) instead — tabs appear in the user's tab strip and can be inspected. Reserve hidden windows for automated/scheduled runs only.
+**Do NOT use \`create_hidden_window\` or \`new_hidden_page\` for user-requested tasks.** Hidden windows are invisible to the user and cannot be screenshotted. Use \`new_page\` (background mode) instead — tabs appear in the user's tab strip and can be inspected. Reserve hidden windows for automated/scheduled runs only.`
 
-For single-page lookups (e.g., "go to X and read Y"), use \`navigate_page\` on the current tab. Only create new tabs when the task requires multiple pages open simultaneously.
+  if (!isNewTab) {
+    executionContent += `
+
+For single-page lookups (e.g., "go to X and read Y"), use \`navigate_page\` on the current tab. Only create new tabs when the task requires multiple pages open simultaneously.`
+  }
+
+  executionContent += `
 
 ### Tab retry discipline
 When a background tab fails (404, wrong content, unexpected redirect):
 - **Navigate the existing tab** to the correct URL with \`navigate_page\` — do NOT open a new tab for retries.
 - If you must abandon a tab, close it with \`close_page\` before opening a replacement.
-- Never let orphan tabs accumulate — each task should end with only the tabs that contain useful content.
+- Never let orphan tabs accumulate — each task should end with only the tabs that contain useful content.`
+
+  executionContent += `
 
 ### Observe → Act → Verify
 - **Before acting**: Take a snapshot to get interactive element IDs.
@@ -241,13 +271,38 @@ Some tools automatically include a fresh snapshot in their response (labeled "Ad
 - 2FA → notify user, pause for completion
 - Page not found (404) or server error (500) → report the error to the user
 </execution>`
+
+  return executionContent
 }
 
 // -----------------------------------------------------------------------------
 // section: tool-selection
 // -----------------------------------------------------------------------------
 
-function getToolSelection(): string {
+function getToolSelection(
+  _exclude: Set<string>,
+  options?: BuildSystemPromptOptions,
+): string {
+  const isNewTab = options?.origin === 'newtab'
+
+  const navTable = isNewTab
+    ? `### Navigation: single-tab vs multi-tab
+| Task | Approach |
+|------|----------|
+| Look up one page | \`new_page\` (background) → extract data → \`close_page\` |
+| Research across multiple sites | \`new_page\` (background) for each site + \`group_tabs\` |
+| Compare two pages side by side | \`new_page\` (background) × 2 + \`group_tabs\` |
+| User says "open a new tab" | \`new_page\` (background) |
+
+**Remember:** The active tab is the New Tab chat UI. Never navigate or close it.`
+    : `### Navigation: single-tab vs multi-tab
+| Task | Approach |
+|------|----------|
+| Look up one page | \`navigate_page\` on current tab |
+| Research across multiple sites | \`new_page\` (background) for each site + \`group_tabs\` |
+| Compare two pages side by side | \`new_page\` (background) × 2 + \`group_tabs\` |
+| User says "open a new tab" | \`new_page\` (background) — don't steal focus |`
+
   return `<tool_selection>
 ## Tool Selection
 
@@ -268,13 +323,7 @@ function getToolSelection(): string {
 - Prefer \`fill\` over \`press_key\` for text input. Use \`press_key\` for keyboard shortcuts (Enter, Escape, Tab, Ctrl+A, etc.).
 - Prefer clicking links over \`navigate_page\` when the link is visible. Use \`navigate_page\` for direct URL access, back/forward, or reload.
 
-### Navigation: single-tab vs multi-tab
-| Task | Approach |
-|------|----------|
-| Look up one page | \`navigate_page\` on current tab |
-| Research across multiple sites | \`new_page\` (background) for each site + \`group_tabs\` |
-| Compare two pages side by side | \`new_page\` (background) × 2 + \`group_tabs\` |
-| User says "open a new tab" | \`new_page\` (background) — don't steal focus |
+${navTable}
 
 ### Connected apps: Strata vs browser
 When an app is Connected, prefer Strata tools over browser automation. Strata is faster, more reliable, and works without navigating away from the user's current page.
@@ -668,7 +717,10 @@ const promptSections: Record<string, PromptSectionFn> = {
   security: getSecurity,
   capabilities: getCapabilities,
   execution: getExecution,
-  'tool-selection': getToolSelection,
+  'tool-selection': (
+    _exclude: Set<string>,
+    options?: BuildSystemPromptOptions,
+  ) => getToolSelection(_exclude, options),
   'external-integrations': getExternalIntegrations,
   'error-recovery': getErrorRecovery,
   'memory-and-identity': getMemoryAndIdentity,
@@ -695,6 +747,8 @@ export interface BuildSystemPromptOptions {
   /** Apps the user previously declined to connect (chose "do it manually"). */
   declinedApps?: string[]
   skillsCatalog?: string
+  /** Where the chat session originates from — determines navigation behavior. */
+  origin?: 'sidepanel' | 'newtab'
 }
 
 export function buildSystemPrompt(options?: BuildSystemPromptOptions): string {

packages/browseros-agent/apps/server/src/agent/session-store.ts

@@ -9,6 +9,8 @@ export interface AgentSession {
   browserContext?: BrowserContext
   /** MCP server names used when the session was created, for change detection. */
   mcpServerKey?: string
+  /** Workspace directory when the session was created, for change detection. */
+  workingDir?: string
 }
 
 export class SessionStore {

packages/browseros-agent/apps/server/src/agent/tool-adapter.ts

@@ -38,12 +38,14 @@ function contentToModelOutput(
 export function buildBrowserToolSet(
   registry: ToolRegistry,
   browser: Browser,
-  workingDir: string,
+  workingDir: string | undefined,
+  session?: { origin?: 'sidepanel' | 'newtab'; originPageId?: number },
 ): ToolSet {
   const toolSet: ToolSet = {}
   const ctx: ToolContext = {
     browser,
     directories: { workingDir },
+    session,
   }
 
   for (const def of registry.all()) {

packages/browseros-agent/apps/server/src/agent/types.ts

@@ -35,7 +35,7 @@ export interface ResolvedAgentConfig {
   reasoningSummary?: string
   contextWindowSize?: number
   userSystemPrompt?: string
-  workingDir: string
+  workingDir?: string
   /** Whether the model supports image inputs (vision). Defaults to true. */
   supportsImages?: boolean
   /** Eval mode - enables window management tools. Defaults to false. */
@@ -46,6 +46,8 @@ export interface ResolvedAgentConfig {
   isScheduledTask?: boolean
   /** Apps the user previously declined to connect via MCP (chose "do it manually"). */
   declinedApps?: string[]
+  /** Where the chat session originates from — determines navigation behavior. */
+  origin?: 'sidepanel' | 'newtab'
   /** BrowserOS installation ID for credit-based tracking. */
   browserosId?: string
 }

packages/browseros-agent/apps/server/src/api/services/chat-service.ts

@@ -4,16 +4,16 @@
  * SPDX-License-Identifier: AGPL-3.0-or-later
  */
 
-import { mkdir, utimes } from 'node:fs/promises'
-import path from 'node:path'
 import { createAgentUIStreamResponse, type UIMessage } from 'ai'
 import { AiSdkAgent } from '../../agent/ai-sdk-agent'
 import { formatUserMessage } from '../../agent/format-message'
-import { filterValidMessages } from '../../agent/message-validation'
-import type { SessionStore } from '../../agent/session-store'
+import {
+  filterValidMessages,
+  sanitizeMessagesForToolset,
+} from '../../agent/message-validation'
+import type { AgentSession, SessionStore } from '../../agent/session-store'
 import type { ResolvedAgentConfig } from '../../agent/types'
 import type { Browser } from '../../browser/browser'
-import { getSessionsDir } from '../../lib/browseros-dir'
 import type { KlavisClient } from '../../lib/clients/klavis/klavis-client'
 import { resolveLLMConfig } from '../../lib/clients/llm/config'
 import { logger } from '../../lib/logger'
@@ -40,8 +40,6 @@ export class ChatService {
 
     const llmConfig = await resolveLLMConfig(request, this.deps.browserosId)
 
-    const workingDir = await this.resolveSessionDir(request)
-
     const agentConfig: ResolvedAgentConfig = {
       conversationId: request.conversationId,
       provider: llmConfig.provider,
@@ -59,16 +57,18 @@ export class ChatService {
       reasoningSummary: request.reasoningSummary,
       contextWindowSize: request.contextWindowSize,
       userSystemPrompt: request.userSystemPrompt,
-      workingDir,
+      workingDir: request.userWorkingDir,
       supportsImages: request.supportsImages,
       chatMode: request.mode === 'chat',
       isScheduledTask: request.isScheduledTask,
+      origin: request.origin,
       declinedApps: request.declinedApps,
       browserosId: this.deps.browserosId,
     }
 
     let session = sessionStore.get(request.conversationId)
     let isNewSession = false
+    const contextChanges: string[] = []
 
     // Build a stable key from enabled MCP servers for change detection
     const mcpServerKey = this.buildMcpServerKey(request.browserContext)
@@ -80,23 +80,68 @@ export class ChatService {
         previous: session.mcpServerKey,
         current: mcpServerKey,
       })
-      const previousMessages = session.agent.messages
-      await session.agent.dispose()
-      sessionStore.remove(request.conversationId)
+      const previousMcpKey = session.mcpServerKey
+      session = await this.rebuildSession(
+        session,
+        request,
+        agentConfig,
+        mcpServerKey,
+      )
 
-      const browserContext = await this.resolvePageIds(request.browserContext)
-      const agent = await AiSdkAgent.create({
-        resolvedConfig: agentConfig,
-        browser: this.deps.browser,
-        registry: this.deps.registry,
-        browserContext,
-        klavisClient: this.deps.klavisClient,
-        browserosId: this.deps.browserosId,
-        aiSdkDevtoolsEnabled: this.deps.aiSdkDevtoolsEnabled,
+      const oldServers = new Set(
+        (previousMcpKey ?? '').split(',').filter(Boolean),
+      )
+      const newServers = new Set(mcpServerKey.split(',').filter(Boolean))
+      const added = [...newServers].filter((s) => !oldServers.has(s))
+      const removed = [...oldServers].filter((s) => !newServers.has(s))
+
+      const parts: string[] = []
+      if (removed.length > 0) {
+        parts.push(
+          `The following app integrations were disconnected: ${removed.join(', ')}. Their tools are no longer available.`,
+        )
+      }
+      if (added.length > 0) {
+        parts.push(
+          `The following app integrations were connected: ${added.join(', ')}. Their tools are now available.`,
+        )
+      }
+      if (parts.length === 0) {
+        parts.push(
+          'Connected app integrations changed during this conversation. Use only tools that are currently registered.',
+        )
+      }
+      contextChanges.push(parts.join(' '))
+    }
+
+    // Detect workspace change mid-conversation → rebuild session
+    if (session && session.workingDir !== request.userWorkingDir) {
+      logger.info('Workspace changed mid-conversation, rebuilding session', {
+        conversationId: request.conversationId,
+        previous: session.workingDir ?? '(none)',
+        current: request.userWorkingDir ?? '(none)',
       })
-      session = { agent, browserContext, mcpServerKey }
-      session.agent.messages = previousMessages
-      sessionStore.set(request.conversationId, session)
+      const previousWorkingDir = session.workingDir
+      session = await this.rebuildSession(
+        session,
+        request,
+        agentConfig,
+        mcpServerKey,
+      )
+
+      if (!request.userWorkingDir) {
+        contextChanges.push(
+          'The user disconnected the workspace during this conversation. Filesystem tools (filesystem_read, filesystem_write, filesystem_edit, filesystem_bash, filesystem_grep, filesystem_find, filesystem_ls) are no longer available. Return all output directly in chat. If the user asks for file operations, suggest they select a working directory from the chat toolbar.',
+        )
+      } else if (!previousWorkingDir) {
+        contextChanges.push(
+          `The user connected a workspace during this conversation. Filesystem tools are now available. Working directory: ${request.userWorkingDir}`,
+        )
+      } else {
+        contextChanges.push(
+          `The user switched workspace during this conversation. Filesystem tools now use the new working directory: ${request.userWorkingDir}`,
+        )
+      }
     }
 
     if (!session) {
@@ -141,7 +186,13 @@ export class ChatService {
         browserosId: this.deps.browserosId,
         aiSdkDevtoolsEnabled: this.deps.aiSdkDevtoolsEnabled,
       })
-      session = { agent, hiddenWindowId, browserContext, mcpServerKey }
+      session = {
+        agent,
+        hiddenWindowId,
+        browserContext,
+        mcpServerKey,
+        workingDir: request.userWorkingDir,
+      }
       sessionStore.set(request.conversationId, session)
     }
 
@@ -175,7 +226,13 @@ export class ChatService {
       request.selectedText,
       request.selectedTextSource,
     )
-    session.agent.appendUserMessage(userContent)
+
+    // Prepend tool-change context when session was rebuilt mid-conversation
+    const contextPrefix =
+      contextChanges.length > 0
+        ? `${contextChanges.map((c) => `[Context: ${c}]`).join('\n')}\n\n`
+        : ''
+    session.agent.appendUserMessage(contextPrefix + userContent)
 
     return createAgentUIStreamResponse({
       agent: session.agent.toolLoopAgent,
@@ -262,22 +319,44 @@ export class ChatService {
     })
   }
 
+  private async rebuildSession(
+    session: AgentSession,
+    request: ChatRequest,
+    agentConfig: ResolvedAgentConfig,
+    mcpServerKey: string,
+  ): Promise<AgentSession> {
+    const previousMessages = session.agent.messages
+    await session.agent.dispose()
+    this.deps.sessionStore.remove(request.conversationId)
+
+    const browserContext = await this.resolvePageIds(request.browserContext)
+    const agent = await AiSdkAgent.create({
+      resolvedConfig: agentConfig,
+      browser: this.deps.browser,
+      registry: this.deps.registry,
+      browserContext,
+      klavisClient: this.deps.klavisClient,
+      browserosId: this.deps.browserosId,
+      aiSdkDevtoolsEnabled: this.deps.aiSdkDevtoolsEnabled,
+    })
+    const newSession: AgentSession = {
+      agent,
+      browserContext,
+      mcpServerKey,
+      workingDir: request.userWorkingDir,
+    }
+    newSession.agent.messages = sanitizeMessagesForToolset(
+      previousMessages,
+      agent.toolNames,
+    )
+    this.deps.sessionStore.set(request.conversationId, newSession)
+    return newSession
+  }
+
   private buildMcpServerKey(browserContext?: BrowserContext): string {
     const managed = browserContext?.enabledMcpServers?.slice().sort() ?? []
     const custom =
       browserContext?.customMcpServers?.map((s) => s.url).sort() ?? []
     return [...managed, ...custom].join(',')
   }
-
-  private async resolveSessionDir(request: ChatRequest): Promise<string> {
-    const dir = request.userWorkingDir
-      ? request.userWorkingDir
-      : path.join(getSessionsDir(), request.conversationId)
-    await mkdir(dir, { recursive: true })
-    if (!request.userWorkingDir) {
-      const now = new Date()
-      await utimes(dir, now, now).catch(() => {})
-    }
-    return dir
-  }
 }

packages/browseros-agent/apps/server/src/api/types.ts

@@ -45,6 +45,7 @@ export const ChatRequestSchema = AgentLLMConfigSchema.extend({
   userWorkingDir: z.string().min(1).optional(),
   supportsImages: z.boolean().optional().default(true),
   mode: z.enum(['chat', 'agent']).optional().default('agent'),
+  origin: z.enum(['sidepanel', 'newtab']).optional().default('sidepanel'),
   declinedApps: z.array(z.string()).optional(),
   selectedText: z.string().optional(),
   selectedTextSource: z

packages/browseros-agent/apps/server/src/tools/framework.ts

@@ -1,3 +1,4 @@
+import { tmpdir } from 'node:os'
 import { resolve } from 'node:path'
 import type { z } from 'zod'
 import type { Browser } from '../browser/browser'
@@ -18,13 +19,19 @@ export type ToolHandler = (
 ) => Promise<void>
 
 export interface ToolDirectories {
-  workingDir: string
+  workingDir?: string
   resourcesDir?: string
 }
 
+export interface ToolSessionContext {
+  origin?: 'sidepanel' | 'newtab'
+  originPageId?: number
+}
+
 export type ToolContext = {
   browser: Browser
   directories: ToolDirectories
+  session?: ToolSessionContext
 }
 
 export function resolveWorkingPath(
@@ -32,7 +39,7 @@ export function resolveWorkingPath(
   targetPath: string,
   cwd?: string,
 ): string {
-  return resolve(cwd ?? ctx.directories.workingDir, targetPath)
+  return resolve(cwd ?? ctx.directories.workingDir ?? tmpdir(), targetPath)
 }
 
 export function defineTool<

packages/browseros-agent/apps/server/src/tools/navigation.ts

@@ -88,6 +88,17 @@ export const navigate_page = defineTool({
       return
     }
 
+    if (
+      ctx.session?.origin === 'newtab' &&
+      ctx.session.originPageId !== undefined &&
+      args.page === ctx.session.originPageId
+    ) {
+      response.error(
+        'Cannot navigate the origin tab in new-tab mode — this would destroy the chat UI. Use `new_page` to open a background tab instead.',
+      )
+      return
+    }
+
     switch (args.action) {
       case 'url':
         await ctx.browser.goto(args.page, args.url as string)
@@ -266,6 +277,17 @@ export const close_page = defineTool({
     action: z.literal('close_page'),
   }),
   handler: async (args, ctx, response) => {
+    if (
+      ctx.session?.origin === 'newtab' &&
+      ctx.session.originPageId !== undefined &&
+      args.page === ctx.session.originPageId
+    ) {
+      response.error(
+        'Cannot close the origin tab in new-tab mode — this would destroy the chat UI.',
+      )
+      return
+    }
+
     await ctx.browser.closePage(args.page)
     response.text(`Closed page ${args.page}`)
     response.data({ page: args.page, action: 'close_page' })

packages/browseros-agent/apps/server/src/tools/page-actions.ts

@@ -1,4 +1,5 @@
 import { mkdir, mkdtemp, rename, rm } from 'node:fs/promises'
+import { tmpdir } from 'node:os'
 import { join } from 'node:path'
 import { z } from 'zod'
 import { defineTool, resolveWorkingPath } from './framework'
@@ -121,10 +122,9 @@ export const download_file = defineTool({
   }),
   handler: async (args, ctx, response) => {
     const resolvedDir = resolveWorkingPath(ctx, args.path, args.cwd)
-    await mkdir(ctx.directories.workingDir, { recursive: true })
-    const tempDir = await mkdtemp(
-      join(ctx.directories.workingDir, 'browseros-dl-'),
-    )
+    const baseDir = ctx.directories.workingDir ?? tmpdir()
+    await mkdir(baseDir, { recursive: true })
+    const tempDir = await mkdtemp(join(baseDir, 'browseros-dl-'))
 
     try {
       const { filePath, suggestedFilename } =

packages/browseros-agent/apps/server/tests/agent/message-validation.test.ts

@@ -0,0 +1,299 @@
+/**
+ * @license
+ * Copyright 2025 BrowserOS
+ *
+ * Message Validation — Test Suite
+ *
+ * Tests for sanitizeMessagesForToolset, which strips tool parts from
+ * carried-over messages when a session is rebuilt with a different toolset
+ * (e.g., workspace removed or MCP server disconnected mid-conversation).
+ *
+ * Without this sanitization, the AI SDK throws a validation error because
+ * it finds tool parts in the message history that have no matching schema.
+ */
+
+import { describe, expect, it } from 'bun:test'
+import type { UIMessage } from 'ai'
+import {
+  hasMessageContent,
+  sanitizeMessagesForToolset,
+} from '../../src/agent/message-validation'
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+function makeUserMessage(text: string, id?: string): UIMessage {
+  return {
+    id: id ?? crypto.randomUUID(),
+    role: 'user',
+    parts: [{ type: 'text', text }],
+  }
+}
+
+function makeAssistantMessage(
+  parts: UIMessage['parts'],
+  id?: string,
+): UIMessage {
+  return {
+    id: id ?? crypto.randomUUID(),
+    role: 'assistant',
+    parts,
+  }
+}
+
+// ---------------------------------------------------------------------------
+// sanitizeMessagesForToolset
+// ---------------------------------------------------------------------------
+
+describe('sanitizeMessagesForToolset', () => {
+  const allTools = new Set([
+    'navigate_page',
+    'click',
+    'take_snapshot',
+    'filesystem_read',
+    'filesystem_write',
+    'memory_search',
+  ])
+
+  const noFilesystemTools = new Set([
+    'navigate_page',
+    'click',
+    'take_snapshot',
+    'memory_search',
+  ])
+
+  it('preserves messages with no tool parts', () => {
+    const messages: UIMessage[] = [
+      makeUserMessage('Hello'),
+      makeAssistantMessage([{ type: 'text', text: 'Hi there!' }]),
+    ]
+
+    const result = sanitizeMessagesForToolset(messages, noFilesystemTools)
+    expect(result).toHaveLength(2)
+    expect(result[0].parts).toHaveLength(1)
+    expect(result[1].parts).toHaveLength(1)
+  })
+
+  it('preserves tool parts when tool is in the toolset', () => {
+    const messages: UIMessage[] = [
+      makeAssistantMessage([
+        { type: 'text', text: 'Taking a snapshot...' },
+        {
+          type: 'tool-take_snapshot',
+          toolCallId: 'call-1',
+          toolName: 'take_snapshot',
+          state: 'result',
+          input: { page: 1 },
+          output: { content: 'snapshot data' },
+        } as unknown as UIMessage['parts'][number],
+      ]),
+    ]
+
+    const result = sanitizeMessagesForToolset(messages, allTools)
+    expect(result).toHaveLength(1)
+    expect(result[0].parts).toHaveLength(2)
+  })
+
+  it('strips tool parts when tool is NOT in the toolset', () => {
+    const messages: UIMessage[] = [
+      makeAssistantMessage([
+        { type: 'text', text: 'Reading file...' },
+        {
+          type: 'tool-filesystem_read',
+          toolCallId: 'call-1',
+          toolName: 'filesystem_read',
+          state: 'result',
+          input: { path: '/tmp/test.txt' },
+          output: { content: 'file data' },
+        } as unknown as UIMessage['parts'][number],
+      ]),
+    ]
+
+    const result = sanitizeMessagesForToolset(messages, noFilesystemTools)
+    expect(result).toHaveLength(1)
+    // Only the text part should remain
+    expect(result[0].parts).toHaveLength(1)
+    expect(result[0].parts[0].type).toBe('text')
+  })
+
+  it('strips multiple removed tool parts from same message', () => {
+    const messages: UIMessage[] = [
+      makeAssistantMessage([
+        { type: 'text', text: 'Working on files...' },
+        {
+          type: 'tool-filesystem_read',
+          toolCallId: 'call-1',
+          toolName: 'filesystem_read',
+          state: 'result',
+          input: { path: '/tmp/a.txt' },
+          output: {},
+        } as unknown as UIMessage['parts'][number],
+        {
+          type: 'tool-filesystem_write',
+          toolCallId: 'call-2',
+          toolName: 'filesystem_write',
+          state: 'result',
+          input: { path: '/tmp/b.txt', content: 'data' },
+          output: {},
+        } as unknown as UIMessage['parts'][number],
+      ]),
+    ]
+
+    const result = sanitizeMessagesForToolset(messages, noFilesystemTools)
+    expect(result).toHaveLength(1)
+    expect(result[0].parts).toHaveLength(1)
+    expect(result[0].parts[0].type).toBe('text')
+  })
+
+  it('keeps browser tool parts while removing filesystem tool parts', () => {
+    const messages: UIMessage[] = [
+      makeAssistantMessage([
+        {
+          type: 'tool-take_snapshot',
+          toolCallId: 'call-1',
+          toolName: 'take_snapshot',
+          state: 'result',
+          input: { page: 1 },
+          output: {},
+        } as unknown as UIMessage['parts'][number],
+        {
+          type: 'tool-filesystem_read',
+          toolCallId: 'call-2',
+          toolName: 'filesystem_read',
+          state: 'result',
+          input: { path: '/tmp/test.txt' },
+          output: {},
+        } as unknown as UIMessage['parts'][number],
+      ]),
+    ]
+
+    const result = sanitizeMessagesForToolset(messages, noFilesystemTools)
+    expect(result).toHaveLength(1)
+    expect(result[0].parts).toHaveLength(1)
+    expect((result[0].parts[0] as { type: string }).type).toBe(
+      'tool-take_snapshot',
+    )
+  })
+
+  it('removes messages that become empty after stripping', () => {
+    const messages: UIMessage[] = [
+      makeUserMessage('Read this file'),
+      makeAssistantMessage([
+        {
+          type: 'tool-filesystem_read',
+          toolCallId: 'call-1',
+          toolName: 'filesystem_read',
+          state: 'result',
+          input: { path: '/tmp/test.txt' },
+          output: {},
+        } as unknown as UIMessage['parts'][number],
+      ]),
+    ]
+
+    const result = sanitizeMessagesForToolset(messages, noFilesystemTools)
+    // The assistant message had only a tool part — after stripping, it's empty
+    // and should be filtered out by hasMessageContent
+    expect(result).toHaveLength(1)
+    expect(result[0].role).toBe('user')
+  })
+
+  it('preserves non-tool part types (reasoning, step-start, file)', () => {
+    const messages: UIMessage[] = [
+      makeAssistantMessage([
+        { type: 'text', text: 'Let me think...' },
+        {
+          type: 'reasoning',
+          reasoning: 'Analyzing the request',
+        } as unknown as UIMessage['parts'][number],
+        {
+          type: 'step-start',
+        } as unknown as UIMessage['parts'][number],
+      ]),
+    ]
+
+    const result = sanitizeMessagesForToolset(messages, noFilesystemTools)
+    expect(result).toHaveLength(1)
+    expect(result[0].parts).toHaveLength(3)
+  })
+
+  it('returns same message references when no filtering needed', () => {
+    const messages: UIMessage[] = [
+      makeUserMessage('Hello'),
+      makeAssistantMessage([{ type: 'text', text: 'Hi!' }]),
+    ]
+
+    const result = sanitizeMessagesForToolset(messages, noFilesystemTools)
+    // Messages that don't need filtering should be the same reference
+    expect(result[0]).toBe(messages[0])
+    expect(result[1]).toBe(messages[1])
+  })
+
+  it('handles empty message array', () => {
+    const result = sanitizeMessagesForToolset([], noFilesystemTools)
+    expect(result).toHaveLength(0)
+  })
+
+  it('handles empty toolset (all tools removed)', () => {
+    const messages: UIMessage[] = [
+      makeAssistantMessage([
+        { type: 'text', text: 'Working...' },
+        {
+          type: 'tool-navigate_page',
+          toolCallId: 'call-1',
+          toolName: 'navigate_page',
+          state: 'result',
+          input: {},
+          output: {},
+        } as unknown as UIMessage['parts'][number],
+      ]),
+    ]
+
+    const result = sanitizeMessagesForToolset(messages, new Set())
+    expect(result).toHaveLength(1)
+    expect(result[0].parts).toHaveLength(1)
+    expect(result[0].parts[0].type).toBe('text')
+  })
+})
+
+// ---------------------------------------------------------------------------
+// hasMessageContent (existing function, verify edge cases)
+// ---------------------------------------------------------------------------
+
+describe('hasMessageContent', () => {
+  it('rejects messages with empty parts array', () => {
+    const msg: UIMessage = {
+      id: '1',
+      role: 'assistant',
+      parts: [],
+    }
+    expect(hasMessageContent(msg)).toBe(false)
+  })
+
+  it('rejects messages with only whitespace text', () => {
+    const msg: UIMessage = {
+      id: '1',
+      role: 'assistant',
+      parts: [{ type: 'text', text: '   \n  ' }],
+    }
+    expect(hasMessageContent(msg)).toBe(false)
+  })
+
+  it('accepts messages with non-text parts', () => {
+    const msg: UIMessage = {
+      id: '1',
+      role: 'assistant',
+      parts: [
+        {
+          type: 'tool-click',
+          toolCallId: 'call-1',
+          toolName: 'click',
+          state: 'result',
+          input: {},
+          output: {},
+        } as unknown as UIMessage['parts'][number],
+      ],
+    }
+    expect(hasMessageContent(msg)).toBe(true)
+  })
+})

packages/browseros-agent/apps/server/tests/agent/prompt.test.ts

@@ -1195,3 +1195,120 @@ describe('nudges', () => {
     expect(prompt).toContain('at most once')
   })
 })
+
+// ---------------------------------------------------------------------------
+// 15. NEW-TAB ORIGIN
+//
+// Why: When the user chats from the new-tab page, the active tab IS the chat
+// UI. The agent must never navigate or close it. The prompt must adapt its
+// execution and tool-selection sections to prohibit origin tab navigation
+// and default all lookups to new_page (background).
+// ---------------------------------------------------------------------------
+
+describe('new-tab origin', () => {
+  /** Build a prompt with newtab origin */
+  function buildNewTab(overrides?: Partial<BuildSystemPromptOptions>): string {
+    return buildSystemPrompt({
+      workspaceDir: '/home/user/workspace',
+      soulContent: 'Be helpful and concise.',
+      origin: 'newtab',
+      ...overrides,
+    })
+  }
+
+  // --- Execution section ---
+
+  it('includes New-Tab Origin Rules when origin is newtab', () => {
+    const prompt = buildNewTab()
+    expect(prompt).toContain('New-Tab Origin Rules')
+    expect(prompt).toContain('New Tab page')
+    expect(prompt).toContain('chat UI itself')
+  })
+
+  it('prohibits navigate_page on active tab in newtab mode', () => {
+    const prompt = buildNewTab()
+    expect(prompt).toContain('NEVER call `navigate_page` on the active tab')
+  })
+
+  it('prohibits close_page on active tab in newtab mode', () => {
+    const prompt = buildNewTab()
+    expect(prompt).toContain('NEVER call `close_page` on the active tab')
+  })
+
+  it('requires new_page for all browsing in newtab mode', () => {
+    const prompt = buildNewTab()
+    expect(prompt).toContain(
+      'For ALL browsing tasks (including single-page lookups), use `new_page`',
+    )
+  })
+
+  it('does NOT include single-tab navigate_page guidance in newtab mode', () => {
+    // The sidepanel prompt says "use navigate_page on the current tab" for
+    // single-page lookups. This must NOT appear in newtab mode.
+    const prompt = buildNewTab()
+    expect(prompt).not.toContain(
+      'For single-page lookups (e.g., "go to X and read Y"), use `navigate_page` on the current tab',
+    )
+  })
+
+  it('does NOT include "Stay on the current page" in newtab mode', () => {
+    const prompt = buildNewTab()
+    expect(prompt).not.toContain(
+      'Stay on the current page for single-page tasks',
+    )
+  })
+
+  it('still includes common execution sections in newtab mode', () => {
+    // Newtab mode should still have multi-tab workflow, observe-act-verify, etc.
+    const prompt = buildNewTab()
+    expect(prompt).toContain('Multi-tab workflow')
+    expect(prompt).toContain('Observe → Act → Verify')
+    expect(prompt).toContain('Tab retry discipline')
+    expect(prompt).toContain('CAPTCHA')
+  })
+
+  // --- Sidepanel (default) should NOT have newtab rules ---
+
+  it('does NOT include New-Tab Origin Rules in sidepanel mode', () => {
+    const prompt = buildRegular({ origin: 'sidepanel' })
+    expect(prompt).not.toContain('New-Tab Origin Rules')
+  })
+
+  it('does NOT include New-Tab Origin Rules when origin is undefined', () => {
+    const prompt = buildRegular()
+    expect(prompt).not.toContain('New-Tab Origin Rules')
+  })
+
+  it('includes single-tab navigate_page guidance in sidepanel mode', () => {
+    const prompt = buildRegular({ origin: 'sidepanel' })
+    expect(prompt).toContain(
+      'For single-page lookups (e.g., "go to X and read Y"), use `navigate_page` on the current tab',
+    )
+  })
+
+  // --- Tool selection section ---
+
+  it('tool selection table uses new_page for lookups in newtab mode', () => {
+    const prompt = buildNewTab()
+    expect(prompt).toContain(
+      '`new_page` (background) → extract data → `close_page`',
+    )
+  })
+
+  it('tool selection includes reminder about active tab in newtab mode', () => {
+    const prompt = buildNewTab()
+    expect(prompt).toContain(
+      'The active tab is the New Tab chat UI. Never navigate or close it.',
+    )
+  })
+
+  it('tool selection table uses navigate_page for lookups in sidepanel mode', () => {
+    const prompt = buildRegular({ origin: 'sidepanel' })
+    expect(prompt).toContain('`navigate_page` on current tab')
+  })
+
+  it('tool selection does NOT have newtab reminder in sidepanel mode', () => {
+    const prompt = buildRegular({ origin: 'sidepanel' })
+    expect(prompt).not.toContain('The active tab is the New Tab chat UI')
+  })
+})

packages/browseros-agent/apps/server/tests/tools/navigation-newtab-guard.test.ts

@@ -0,0 +1,270 @@
+/**
+ * New-tab origin navigation guards.
+ *
+ * When the chat session originates from the new-tab page, navigate_page and
+ * close_page must reject attempts to act on the origin tab. These are
+ * integration tests that run against a real browser to verify the guards
+ * work end-to-end through executeTool.
+ */
+
+import { describe, it } from 'bun:test'
+import assert from 'node:assert'
+import type { ToolContext, ToolDefinition } from '../../src/tools/framework'
+import { executeTool } from '../../src/tools/framework'
+import { close_page, navigate_page, new_page } from '../../src/tools/navigation'
+import type { ToolResult } from '../../src/tools/response'
+import { withBrowser } from '../__helpers__/with-browser'
+
+function textOf(result: {
+  content: { type: string; text?: string }[]
+}): string {
+  return result.content
+    .filter((c) => c.type === 'text')
+    .map((c) => c.text)
+    .join('\n')
+}
+
+function structuredOf<T>(result: { structuredContent?: unknown }): T {
+  assert.ok(result.structuredContent, 'Expected structuredContent')
+  return result.structuredContent as T
+}
+
+describe('new-tab origin navigation guards', () => {
+  // Helper: execute a tool with newtab session context
+  function executeWithSession(
+    ctx: { browser: ToolContext['browser'] },
+    tool: ToolDefinition,
+    args: unknown,
+    session: ToolContext['session'],
+  ): Promise<ToolResult> {
+    const signal = AbortSignal.timeout(30_000)
+    return executeTool(
+      tool,
+      args,
+      {
+        browser: ctx.browser,
+        directories: { workingDir: process.cwd() },
+        session,
+      },
+      signal,
+    )
+  }
+
+  // -------------------------------------------------------------------------
+  // navigate_page guards
+  // -------------------------------------------------------------------------
+
+  it('navigate_page rejects navigation on origin tab in newtab mode', async () => {
+    await withBrowser(async ({ browser }) => {
+      // Use a new page as the simulated "origin tab"
+      const setupResult = await executeTool(
+        new_page,
+        { url: 'about:blank' },
+        { browser, directories: { workingDir: process.cwd() } },
+        AbortSignal.timeout(30_000),
+      )
+      const originPageId = structuredOf<{ pageId: number }>(setupResult).pageId
+
+      const result = await executeWithSession(
+        { browser },
+        navigate_page,
+        { page: originPageId, action: 'url', url: 'https://example.com' },
+        { origin: 'newtab', originPageId },
+      )
+
+      assert.ok(result.isError, 'Expected navigate_page to be rejected')
+      assert.ok(
+        textOf(result).includes('Cannot navigate the origin tab'),
+        `Expected origin tab error, got: ${textOf(result)}`,
+      )
+
+      // Cleanup
+      await executeTool(
+        close_page,
+        { page: originPageId },
+        { browser, directories: { workingDir: process.cwd() } },
+        AbortSignal.timeout(30_000),
+      )
+    })
+  }, 60_000)
+
+  it('navigate_page allows navigation on non-origin tab in newtab mode', async () => {
+    await withBrowser(async ({ browser }) => {
+      const originResult = await executeTool(
+        new_page,
+        { url: 'about:blank' },
+        { browser, directories: { workingDir: process.cwd() } },
+        AbortSignal.timeout(30_000),
+      )
+      const originPageId = structuredOf<{ pageId: number }>(originResult).pageId
+
+      // Open a second tab — this is NOT the origin tab
+      const otherResult = await executeTool(
+        new_page,
+        { url: 'about:blank' },
+        { browser, directories: { workingDir: process.cwd() } },
+        AbortSignal.timeout(30_000),
+      )
+      const otherPageId = structuredOf<{ pageId: number }>(otherResult).pageId
+
+      const result = await executeWithSession(
+        { browser },
+        navigate_page,
+        { page: otherPageId, action: 'url', url: 'https://example.com' },
+        { origin: 'newtab', originPageId },
+      )
+
+      assert.ok(
+        !result.isError,
+        `Expected success, got error: ${textOf(result)}`,
+      )
+      assert.ok(textOf(result).includes('Navigated to'))
+
+      // Cleanup
+      const noSession = { browser, directories: { workingDir: process.cwd() } }
+      await executeTool(
+        close_page,
+        { page: otherPageId },
+        noSession,
+        AbortSignal.timeout(30_000),
+      )
+      await executeTool(
+        close_page,
+        { page: originPageId },
+        noSession,
+        AbortSignal.timeout(30_000),
+      )
+    })
+  }, 60_000)
+
+  it('navigate_page works normally in sidepanel mode', async () => {
+    await withBrowser(async ({ browser }) => {
+      const setupResult = await executeTool(
+        new_page,
+        { url: 'about:blank' },
+        { browser, directories: { workingDir: process.cwd() } },
+        AbortSignal.timeout(30_000),
+      )
+      const pageId = structuredOf<{ pageId: number }>(setupResult).pageId
+
+      const result = await executeWithSession(
+        { browser },
+        navigate_page,
+        { page: pageId, action: 'url', url: 'https://example.com' },
+        { origin: 'sidepanel', originPageId: pageId },
+      )
+
+      assert.ok(
+        !result.isError,
+        `Expected success, got error: ${textOf(result)}`,
+      )
+      assert.ok(textOf(result).includes('Navigated to'))
+
+      await executeTool(
+        close_page,
+        { page: pageId },
+        { browser, directories: { workingDir: process.cwd() } },
+        AbortSignal.timeout(30_000),
+      )
+    })
+  }, 60_000)
+
+  it('navigate_page works when session is undefined (backwards compat)', async () => {
+    await withBrowser(async ({ browser, execute }) => {
+      const setupResult = await execute(new_page, { url: 'about:blank' })
+      const pageId = structuredOf<{ pageId: number }>(setupResult).pageId
+
+      // execute() from withBrowser passes no session — simulates old clients
+      const result = await execute(navigate_page, {
+        page: pageId,
+        action: 'url',
+        url: 'https://example.com',
+      })
+
+      assert.ok(
+        !result.isError,
+        `Expected success, got error: ${textOf(result)}`,
+      )
+
+      await execute(close_page, { page: pageId })
+    })
+  }, 60_000)
+
+  // -------------------------------------------------------------------------
+  // close_page guards
+  // -------------------------------------------------------------------------
+
+  it('close_page rejects closing origin tab in newtab mode', async () => {
+    await withBrowser(async ({ browser }) => {
+      const setupResult = await executeTool(
+        new_page,
+        { url: 'about:blank' },
+        { browser, directories: { workingDir: process.cwd() } },
+        AbortSignal.timeout(30_000),
+      )
+      const originPageId = structuredOf<{ pageId: number }>(setupResult).pageId
+
+      const result = await executeWithSession(
+        { browser },
+        close_page,
+        { page: originPageId },
+        { origin: 'newtab', originPageId },
+      )
+
+      assert.ok(result.isError, 'Expected close_page to be rejected')
+      assert.ok(
+        textOf(result).includes('Cannot close the origin tab'),
+        `Expected origin tab error, got: ${textOf(result)}`,
+      )
+
+      // Clean up the page we created (without newtab guard)
+      await executeTool(
+        close_page,
+        { page: originPageId },
+        { browser, directories: { workingDir: process.cwd() } },
+        AbortSignal.timeout(30_000),
+      )
+    })
+  }, 60_000)
+
+  it('close_page allows closing non-origin tab in newtab mode', async () => {
+    await withBrowser(async ({ browser }) => {
+      const originResult = await executeTool(
+        new_page,
+        { url: 'about:blank' },
+        { browser, directories: { workingDir: process.cwd() } },
+        AbortSignal.timeout(30_000),
+      )
+      const originPageId = structuredOf<{ pageId: number }>(originResult).pageId
+
+      const otherResult = await executeTool(
+        new_page,
+        { url: 'about:blank' },
+        { browser, directories: { workingDir: process.cwd() } },
+        AbortSignal.timeout(30_000),
+      )
+      const otherPageId = structuredOf<{ pageId: number }>(otherResult).pageId
+
+      const result = await executeWithSession(
+        { browser },
+        close_page,
+        { page: otherPageId },
+        { origin: 'newtab', originPageId },
+      )
+
+      assert.ok(
+        !result.isError,
+        `Expected success, got error: ${textOf(result)}`,
+      )
+      assert.ok(textOf(result).includes(`Closed page ${otherPageId}`))
+
+      // Cleanup origin page
+      await executeTool(
+        close_page,
+        { page: originPageId },
+        { browser, directories: { workingDir: process.cwd() } },
+        AbortSignal.timeout(30_000),
+      )
+    })
+  }, 60_000)
+})

packages/browseros-agent/bun.lock

@@ -51,9 +51,9 @@
         "@radix-ui/react-use-controllable-state": "^1.2.2",
         "@sentry/react": "^10.31.0",
         "@sentry/vite-plugin": "^4.6.1",
-        "@tanstack/query-async-storage-persister": "^5.90.21",
-        "@tanstack/react-query": "^5.90.19",
-        "@tanstack/react-query-persist-client": "^5.90.21",
+        "@tanstack/query-async-storage-persister": "^5.95.2",
+        "@tanstack/react-query": "^5.95.2",
+        "@tanstack/react-query-persist-client": "^5.95.2",
         "@types/cytoscape": "^3.31.0",
         "@types/dompurify": "^3.2.0",
         "@webext-core/messaging": "^2.3.0",
@@ -76,8 +76,8 @@
         "eventsource-parser": "^3.0.6",
         "graphql": "^16.12.0",
         "hono": "^4.12.3",
+        "idb-keyval": "^6.2.2",
         "klavis": "^2.15.0",
-        "localforage": "^1.10.0",
         "lucide-react": "^0.562.0",
         "motion": "^12.23.24",
         "nanoid": "^5.1.6",
@@ -170,7 +170,7 @@
     },
     "apps/server": {
       "name": "@browseros/server",
-      "version": "0.0.79",
+      "version": "0.0.80",
       "bin": {
         "browseros-server": "./src/index.ts",
       },
@@ -231,7 +231,7 @@
     },
     "packages/agent-sdk": {
       "name": "@browseros-ai/agent-sdk",
-      "version": "0.0.5",
+      "version": "0.0.7",
       "dependencies": {
         "eventsource-parser": "^3.0.6",
         "zod-to-json-schema": "^3.24.1",
@@ -1780,15 +1780,15 @@
 
     "@tailwindcss/vite": ["@tailwindcss/vite@4.1.18", "", { "dependencies": { "@tailwindcss/node": "4.1.18", "@tailwindcss/oxide": "4.1.18", "tailwindcss": "4.1.18" }, "peerDependencies": { "vite": "^5.2.0 || ^6 || ^7" } }, "sha512-jVA+/UpKL1vRLg6Hkao5jldawNmRo7mQYrZtNHMIVpLfLhDml5nMRUo/8MwoX2vNXvnaXNNMedrMfMugAVX1nA=="],
 
-    "@tanstack/query-async-storage-persister": ["@tanstack/query-async-storage-persister@5.90.21", "", { "dependencies": { "@tanstack/query-core": "5.90.19", "@tanstack/query-persist-client-core": "5.91.18" } }, "sha512-edpZzybucsMxGiWOMy24io+5l4Lciw4bgv/N2EXQnSp0exS1siTOQbCAQET8jwStCEnaoEiS8ljChnfmnd2pkw=="],
+    "@tanstack/query-async-storage-persister": ["@tanstack/query-async-storage-persister@5.95.2", "", { "dependencies": { "@tanstack/query-core": "5.95.2", "@tanstack/query-persist-client-core": "5.95.2" } }, "sha512-ZhPIHH8J833OVZhEWwwdOk0uhY94d9Wgdnq97JoQx4Ui4xx4Dh6e7WPUrjlUWo88Yqi4Ij+T1o/VR7Vlbnkbjw=="],
 
-    "@tanstack/query-core": ["@tanstack/query-core@5.90.19", "", {}, "sha512-GLW5sjPVIvH491VV1ufddnfldyVB+teCnpPIvweEfkpRx7CfUmUGhoh9cdcUKBh/KwVxk22aNEDxeTsvmyB/WA=="],
+    "@tanstack/query-core": ["@tanstack/query-core@5.95.2", "", {}, "sha512-o4T8vZHZET4Bib3jZ/tCW9/7080urD4c+0/AUaYVpIqOsr7y0reBc1oX3ttNaSW5mYyvZHctiQ/UOP2PfdmFEQ=="],
 
-    "@tanstack/query-persist-client-core": ["@tanstack/query-persist-client-core@5.91.18", "", { "dependencies": { "@tanstack/query-core": "5.90.19" } }, "sha512-1FNvccVTFZph07dtA/4p5PRAVKfqVLPPxA8BXUoYjPOZP6T4qY1asItVkUFtUr6kBu48i0DBnEEZQLmK82BIFw=="],
+    "@tanstack/query-persist-client-core": ["@tanstack/query-persist-client-core@5.95.2", "", { "dependencies": { "@tanstack/query-core": "5.95.2" } }, "sha512-Opfj34WZ594YXpEcZEs8WBiyPGrjrKlGILfk/Ss283uwWQ36C5nX3tRY/bBiXmM82KWauUuNvahwGwiyco/8cQ=="],
 
-    "@tanstack/react-query": ["@tanstack/react-query@5.90.19", "", { "dependencies": { "@tanstack/query-core": "5.90.19" }, "peerDependencies": { "react": "^18 || ^19" } }, "sha512-qTZRZ4QyTzQc+M0IzrbKHxSeISUmRB3RPGmao5bT+sI6ayxSRhn0FXEnT5Hg3as8SBFcRosrXXRFB+yAcxVxJQ=="],
+    "@tanstack/react-query": ["@tanstack/react-query@5.95.2", "", { "dependencies": { "@tanstack/query-core": "5.95.2" }, "peerDependencies": { "react": "^18 || ^19" } }, "sha512-/wGkvLj/st5Ud1Q76KF1uFxScV7WeqN1slQx5280ycwAyYkIPGaRZAEgHxe3bjirSd5Zpwkj6zNcR4cqYni/ZA=="],
 
-    "@tanstack/react-query-persist-client": ["@tanstack/react-query-persist-client@5.90.21", "", { "dependencies": { "@tanstack/query-persist-client-core": "5.91.18" }, "peerDependencies": { "@tanstack/react-query": "^5.90.19", "react": "^18 || ^19" } }, "sha512-ix9fVeS96QZxaMPRUwf+k6RlNLJxvu0WSjQp9nPiosxRqquxz0tJ5ErMsclZO9Q/jmVhoFm4FKEZ8mfTLBMoiQ=="],
+    "@tanstack/react-query-persist-client": ["@tanstack/react-query-persist-client@5.95.2", "", { "dependencies": { "@tanstack/query-persist-client-core": "5.95.2" }, "peerDependencies": { "@tanstack/react-query": "^5.95.2", "react": "^18 || ^19" } }, "sha512-i3fvzD8gaLgQyFvRc/+iSUr60aL31tMN+5QM11zdPRg0K9CirIQjHD7WgXFBnD29KJDvcjcv7OrIBaPwZ+H9xw=="],
 
     "@theguild/federation-composition": ["@theguild/federation-composition@0.21.3", "", { "dependencies": { "constant-case": "^3.0.4", "debug": "4.4.3", "json5": "^2.2.3", "lodash.sortby": "^4.7.0" }, "peerDependencies": { "graphql": "^16.0.0" } }, "sha512-+LlHTa4UbRpZBog3ggAxjYIFvdfH3UMvvBUptur19TMWkqU4+n3GmN+mDjejU+dyBXIG27c25RsiQP1HyvM99g=="],
 
@@ -2960,6 +2960,8 @@
 
     "iconv-lite": ["iconv-lite@0.7.2", "", { "dependencies": { "safer-buffer": ">= 2.1.2 < 3.0.0" } }, "sha512-im9DjEDQ55s9fL4EYzOAv0yMqmMBSZp6G0VvFyTMPKWxiSBHUj9NW/qqLmXUwXrrM7AvqSlTCfvqRb0cM8yYqw=="],
 
+    "idb-keyval": ["idb-keyval@6.2.2", "", {}, "sha512-yjD9nARJ/jb1g+CvD0tlhUHOrJ9Sy0P8T9MF3YaLlHnSRpwPfpTX0XIvpmw3gAJUmEu3FiICLBDPXVwyEvrleg=="],
+
     "ieee754": ["ieee754@1.2.1", "", {}, "sha512-dcyqhDvX1C46lXZcVqCpK+FtMRQVdIMN6/Df5js2zouUsqG7I6sFxitIC+7KYK29KdXOLHdu9zL4sFnoVQnqaA=="],
 
     "ignore": ["ignore@7.0.5", "", {}, "sha512-Hs59xBNfUIunMFgWAbGX5cq6893IbWg4KnrjbYwX3tx0ztorVgTDA6B2sxf8ejHJ4wz8BqGUMYlnzNBer5NvGg=="],
@@ -3186,7 +3188,7 @@
 
     "lib0": ["lib0@0.2.117", "", { "dependencies": { "isomorphic.js": "^0.2.4" }, "bin": { "0serve": "bin/0serve.js", "0gentesthtml": "bin/gentesthtml.js", "0ecdsa-generate-keypair": "bin/0ecdsa-generate-keypair.js" } }, "sha512-DeXj9X5xDCjgKLU/7RR+/HQEVzuuEUiwldwOGsHK/sfAfELGWEyTcf0x+uOvCvK3O2zPmZePXWL85vtia6GyZw=="],
 
-    "lie": ["lie@3.1.1", "", { "dependencies": { "immediate": "~3.0.5" } }, "sha512-RiNhHysUjhrDQntfYSfY4MU24coXXdEOgw9WGcKHNeEwffDYbF//u87M1EWaMGzuFoSbqW0C9C6lEEhDOAswfw=="],
+    "lie": ["lie@3.3.0", "", { "dependencies": { "immediate": "~3.0.5" } }, "sha512-UaiMJzeWRlEujzAuw5LokY1L5ecNQYZKfmyZ9L7wDHb/p5etKaxXhohBcrw0EYby+G/NA52vRSN4N39dxHAIwQ=="],
 
     "lighthouse-logger": ["lighthouse-logger@2.0.2", "", { "dependencies": { "debug": "^4.4.1", "marky": "^1.2.2" } }, "sha512-vWl2+u5jgOQuZR55Z1WM0XDdrJT6mzMP8zHUct7xTlWhuQs+eV0g+QL0RQdFjT54zVmbhLCP8vIVpy1wGn/gCg=="],
 
@@ -3232,8 +3234,6 @@
 
     "local-pkg": ["local-pkg@1.1.2", "", { "dependencies": { "mlly": "^1.7.4", "pkg-types": "^2.3.0", "quansync": "^0.2.11" } }, "sha512-arhlxbFRmoQHl33a0Zkle/YWlmNwoyt6QNZEIJcqNbdrsix5Lvc4HyyI3EnwxTYlZYc32EbYrQ8SzEZ7dqgg9A=="],
 
-    "localforage": ["localforage@1.10.0", "", { "dependencies": { "lie": "3.1.1" } }, "sha512-14/H1aX7hzBBmmh7sGPd+AOMkkIrHM3Z1PAyGgZigA1H1p5O5ANnMyWzvpAETtG68/dC4pC0ncy3+PPGzXZHPg=="],
-
     "locate-path": ["locate-path@6.0.0", "", { "dependencies": { "p-locate": "^5.0.0" } }, "sha512-iPZK6eYjbxRu3uB4/WZ3EsEIMJFMqAoopl3R+zuq0UjcAm/MO6KCweDgPfP3elTztoKP3KtnVHxTn2NHBSDVUw=="],
 
     "lodash": ["lodash@4.17.23", "", {}, "sha512-LgVTMpQtIopCi79SJeDiP0TfWi5CNEc/L/aRdTh3yIvmZXTnheWpKjSZhnvMl8iXbC1tFg9gdHHDMLoV7CnG+w=="],
@@ -4552,7 +4552,7 @@
 
     "@better-auth/core/zod": ["zod@4.3.5", "", {}, "sha512-k7Nwx6vuWx1IJ9Bjuf4Zt1PEllcwe7cls3VNzm4CQ1/hgtFUK2bRNG3rvnpPUhFjmqJKAKtjV576KnUkHocg/g=="],
 
-    "@browseros/agent/@types/bun": ["@types/bun@1.3.10", "", { "dependencies": { "bun-types": "1.3.10" } }, "sha512-0+rlrUrOrTSskibryHbvQkDOWRJwJZqZlxrUs1u4oOoTln8+WIXBPmAuCF35SWB2z4Zl3E84Nl/D0P7803nigQ=="],
+    "@browseros/agent/@types/bun": ["@types/bun@1.3.11", "", { "dependencies": { "bun-types": "1.3.11" } }, "sha512-5vPne5QvtpjGpsGYXiFyycfpDF2ECyPcTSsFBMa0fraoxiQyMJ3SmuQIGhzPg2WJuWxVBoxWJ2kClYTcw/4fAg=="],
 
     "@browseros/agent/zod": ["zod@4.3.5", "", {}, "sha512-k7Nwx6vuWx1IJ9Bjuf4Zt1PEllcwe7cls3VNzm4CQ1/hgtFUK2bRNG3rvnpPUhFjmqJKAKtjV576KnUkHocg/g=="],
 
@@ -5104,8 +5104,6 @@
 
     "jest-worker/supports-color": ["supports-color@8.1.1", "", { "dependencies": { "has-flag": "^4.0.0" } }, "sha512-MpUEN2OodtUzxvKQl72cUF7RQ5EiHsGvSsVG0ia9c5RbWGL2CI4C7EpPS8UTBIplnlzZiNuV56w+FuNxy3ty2Q=="],
 
-    "jszip/lie": ["lie@3.3.0", "", { "dependencies": { "immediate": "~3.0.5" } }, "sha512-UaiMJzeWRlEujzAuw5LokY1L5ecNQYZKfmyZ9L7wDHb/p5etKaxXhohBcrw0EYby+G/NA52vRSN4N39dxHAIwQ=="],
-
     "jszip/readable-stream": ["readable-stream@2.3.8", "", { "dependencies": { "core-util-is": "~1.0.0", "inherits": "~2.0.3", "isarray": "~1.0.0", "process-nextick-args": "~2.0.0", "safe-buffer": "~5.1.1", "string_decoder": "~1.1.1", "util-deprecate": "~1.0.1" } }, "sha512-8p0AUk4XODgIewSi0l8Epjs+EVnWiK7NoDIEGU0HhE7+ZyY8D1IMY7odu5lRrFXGg71L15KG8QrPmum45RTtdA=="],
 
     "jwa/safe-buffer": ["safe-buffer@5.2.1", "", {}, "sha512-rp3So07KcdmmKbGvgaNxQSJr7bGVSVk5S9Eq1F+ppbRo70+YeaDxkw5Dd8NPN+GD6bjnYm2VuPuCXmpuYvmCXQ=="],
@@ -5306,7 +5304,7 @@
 
     "@aws-crypto/util/@smithy/util-utf8/@smithy/util-buffer-from": ["@smithy/util-buffer-from@2.2.0", "", { "dependencies": { "@smithy/is-array-buffer": "^2.2.0", "tslib": "^2.6.2" } }, "sha512-IJdWBbTcMQ6DA0gdNhh/BwrLkDR+ADW5Kr1aZmd4k3DIF6ezMV4R2NIAmT08wQJ3yUK82thHWmC/TnK/wpMMIA=="],
 
-    "@browseros/agent/@types/bun/bun-types": ["bun-types@1.3.10", "", { "dependencies": { "@types/node": "*" } }, "sha512-tcpfCCl6XWo6nCVnpcVrxQ+9AYN1iqMIzgrSKYMB/fjLtV2eyAVEg7AxQJuCq/26R6HpKWykQXuSOq/21RYcbg=="],
+    "@browseros/agent/@types/bun/bun-types": ["bun-types@1.3.11", "", { "dependencies": { "@types/node": "*" } }, "sha512-1KGPpoxQWl9f6wcZh57LvrPIInQMn2TQ7jsgxqpRzg+l0QPOFvJVH7HmvHo/AiPgwXy+/Thf6Ov3EdVn1vOabg=="],
 
     "@browseros/eval/@aws-sdk/client-s3/@aws-sdk/core": ["@aws-sdk/core@3.973.23", "", { "dependencies": { "@aws-sdk/types": "^3.973.6", "@aws-sdk/xml-builder": "^3.972.15", "@smithy/core": "^3.23.12", "@smithy/node-config-provider": "^4.3.12", "@smithy/property-provider": "^4.2.12", "@smithy/protocol-http": "^5.3.12", "@smithy/signature-v4": "^5.3.12", "@smithy/smithy-client": "^4.12.7", "@smithy/types": "^4.13.1", "@smithy/util-base64": "^4.3.2", "@smithy/util-middleware": "^4.2.12", "@smithy/util-utf8": "^4.2.2", "tslib": "^2.6.2" } }, "sha512-aoJncvD1XvloZ9JLnKqTRL9dBy+Szkryoag9VT+V1TqsuUgIxV9cnBVM/hrDi2vE8bDqLiDR8nirdRcCdtJu0w=="],
 

packages/browseros-agent/package.json

@@ -21,6 +21,7 @@
     "build:server": "FORCE_COLOR=1 bun scripts/build/server.ts --target=all",
     "build:server:ci": "FORCE_COLOR=1 bun scripts/build/server.ts --target=all --compile-only",
     "build:server:test": "FORCE_COLOR=1 bun scripts/build/server.ts --target=darwin-arm64 --no-upload",
+    "upload:cli-installers": "bun scripts/build/cli.ts",
     "start:server:test": "bun run build:server:test && set -a && . apps/server/.env.development && set +a && dist/prod/server/.tmp/binaries/browseros-server-darwin-arm64",
     "build:agent:dev": "FORCE_COLOR=1 bun run --filter @browseros/agent --elide-lines=0 build:dev",
     "build:agent": "bun run codegen:agent && bun run --filter @browseros/agent build",

packages/browseros-agent/packages/agent-sdk/CHANGELOG.md

@@ -1 +1,12 @@
 # @browseros-ai/agent-sdk
+
+## v0.0.7 (2026-03-26)
+
+## What's Changed
+
+- chore: bump @browseros-ai/agent-sdk to 0.0.7 (#569) (#569) @DaniAkash
+
+## Contributors
+
+- @DaniAkash
+

packages/browseros-agent/packages/agent-sdk/README.md

@@ -1,7 +1,17 @@
 # @browseros-ai/agent-sdk
 
+[![npm version](https://img.shields.io/npm/v/@browseros-ai/agent-sdk)](https://www.npmjs.com/package/@browseros-ai/agent-sdk)
+[![License: AGPL v3](https://img.shields.io/badge/License-AGPL%20v3-blue.svg)](../../../../LICENSE)
+
 Browser automation SDK for BrowserOS — navigate, interact, extract data, and verify page state using natural language.
 
+Build automations that describe *what* to do, not *how* to do it. The SDK connects to a running BrowserOS instance and translates natural language instructions into browser actions using your choice of LLM provider.
+
+## Prerequisites
+
+- A running [BrowserOS](https://browseros.com) instance
+- An API key for at least one [supported LLM provider](#llm-providers)
+
 ## Installation
 
 ```bash
@@ -17,7 +27,7 @@ import { Agent } from '@browseros-ai/agent-sdk'
 import { z } from 'zod'
 
 const agent = new Agent({
-  url: 'http://localhost:3000',
+  url: 'http://localhost:9100',
   llm: {
     provider: 'openai',
     apiKey: process.env.OPENAI_API_KEY,
@@ -42,6 +52,40 @@ const { data } = await agent.extract('get all product names and prices', {
 const { success, reason } = await agent.verify('user is logged in')
 ```
 
+## Multi-Step Example
+
+Combine navigation, actions, extraction, and verification for end-to-end automation:
+
+```typescript
+import { Agent } from '@browseros-ai/agent-sdk'
+import { z } from 'zod'
+
+const agent = new Agent({
+  url: 'http://localhost:9100',
+  llm: { provider: 'anthropic', apiKey: process.env.ANTHROPIC_API_KEY },
+})
+
+// 1. Navigate
+await agent.nav('https://news.ycombinator.com')
+
+// 2. Extract data
+const { data: stories } = await agent.extract('get the top 5 stories with title, points, and link', {
+  schema: z.array(z.object({
+    title: z.string(),
+    points: z.number(),
+    link: z.string(),
+  })),
+})
+
+// 3. Act on extracted data
+await agent.act(`click on the story titled "${stories[0].title}"`)
+
+// 4. Verify the result
+const { success } = await agent.verify('the story page or external link has loaded')
+
+console.log({ stories, navigationSuccess: success })
+```
+
 ## API Reference
 
 ### `new Agent(options)`
@@ -105,8 +149,6 @@ const { success, reason } = await agent.verify('the form was submitted successfu
 
 ## LLM Providers
 
-Supported providers:
-
 | Provider | Config |
 |----------|--------|
 | OpenAI | `{ provider: 'openai', apiKey: '...' }` |
@@ -121,11 +163,11 @@ Supported providers:
 
 ## Progress Events
 
-Track agent operations:
+Track agent operations in real time:
 
 ```typescript
 const agent = new Agent({
-  url: 'http://localhost:3000',
+  url: 'http://localhost:9100',
   onProgress: (event) => {
     console.log(`[${event.type}] ${event.message}`)
   },
@@ -154,6 +196,13 @@ try {
 }
 ```
 
+## Links
+
+- [Documentation](https://docs.browseros.com)
+- [GitHub](https://github.com/browseros-ai/BrowserOS)
+- [Changelog](./CHANGELOG.md)
+- [Discord](https://discord.gg/YKwjt5vuKr)
+
 ## License
 
-AGPL-3.0-or-later
+[AGPL-3.0-or-later](../../../../LICENSE)

packages/browseros-agent/packages/cdp-protocol/README.md

@@ -0,0 +1,67 @@
+# @browseros/cdp-protocol
+
+Type-safe Chrome DevTools Protocol bindings for BrowserOS.
+
+> **Internal package** — auto-generated TypeScript types and API wrappers for all CDP domains. Used by `@browseros/server` to communicate with Chromium.
+
+## Usage
+
+Import domain types or domain API wrappers using subpath exports:
+
+```typescript
+// Import type definitions for a CDP domain
+import type { NavigateParams, NavigateReturn } from '@browseros/cdp-protocol/domains/page'
+
+// Import the API wrapper for a domain
+import { PageAPI } from '@browseros/cdp-protocol/domain-apis/page'
+
+// Core protocol API
+import { ProtocolAPI } from '@browseros/cdp-protocol/protocol-api'
+
+// Factory function
+import { createAPI } from '@browseros/cdp-protocol/create-api'
+```
+
+## Supported Domains
+
+All standard Chrome DevTools Protocol domains are supported:
+
+| Category | Domains |
+|----------|---------|
+| **Page & DOM** | Page, DOM, DOMDebugger, DOMSnapshot, DOMStorage, CSS, Overlay |
+| **Network** | Network, Fetch, IO, ServiceWorker, CacheStorage |
+| **Input & Interaction** | Input, Emulation, DeviceOrientation, DeviceAccess |
+| **JavaScript** | Runtime, Debugger, Console, Profiler, HeapProfiler |
+| **Browser** | Browser, Target, Inspector, Extensions, PWA |
+| **Performance** | Performance, PerformanceTimeline, Tracing, Memory |
+| **Media** | Media, WebAudio, Cast |
+| **Security** | Security, WebAuthn, FedCm |
+| **Storage** | IndexedDB, Storage, FileSystem |
+| **Other** | Accessibility, Animation, Audits, Autofill, BackgroundService, BluetoothEmulation, EventBreakpoints, HeadlessExperimental, LayerTree, Log, Preload, Schema, SystemInfo, Tethering |
+| **BrowserOS Custom** | Bookmarks, History |
+
+## Structure
+
+```
+src/generated/
+├── domains/            # Type definitions for each CDP domain
+│   ├── page.ts
+│   ├── dom.ts
+│   ├── network.ts
+│   └── ...
+├── domain-apis/        # API wrapper classes for each domain
+│   ├── page.ts
+│   ├── dom.ts
+│   ├── network.ts
+│   └── ...
+├── protocol-api.ts     # Unified protocol API
+└── create-api.ts       # API factory
+```
+
+## Regenerating Types
+
+Types are auto-generated from the CDP protocol specification. The generated output lives in `src/generated/` and should not be edited manually.
+
+## License
+
+[AGPL-3.0-or-later](../../../../LICENSE)

packages/browseros-agent/scripts/build/cli.ts

@@ -0,0 +1,9 @@
+#!/usr/bin/env bun
+
+import { runCliInstallerUpload } from './cli/upload'
+
+runCliInstallerUpload().catch((error) => {
+  const message = error instanceof Error ? error.message : String(error)
+  console.error(`\n✗ ${message}\n`)
+  process.exit(1)
+})

packages/browseros-agent/scripts/build/cli/config.ts

@@ -0,0 +1,52 @@
+import { existsSync, readFileSync } from 'node:fs'
+import { join } from 'node:path'
+
+import { parse } from 'dotenv'
+
+import type { R2Config } from '../server/types'
+
+const PROD_ENV_PATH = join('apps', 'cli', '.env.production')
+const PROD_ENV_TEMPLATE_PATH = join('apps', 'cli', '.env.production.example')
+
+function pickEnv(name: string, fileEnv: Record<string, string>): string {
+  const value = process.env[name] ?? fileEnv[name]
+  if (!value || value.trim().length === 0) {
+    throw new Error(`Missing required environment variable: ${name}`)
+  }
+  return value
+}
+
+function loadProdEnv(rootDir: string): Record<string, string> {
+  const prodEnvPath = join(rootDir, PROD_ENV_PATH)
+  if (!existsSync(prodEnvPath)) {
+    const templatePath = join(rootDir, PROD_ENV_TEMPLATE_PATH)
+    if (existsSync(templatePath)) {
+      throw new Error(
+        `Missing ${PROD_ENV_PATH}. Create it from ${PROD_ENV_TEMPLATE_PATH} before running upload:cli-installers.`,
+      )
+    }
+    throw new Error(
+      `Missing ${PROD_ENV_PATH}. The template file ${PROD_ENV_TEMPLATE_PATH} was not found.`,
+    )
+  }
+  return parse(readFileSync(prodEnvPath, 'utf-8'))
+}
+
+export interface CliUploadConfig {
+  r2: R2Config
+}
+
+export function loadCliUploadConfig(rootDir: string): CliUploadConfig {
+  const fileEnv = loadProdEnv(rootDir)
+  return {
+    r2: {
+      accountId: pickEnv('R2_ACCOUNT_ID', fileEnv),
+      accessKeyId: pickEnv('R2_ACCESS_KEY_ID', fileEnv),
+      secretAccessKey: pickEnv('R2_SECRET_ACCESS_KEY', fileEnv),
+      bucket: pickEnv('R2_BUCKET', fileEnv),
+      downloadPrefix: '',
+      uploadPrefix:
+        process.env.R2_UPLOAD_PREFIX ?? fileEnv.R2_UPLOAD_PREFIX ?? 'cli',
+    },
+  }
+}

packages/browseros-agent/scripts/build/cli/upload.ts

@@ -0,0 +1,56 @@
+import { existsSync } from 'node:fs'
+import { dirname, join, resolve } from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+import { log } from '../log'
+import { createR2Client, joinObjectKey, uploadFileToObject } from '../server/r2'
+import { loadCliUploadConfig } from './config'
+
+const CDN_BASE_URL = 'https://cdn.browseros.com'
+
+const INSTALLERS = [
+  {
+    filePath: join('apps', 'cli', 'scripts', 'install.sh'),
+    objectName: 'install.sh',
+    contentType: 'text/x-shellscript; charset=utf-8',
+  },
+  {
+    filePath: join('apps', 'cli', 'scripts', 'install.ps1'),
+    objectName: 'install.ps1',
+    contentType: 'text/plain; charset=utf-8',
+  },
+] as const
+
+export async function runCliInstallerUpload(): Promise<void> {
+  const rootDir = resolve(dirname(fileURLToPath(import.meta.url)), '../../..')
+  process.chdir(rootDir)
+  await uploadCliInstallers(rootDir)
+}
+
+export async function uploadCliInstallers(rootDir: string): Promise<void> {
+  const { r2 } = loadCliUploadConfig(rootDir)
+  const client = createR2Client(r2)
+
+  log.header('Uploading BrowserOS CLI installer scripts')
+
+  try {
+    for (const installer of INSTALLERS) {
+      const absolutePath = join(rootDir, installer.filePath)
+      if (!existsSync(absolutePath)) {
+        throw new Error(`Installer script not found: ${installer.filePath}`)
+      }
+
+      const objectKey = joinObjectKey(r2.uploadPrefix, installer.objectName)
+      log.step(`Uploading ${installer.filePath}`)
+      await uploadFileToObject(client, r2, objectKey, absolutePath, {
+        contentType: installer.contentType,
+      })
+      log.success(`Uploaded ${objectKey}`)
+      log.info(`${CDN_BASE_URL}/${objectKey}`)
+    }
+
+    log.done('CLI installer upload completed')
+  } finally {
+    client.destroy()
+  }
+}

packages/browseros-agent/scripts/build/server/r2.ts

@@ -10,6 +10,10 @@ import {
 
 import type { R2Config } from './types'
 
+export interface UploadFileOptions {
+  contentType?: string
+}
+
 function createClientConfig(r2: R2Config): S3ClientConfig {
   return {
     region: 'auto',
@@ -81,6 +85,7 @@ export async function uploadFileToObject(
   r2: R2Config,
   key: string,
   filePath: string,
+  options: UploadFileOptions = {},
 ): Promise<void> {
   const data = await readFile(filePath)
   await client.send(
@@ -88,7 +93,7 @@ export async function uploadFileToObject(
       Bucket: r2.bucket,
       Key: key,
       Body: data,
-      ContentType: 'application/zip',
+      ContentType: options.contentType ?? 'application/zip',
     }),
   )
 }

packages/browseros/README.md

@@ -0,0 +1,133 @@
+# BrowserOS Browser (Chromium Fork)
+
+Custom Chromium build with AI agent integration, enhanced privacy patches, and native MCP support.
+
+> Based on **Chromium 146.0.7680.31** · Built with Python 3.12+ · Licensed under [AGPL-3.0](../../LICENSE)
+
+## What This Is
+
+This package contains the BrowserOS browser build system — everything needed to fetch Chromium source, apply BrowserOS patches, and produce signed binaries for macOS, Windows, and Linux. The build system is a Python CLI that orchestrates the entire pipeline from source to distributable.
+
+BrowserOS patches add:
+- Native AI agent sidebar and new tab integration
+- MCP server endpoints baked into the browser
+- Enhanced privacy via [ungoogled-chromium](https://github.com/ungoogled-software/ungoogled-chromium) patches
+- Custom branding, icons, and entitlements
+- Keychain access group management (macOS)
+- Sparkle auto-update framework (macOS)
+
+## Prerequisites
+
+| Requirement | Details |
+|-------------|---------|
+| **Disk space** | ~100 GB for Chromium source + build artifacts |
+| **Python** | 3.12+ |
+| **macOS** | Xcode + Command Line Tools |
+| **Linux** | `build-essential`, `clang`, `lld`, and Chromium's [Linux deps](https://chromium.googlesource.com/chromium/src/+/main/docs/linux/build_instructions.md) |
+| **Windows** | Visual Studio 2022, Windows SDK |
+
+## Directory Structure
+
+```
+packages/browseros/
+├── build/                   # Build system (Python CLI)
+│   ├── __main__.py          # CLI entry point
+│   ├── browseros.py         # Main app definition
+│   ├── modules/
+│   │   ├── setup/           # Chromium source fetch and setup
+│   │   ├── patches/         # Patch application logic
+│   │   ├── apply/           # Apply patches to source tree
+│   │   ├── extract/         # Extract patches from modified source
+│   │   ├── feature/         # Feature flag management
+│   │   ├── package/         # Binary packaging
+│   │   ├── sign/            # Code signing (macOS, Windows)
+│   │   ├── ota/             # Over-the-air update support
+│   │   └── resources/       # Resource management
+│   ├── config/              # Build configuration
+│   └── features.yaml        # Feature flag definitions
+│
+├── chromium_patches/        # BrowserOS patches applied to Chromium source
+│   ├── chrome/browser/      # Browser UI and feature patches
+│   ├── components/          # Component patches (e.g., os_crypt)
+│   └── ...                  # Organized to mirror Chromium source tree
+│
+├── chromium_files/          # New files added to Chromium (not patches)
+├── series_patches/          # Ordered patch series
+├── resources/               # Icons, entitlements, signing resources
+│   └── entitlements/        # macOS entitlements (app, helper, GPU, etc.)
+│
+├── tools/
+│   └── bdev                 # Developer tool
+│
+├── CHROMIUM_VERSION          # Pinned Chromium version (MAJOR.MINOR.BUILD.PATCH)
+├── BASE_COMMIT              # Base Chromium commit hash
+├── pyproject.toml           # Python project config
+└── requirements.txt         # Python dependencies
+```
+
+## Build System
+
+The `browseros` CLI manages the full build lifecycle:
+
+```bash
+# Install the build system
+pip install -e .
+
+# Or use uv
+uv pip install -e .
+```
+
+Key commands:
+
+```bash
+browseros setup          # Fetch and prepare Chromium source
+browseros apply          # Apply all patches to Chromium source
+browseros build          # Build BrowserOS binary
+browseros package        # Package into distributable (DMG, installer, AppImage)
+browseros sign           # Code sign the binary (macOS/Windows)
+```
+
+## Patch System
+
+BrowserOS applies patches on top of vanilla Chromium. Patches are organized in two directories:
+
+- **`chromium_patches/`** — Individual file patches, organized to mirror the Chromium source tree. Each file here replaces or modifies the corresponding file in Chromium.
+- **`series_patches/`** — Ordered patch series applied sequentially.
+
+### Adding a New Patch
+
+1. Make your changes in the Chromium source tree
+2. Use `browseros extract` to pull changes back into patch format
+3. Place the patch in the appropriate directory mirroring Chromium's structure
+4. Test with a full `browseros apply && browseros build` cycle
+
+### Chromium Version Pinning
+
+The exact Chromium version is pinned in `CHROMIUM_VERSION`:
+
+```
+MAJOR=146
+MINOR=0
+BUILD=7680
+PATCH=31
+```
+
+To update the base Chromium version, update this file and `BASE_COMMIT`, then resolve any patch conflicts.
+
+## Signing (macOS)
+
+macOS builds require code signing for Keychain access, Gatekeeper, and notarization:
+
+- Entitlements are in `resources/entitlements/` (app, helper, GPU, renderer, etc.)
+- Designated requirements pin to Team ID for Keychain persistence across updates
+- The signing module is at `build/modules/sign/macos.py`
+
+## Feature Flags
+
+Feature flags are defined in `features.yaml` and control which BrowserOS-specific features are compiled into the build. The feature module (`build/modules/feature/`) manages flag resolution at build time.
+
+## Related Resources
+
+- [Chromium Build Instructions](https://chromium.googlesource.com/chromium/src/+/main/docs/linux/build_instructions.md)
+- [ungoogled-chromium](https://github.com/ungoogled-software/ungoogled-chromium) — upstream privacy patches
+- [BrowserOS Agent Platform](../browseros-agent/) — the TypeScript/Go agent system that runs inside the browser