@quantumclaw/quantumclaw 2026.3.22

package/docs/tools/agent-send.md

@@ -0,0 +1,100 @@
+---
+summary: "Run agent turns from the CLI and optionally deliver replies to channels"
+read_when:
+  - You want to trigger agent runs from scripts or the command line
+  - You need to deliver agent replies to a chat channel programmatically
+title: "Agent Send"
+---
+
+# Agent Send
+
+`quantumclaw agent` runs a single agent turn from the command line without needing
+an inbound chat message. Use it for scripted workflows, testing, and
+programmatic delivery.
+
+## Quick start
+
+<Steps>
+  <Step title="Run a simple agent turn">
+    ```bash
+    quantumclaw agent --message "What is the weather today?"
+    ```
+
+    This sends the message through the Gateway and prints the reply.
+
+  </Step>
+
+  <Step title="Target a specific agent or session">
+    ```bash
+    # Target a specific agent
+    quantumclaw agent --agent ops --message "Summarize logs"
+
+    # Target a phone number (derives session key)
+    quantumclaw agent --to +15555550123 --message "Status update"
+
+    # Reuse an existing session
+    quantumclaw agent --session-id abc123 --message "Continue the task"
+    ```
+
+  </Step>
+
+  <Step title="Deliver the reply to a channel">
+    ```bash
+    # Deliver to WhatsApp (default channel)
+    quantumclaw agent --to +15555550123 --message "Report ready" --deliver
+
+    # Deliver to Slack
+    quantumclaw agent --agent ops --message "Generate report" \
+      --deliver --reply-channel slack --reply-to "#reports"
+    ```
+
+  </Step>
+</Steps>
+
+## Flags
+
+| Flag                          | Description                                                 |
+| ----------------------------- | ----------------------------------------------------------- |
+| `--message \<text\>`          | Message to send (required)                                  |
+| `--to \<dest\>`               | Derive session key from a target (phone, chat id)           |
+| `--agent \<id\>`              | Target a configured agent (uses its `main` session)         |
+| `--session-id \<id\>`         | Reuse an existing session by id                             |
+| `--local`                     | Force local embedded runtime (skip Gateway)                 |
+| `--deliver`                   | Send the reply to a chat channel                            |
+| `--channel \<name\>`          | Delivery channel (whatsapp, telegram, discord, slack, etc.) |
+| `--reply-to \<target\>`       | Delivery target override                                    |
+| `--reply-channel \<name\>`    | Delivery channel override                                   |
+| `--reply-account \<id\>`      | Delivery account id override                                |
+| `--thinking \<level\>`        | Set thinking level (off, minimal, low, medium, high, xhigh) |
+| `--verbose \<on\|full\|off\>` | Set verbose level                                           |
+| `--timeout \<seconds\>`       | Override agent timeout                                      |
+| `--json`                      | Output structured JSON                                      |
+
+## Behavior
+
+- By default, the CLI goes **through the Gateway**. Add `--local` to force the
+  embedded runtime on the current machine.
+- If the Gateway is unreachable, the CLI **falls back** to the local embedded run.
+- Session selection: `--to` derives the session key (group/channel targets
+  preserve isolation; direct chats collapse to `main`).
+- Thinking and verbose flags persist into the session store.
+- Output: plain text by default, or `--json` for structured payload + metadata.
+
+## Examples
+
+```bash
+# Simple turn with JSON output
+quantumclaw agent --to +15555550123 --message "Trace logs" --verbose on --json
+
+# Turn with thinking level
+quantumclaw agent --session-id 1234 --message "Summarize inbox" --thinking medium
+
+# Deliver to a different channel than the session
+quantumclaw agent --agent ops --message "Alert" --deliver --reply-channel telegram --reply-to "@admin"
+```
+
+## Related
+
+- [Agent CLI reference](/cli/agent)
+- [Sub-agents](/tools/subagents) — background sub-agent spawning
+- [Sessions](/concepts/session) — how session keys work

package/docs/tools/apply-patch.md

@@ -0,0 +1,51 @@
+---
+summary: "Apply multi-file patches with the apply_patch tool"
+read_when:
+  - You need structured file edits across multiple files
+  - You want to document or debug patch-based edits
+title: "apply_patch Tool"
+---
+
+# apply_patch tool
+
+Apply file changes using a structured patch format. This is ideal for multi-file
+or multi-hunk edits where a single `edit` call would be brittle.
+
+The tool accepts a single `input` string that wraps one or more file operations:
+
+```
+*** Begin Patch
+*** Add File: path/to/file.txt
++line 1
++line 2
+*** Update File: src/app.ts
+@@
+-old line
++new line
+*** Delete File: obsolete.txt
+*** End Patch
+```
+
+## Parameters
+
+- `input` (required): Full patch contents including `*** Begin Patch` and `*** End Patch`.
+
+## Notes
+
+- Patch paths support relative paths (from the workspace directory) and absolute paths.
+- `tools.exec.applyPatch.workspaceOnly` defaults to `true` (workspace-contained). Set it to `false` only if you intentionally want `apply_patch` to write/delete outside the workspace directory.
+- Use `*** Move to:` within an `*** Update File:` hunk to rename files.
+- `*** End of File` marks an EOF-only insert when needed.
+- Experimental and disabled by default. Enable with `tools.exec.applyPatch.enabled`.
+- OpenAI-only (including OpenAI Codex). Optionally gate by model via
+  `tools.exec.applyPatch.allowModels`.
+- Config is only under `tools.exec`.
+
+## Example
+
+```json
+{
+  "tool": "apply_patch",
+  "input": "*** Begin Patch\n*** Update File: src/index.ts\n@@\n-const foo = 1\n+const foo = 2\n*** End Patch"
+}
+```

package/docs/tools/brave-search.md

@@ -0,0 +1,93 @@
+---
+summary: "Brave Search API setup for web_search"
+read_when:
+  - You want to use Brave Search for web_search
+  - You need a BRAVE_API_KEY or plan details
+title: "Brave Search"
+---
+
+# Brave Search API
+
+QuantumClaw supports Brave Search API as a `web_search` provider.
+
+## Get an API key
+
+1. Create a Brave Search API account at [https://brave.com/search/api/](https://brave.com/search/api/)
+2. In the dashboard, choose the **Search** plan and generate an API key.
+3. Store the key in config or set `BRAVE_API_KEY` in the Gateway environment.
+
+## Config example
+
+```json5
+{
+  plugins: {
+    entries: {
+      brave: {
+        config: {
+          webSearch: {
+            apiKey: "BRAVE_API_KEY_HERE",
+          },
+        },
+      },
+    },
+  },
+  tools: {
+    web: {
+      search: {
+        provider: "brave",
+        maxResults: 5,
+        timeoutSeconds: 30,
+      },
+    },
+  },
+}
+```
+
+Provider-specific Brave search settings now live under `plugins.entries.brave.config.webSearch.*`.
+Legacy `tools.web.search.apiKey` still loads through the compatibility shim, but it is no longer the canonical config path.
+
+## Tool parameters
+
+| Parameter     | Description                                                         |
+| ------------- | ------------------------------------------------------------------- |
+| `query`       | Search query (required)                                             |
+| `count`       | Number of results to return (1-10, default: 5)                      |
+| `country`     | 2-letter ISO country code (e.g., "US", "DE")                        |
+| `language`    | ISO 639-1 language code for search results (e.g., "en", "de", "fr") |
+| `ui_lang`     | ISO language code for UI elements                                   |
+| `freshness`   | Time filter: `day` (24h), `week`, `month`, or `year`                |
+| `date_after`  | Only results published after this date (YYYY-MM-DD)                 |
+| `date_before` | Only results published before this date (YYYY-MM-DD)                |
+
+**Examples:**
+
+```javascript
+// Country and language-specific search
+await web_search({
+  query: "renewable energy",
+  country: "DE",
+  language: "de",
+});
+
+// Recent results (past week)
+await web_search({
+  query: "AI news",
+  freshness: "week",
+});
+
+// Date range search
+await web_search({
+  query: "AI developments",
+  date_after: "2024-01-01",
+  date_before: "2024-06-30",
+});
+```
+
+## Notes
+
+- QuantumClaw uses the Brave **Search** plan. If you have a legacy subscription (e.g. the original Free plan with 2,000 queries/month), it remains valid but does not include newer features like LLM Context or higher rate limits.
+- Each Brave plan includes **\$5/month in free credit** (renewing). The Search plan costs \$5 per 1,000 requests, so the credit covers 1,000 queries/month. Set your usage limit in the Brave dashboard to avoid unexpected charges. See the [Brave API portal](https://brave.com/search/api/) for current plans.
+- The Search plan includes the LLM Context endpoint and AI inference rights. Storing results to train or tune models requires a plan with explicit storage rights. See the Brave [Terms of Service](https://api-dashboard.search.brave.com/terms-of-service).
+- Results are cached for 15 minutes by default (configurable via `cacheTtlMinutes`).
+
+See [Web tools](/tools/web) for the full web_search configuration.

package/docs/tools/browser-linux-troubleshooting.md

@@ -0,0 +1,138 @@
+---
+summary: "Fix Chrome/Brave/Edge/Chromium CDP startup issues for QuantumClaw browser control on Linux"
+read_when: "Browser control fails on Linux, especially with snap Chromium"
+title: "Browser Troubleshooting"
+---
+
+# Browser Troubleshooting (Linux)
+
+## Problem: "Failed to start Chrome CDP on port 18800"
+
+QuantumClaw's browser control server fails to launch Chrome/Brave/Edge/Chromium with the error:
+
+```
+{"error":"Error: Failed to start Chrome CDP on port 18800 for profile \"quantumclaw\"."}
+```
+
+### Root Cause
+
+On Ubuntu (and many Linux distros), the default Chromium installation is a **snap package**. Snap's AppArmor confinement interferes with how QuantumClaw spawns and monitors the browser process.
+
+The `apt install chromium` command installs a stub package that redirects to snap:
+
+```
+Note, selecting 'chromium-browser' instead of 'chromium'
+chromium-browser is already the newest version (2:1snap1-0ubuntu2).
+```
+
+This is NOT a real browser - it's just a wrapper.
+
+### Solution 1: Install Google Chrome (Recommended)
+
+Install the official Google Chrome `.deb` package, which is not sandboxed by snap:
+
+```bash
+wget https://dl.google.com/linux/direct/google-chrome-stable_current_amd64.deb
+sudo dpkg -i google-chrome-stable_current_amd64.deb
+sudo apt --fix-broken install -y  # if there are dependency errors
+```
+
+Then update your QuantumClaw config (`~/.quantumclaw/quantumclaw.json`):
+
+```json
+{
+  "browser": {
+    "enabled": true,
+    "executablePath": "/usr/bin/google-chrome-stable",
+    "headless": true,
+    "noSandbox": true
+  }
+}
+```
+
+### Solution 2: Use Snap Chromium with Attach-Only Mode
+
+If you must use snap Chromium, configure QuantumClaw to attach to a manually-started browser:
+
+1. Update config:
+
+```json
+{
+  "browser": {
+    "enabled": true,
+    "attachOnly": true,
+    "headless": true,
+    "noSandbox": true
+  }
+}
+```
+
+2. Start Chromium manually:
+
+```bash
+chromium-browser --headless --no-sandbox --disable-gpu \
+  --remote-debugging-port=18800 \
+  --user-data-dir=$HOME/.quantumclaw/browser/quantumclaw/user-data \
+  about:blank &
+```
+
+3. Optionally create a systemd user service to auto-start Chrome:
+
+```ini
+# ~/.config/systemd/user/quantumclaw-browser.service
+[Unit]
+Description=QuantumClaw Browser (Chrome CDP)
+After=network.target
+
+[Service]
+ExecStart=/snap/bin/chromium --headless --no-sandbox --disable-gpu --remote-debugging-port=18800 --user-data-dir=%h/.quantumclaw/browser/quantumclaw/user-data about:blank
+Restart=on-failure
+RestartSec=5
+
+[Install]
+WantedBy=default.target
+```
+
+Enable with: `systemctl --user enable --now quantumclaw-browser.service`
+
+### Verifying the Browser Works
+
+Check status:
+
+```bash
+curl -s http://127.0.0.1:18791/ | jq '{running, pid, chosenBrowser}'
+```
+
+Test browsing:
+
+```bash
+curl -s -X POST http://127.0.0.1:18791/start
+curl -s http://127.0.0.1:18791/tabs
+```
+
+### Config Reference
+
+| Option                   | Description                                                          | Default                                                     |
+| ------------------------ | -------------------------------------------------------------------- | ----------------------------------------------------------- |
+| `browser.enabled`        | Enable browser control                                               | `true`                                                      |
+| `browser.executablePath` | Path to a Chromium-based browser binary (Chrome/Brave/Edge/Chromium) | auto-detected (prefers default browser when Chromium-based) |
+| `browser.headless`       | Run without GUI                                                      | `false`                                                     |
+| `browser.noSandbox`      | Add `--no-sandbox` flag (needed for some Linux setups)               | `false`                                                     |
+| `browser.attachOnly`     | Don't launch browser, only attach to existing                        | `false`                                                     |
+| `browser.cdpPort`        | Chrome DevTools Protocol port                                        | `18800`                                                     |
+
+### Problem: "No Chrome tabs found for profile=\"user\""
+
+You're using an `existing-session` / Chrome MCP profile. QuantumClaw can see local Chrome,
+but there are no open tabs available to attach to.
+
+Fix options:
+
+1. **Use the managed browser:** `quantumclaw browser start --browser-profile quantumclaw`
+   (or set `browser.defaultProfile: "quantumclaw"`).
+2. **Use Chrome MCP:** make sure local Chrome is running with at least one open tab, then retry with `--browser-profile user`.
+
+Notes:
+
+- `user` is host-only. For Linux servers, containers, or remote hosts, prefer CDP profiles.
+- Local `quantumclaw` profiles auto-assign `cdpPort`/`cdpUrl`; only set those for remote CDP.

package/docs/tools/browser-login.md

@@ -0,0 +1,73 @@
+---
+summary: "Manual logins for browser automation + X/Twitter posting"
+read_when:
+  - You need to log into sites for browser automation
+  - You want to post updates to X/Twitter
+title: "Browser Login"
+---
+
+# Browser login + X/Twitter posting
+
+## Manual login (recommended)
+
+When a site requires login, **sign in manually** in the **host** browser profile (the quantumclaw browser).
+
+Do **not** give the model your credentials. Automated logins often trigger anti‑bot defenses and can lock the account.
+
+Back to the main browser docs: [Browser](/tools/browser).
+
+## Which Chrome profile is used?
+
+QuantumClaw controls a **dedicated Chrome profile** (named `quantumclaw`, orange‑tinted UI). This is separate from your daily browser profile.
+
+For agent browser tool calls:
+
+- Default choice: the agent should use its isolated `quantumclaw` browser.
+- Use `profile="user"` only when existing logged-in sessions matter and the user is at the computer to click/approve any attach prompt.
+- If you have multiple user-browser profiles, specify the profile explicitly instead of guessing.
+
+Two easy ways to access it:
+
+1. **Ask the agent to open the browser** and then log in yourself.
+2. **Open it via CLI**:
+
+```bash
+quantumclaw browser start
+quantumclaw browser open https://x.com
+```
+
+If you have multiple profiles, pass `--browser-profile <name>` (the default is `quantumclaw`).
+
+## X/Twitter: recommended flow
+
+- **Read/search/threads:** use the **host** browser (manual login).
+- **Post updates:** use the **host** browser (manual login).
+
+## Sandboxing + host browser access
+
+Sandboxed browser sessions are **more likely** to trigger bot detection. For X/Twitter (and other strict sites), prefer the **host** browser.
+
+If the agent is sandboxed, the browser tool defaults to the sandbox. To allow host control:
+
+```json5
+{
+  agents: {
+    defaults: {
+      sandbox: {
+        mode: "non-main",
+        browser: {
+          allowHostControl: true,
+        },
+      },
+    },
+  },
+}
+```
+
+Then target the host browser:
+
+```bash
+quantumclaw browser open https://x.com --browser-profile quantumclaw --target host
+```
+
+Or disable sandboxing for the agent that posts updates.

package/docs/tools/browser-wsl2-windows-remote-cdp-troubleshooting.md

@@ -0,0 +1,211 @@
+---
+summary: "Troubleshoot WSL2 Gateway + Windows Chrome remote CDP in layers"
+read_when:
+  - Running QuantumClaw Gateway in WSL2 while Chrome lives on Windows
+  - Seeing overlapping browser/control-ui errors across WSL2 and Windows
+  - Deciding between host-local Chrome MCP and raw remote CDP in split-host setups
+title: "WSL2 + Windows + remote Chrome CDP troubleshooting"
+---
+
+# WSL2 + Windows + remote Chrome CDP troubleshooting
+
+This guide covers the common split-host setup where:
+
+- QuantumClaw Gateway runs inside WSL2
+- Chrome runs on Windows
+- browser control must cross the WSL2/Windows boundary
+
+It also covers the layered failure pattern from [issue #39369](https://github.com/quantumclaw/quantumclaw/issues/39369): several independent problems can show up at once, which makes the wrong layer look broken first.
+
+## Choose the right browser mode first
+
+You have two valid patterns:
+
+### Option 1: Raw remote CDP from WSL2 to Windows
+
+Use a remote browser profile that points from WSL2 to a Windows Chrome CDP endpoint.
+
+Choose this when:
+
+- the Gateway stays inside WSL2
+- Chrome runs on Windows
+- you need browser control to cross the WSL2/Windows boundary
+
+### Option 2: Host-local Chrome MCP
+
+Use `existing-session` / `user` only when the Gateway itself runs on the same host as Chrome.
+
+Choose this when:
+
+- QuantumClaw and Chrome are on the same machine
+- you want the local signed-in browser state
+- you do not need cross-host browser transport
+
+For WSL2 Gateway + Windows Chrome, prefer raw remote CDP. Chrome MCP is host-local, not a WSL2-to-Windows bridge.
+
+## Working architecture
+
+Reference shape:
+
+- WSL2 runs the Gateway on `127.0.0.1:18789`
+- Windows opens the Control UI in a normal browser at `http://127.0.0.1:18789/`
+- Windows Chrome exposes a CDP endpoint on port `9222`
+- WSL2 can reach that Windows CDP endpoint
+- QuantumClaw points a browser profile at the address that is reachable from WSL2
+
+## Why this setup is confusing
+
+Several failures can overlap:
+
+- WSL2 cannot reach the Windows CDP endpoint
+- the Control UI is opened from a non-secure origin
+- `gateway.controlUi.allowedOrigins` does not match the page origin
+- token or pairing is missing
+- the browser profile points at the wrong address
+
+Because of that, fixing one layer can still leave a different error visible.
+
+## Critical rule for the Control UI
+
+When the UI is opened from Windows, use Windows localhost unless you have a deliberate HTTPS setup.
+
+Use:
+
+`http://127.0.0.1:18789/`
+
+Do not default to a LAN IP for the Control UI. Plain HTTP on a LAN or tailnet address can trigger insecure-origin/device-auth behavior that is unrelated to CDP itself. See [Control UI](/web/control-ui).
+
+## Validate in layers
+
+Work top to bottom. Do not skip ahead.
+
+### Layer 1: Verify Chrome is serving CDP on Windows
+
+Start Chrome on Windows with remote debugging enabled:
+
+```powershell
+chrome.exe --remote-debugging-port=9222
+```
+
+From Windows, verify Chrome itself first:
+
+```powershell
+curl http://127.0.0.1:9222/json/version
+curl http://127.0.0.1:9222/json/list
+```
+
+If this fails on Windows, QuantumClaw is not the problem yet.
+
+### Layer 2: Verify WSL2 can reach that Windows endpoint
+
+From WSL2, test the exact address you plan to use in `cdpUrl`:
+
+```bash
+curl http://WINDOWS_HOST_OR_IP:9222/json/version
+curl http://WINDOWS_HOST_OR_IP:9222/json/list
+```
+
+Good result:
+
+- `/json/version` returns JSON with Browser / Protocol-Version metadata
+- `/json/list` returns JSON (empty array is fine if no pages are open)
+
+If this fails:
+
+- Windows is not exposing the port to WSL2 yet
+- the address is wrong for the WSL2 side
+- firewall / port forwarding / local proxying is still missing
+
+Fix that before touching QuantumClaw config.
+
+### Layer 3: Configure the correct browser profile
+
+For raw remote CDP, point QuantumClaw at the address that is reachable from WSL2:
+
+```json5
+{
+  browser: {
+    enabled: true,
+    defaultProfile: "remote",
+    profiles: {
+      remote: {
+        cdpUrl: "http://WINDOWS_HOST_OR_IP:9222",
+        attachOnly: true,
+        color: "#00AA00",
+      },
+    },
+  },
+}
+```
+
+Notes:
+
+- use the WSL2-reachable address, not whatever only works on Windows
+- keep `attachOnly: true` for externally managed browsers
+- test the same URL with `curl` before expecting QuantumClaw to succeed
+
+### Layer 4: Verify the Control UI layer separately
+
+Open the UI from Windows:
+
+`http://127.0.0.1:18789/`
+
+Then verify:
+
+- the page origin matches what `gateway.controlUi.allowedOrigins` expects
+- token auth or pairing is configured correctly
+- you are not debugging a Control UI auth problem as if it were a browser problem
+
+Helpful page:
+
+- [Control UI](/web/control-ui)
+
+### Layer 5: Verify end-to-end browser control
+
+From WSL2:
+
+```bash
+quantumclaw browser open https://example.com --browser-profile remote
+quantumclaw browser tabs --browser-profile remote
+```
+
+Good result:
+
+- the tab opens in Windows Chrome
+- `quantumclaw browser tabs` returns the target
+- later actions (`snapshot`, `screenshot`, `navigate`) work from the same profile
+
+## Common misleading errors
+
+Treat each message as a layer-specific clue:
+
+- `control-ui-insecure-auth`
+  - UI origin / secure-context problem, not a CDP transport problem
+- `token_missing`
+  - auth configuration problem
+- `pairing required`
+  - device approval problem
+- `Remote CDP for profile "remote" is not reachable`
+  - WSL2 cannot reach the configured `cdpUrl`
+- `gateway timeout after 1500ms`
+  - often still CDP reachability or a slow/unreachable remote endpoint
+- `No Chrome tabs found for profile="user"`
+  - local Chrome MCP profile selected where no host-local tabs are available
+
+## Fast triage checklist
+
+1. Windows: does `curl http://127.0.0.1:9222/json/version` work?
+2. WSL2: does `curl http://WINDOWS_HOST_OR_IP:9222/json/version` work?
+3. QuantumClaw config: does `browser.profiles.<name>.cdpUrl` use that exact WSL2-reachable address?
+4. Control UI: are you opening `http://127.0.0.1:18789/` instead of a LAN IP?
+5. Are you trying to use `existing-session` across WSL2 and Windows instead of raw remote CDP?
+
+## Practical takeaway
+
+The setup is usually viable. The hard part is that browser transport, Control UI origin security, and token/pairing can each fail independently while looking similar from the user side.
+
+When in doubt:
+
+- verify the Windows Chrome endpoint locally first
+- verify the same endpoint from WSL2 second
+- only then debug QuantumClaw config or Control UI auth