From a0cd295c0fe7fac0e982c6ba39a47215b811e1d9 Mon Sep 17 00:00:00 2001
From: Peter Steinberger <steipete@gmail.com>
Date: Wed, 21 Jan 2026 03:02:15 +0000
Subject: [PATCH] fix: add browser snapshot default mode (#1336)

Co-authored-by: Seb Slight <sbarrios93@gmail.com>
---
 CHANGELOG.md                          |  1 +
 docs/gateway/configuration.md         |  3 ++
 docs/tools/browser.md                 |  1 +
 src/agents/tools/browser-tool.test.ts | 44 ++++++++++++---
 src/agents/tools/browser-tool.ts      |  8 ++-
 src/cli/browser-cli-inspect.test.ts   | 78 +++++++++++++++++++++++++++
 src/cli/browser-cli-inspect.ts        |  7 ++-
 src/config/schema.ts                  |  2 +
 src/config/types.browser.ts           |  6 +++
 src/config/zod-schema.ts              |  8 +++
 10 files changed, 149 insertions(+), 9 deletions(-)
 create mode 100644 src/cli/browser-cli-inspect.test.ts

diff --git a/CHANGELOG.md b/CHANGELOG.md
index b9fcd520e..1fd00edb2 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -9,6 +9,7 @@ Docs: https://docs.clawd.bot
 - Repo: remove the Peekaboo git submodule now that the SPM release is used.
 - Update: sync plugin sources on channel switches and update npm-installed plugins during `clawdbot update`.
 - Plugins: share npm plugin update logic between `clawdbot update` and `clawdbot plugins update`.
+- Browser: allow config defaults for efficient snapshots in the tool/CLI. (#1336) — thanks @sebslight.
 - Channels: add the Nostr plugin channel with profile management + onboarding install defaults. (#1323) — thanks @joelklabo.
 - Plugins: require manifest-embedded config schemas, validate configs without loading plugin code, and surface plugin config warnings. (#1272) — thanks @thewilloftheshadow.
 - Plugins: move channel catalog metadata into plugin manifests; align Nextcloud Talk policy helpers with core patterns. (#1290) — thanks @NicholaiVogel.
diff --git a/docs/gateway/configuration.md b/docs/gateway/configuration.md
index e26637029..8ebcef47a 100644
--- a/docs/gateway/configuration.md
+++ b/docs/gateway/configuration.md
@@ -2615,10 +2615,13 @@ Defaults:
     // noSandbox: false,
     // executablePath: "/Applications/Brave Browser.app/Contents/MacOS/Brave Browser",
     // attachOnly: false, // set true when tunneling a remote CDP to localhost
+    // snapshotDefaults: { mode: "efficient" }, // tool/CLI default snapshot preset
   }
 }
 ```
 
+Note: `browser.snapshotDefaults` only affects Clawdbot's browser tool + CLI. Direct HTTP clients must pass `mode` explicitly.
+
 ### `ui` (Appearance)
 
 Optional accent color used by the native apps for UI chrome (e.g. Talk Mode bubble tint).
diff --git a/docs/tools/browser.md b/docs/tools/browser.md
index 793b75a75..a897b7412 100644
--- a/docs/tools/browser.md
+++ b/docs/tools/browser.md
@@ -500,6 +500,7 @@ Notes:
   - `--format ai` (default when Playwright is installed): returns an AI snapshot with numeric refs (`aria-ref="<n>"`).
   - `--format aria`: returns the accessibility tree (no refs; inspection only).
   - `--efficient` (or `--mode efficient`): compact role snapshot preset (interactive + compact + depth + lower maxChars).
+  - Config default (tool/CLI only): set `browser.snapshotDefaults.mode: "efficient"` to use efficient snapshots when the caller does not pass a mode (see [Gateway configuration](/gateway/configuration#browser-clawd-managed-browser)).
   - Role snapshot options (`--interactive`, `--compact`, `--depth`, `--selector`) force a role-based snapshot with refs like `ref=e12`.
   - `--frame "<iframe selector>"` scopes role snapshots to an iframe (pairs with role refs like `e12`).
   - `--interactive` outputs a flat, easy-to-pick list of interactive elements (best for driving actions).
diff --git a/src/agents/tools/browser-tool.test.ts b/src/agents/tools/browser-tool.test.ts
index eaac9561a..286589fcd 100644
--- a/src/agents/tools/browser-tool.test.ts
+++ b/src/agents/tools/browser-tool.test.ts
@@ -49,9 +49,10 @@ const browserConfigMocks = vi.hoisted(() => ({
 }));
 vi.mock("../../browser/config.js", () => browserConfigMocks);
 
-vi.mock("../../config/config.js", () => ({
+const configMocks = vi.hoisted(() => ({
   loadConfig: vi.fn(() => ({ browser: {} })),
 }));
+vi.mock("../../config/config.js", () => configMocks);
 
 const toolCommonMocks = vi.hoisted(() => ({
   imageResultFromFile: vi.fn(),
@@ -70,11 +71,12 @@ import { createBrowserTool } from "./browser-tool.js";
 describe("browser tool snapshot maxChars", () => {
   afterEach(() => {
     vi.clearAllMocks();
+    configMocks.loadConfig.mockReturnValue({ browser: {} });
   });
 
   it("applies the default ai snapshot limit", async () => {
     const tool = createBrowserTool();
-    await tool.execute?.(null, { action: "snapshot", format: "ai" });
+    await tool.execute?.(null, { action: "snapshot", snapshotFormat: "ai" });
 
     expect(browserClientMocks.browserSnapshot).toHaveBeenCalledWith(
       "http://127.0.0.1:18791",
@@ -90,7 +92,7 @@ describe("browser tool snapshot maxChars", () => {
     const override = 2_000;
     await tool.execute?.(null, {
       action: "snapshot",
-      format: "ai",
+      snapshotFormat: "ai",
       maxChars: override,
     });
 
@@ -106,7 +108,7 @@ describe("browser tool snapshot maxChars", () => {
     const tool = createBrowserTool();
     await tool.execute?.(null, {
       action: "snapshot",
-      format: "ai",
+      snapshotFormat: "ai",
       maxChars: 0,
     });
 
@@ -124,7 +126,7 @@ describe("browser tool snapshot maxChars", () => {
 
   it("passes refs mode through to browser snapshot", async () => {
     const tool = createBrowserTool();
-    await tool.execute?.(null, { action: "snapshot", format: "ai", refs: "aria" });
+    await tool.execute?.(null, { action: "snapshot", snapshotFormat: "ai", refs: "aria" });
 
     expect(browserClientMocks.browserSnapshot).toHaveBeenCalledWith(
       "http://127.0.0.1:18791",
@@ -135,9 +137,36 @@ describe("browser tool snapshot maxChars", () => {
     );
   });
 
+  it("uses config snapshot defaults when mode is not provided", async () => {
+    configMocks.loadConfig.mockReturnValue({
+      browser: { snapshotDefaults: { mode: "efficient" } },
+    });
+    const tool = createBrowserTool();
+    await tool.execute?.(null, { action: "snapshot", snapshotFormat: "ai" });
+
+    expect(browserClientMocks.browserSnapshot).toHaveBeenCalledWith(
+      "http://127.0.0.1:18791",
+      expect.objectContaining({
+        mode: "efficient",
+      }),
+    );
+  });
+
+  it("does not apply config snapshot defaults to aria snapshots", async () => {
+    configMocks.loadConfig.mockReturnValue({
+      browser: { snapshotDefaults: { mode: "efficient" } },
+    });
+    const tool = createBrowserTool();
+    await tool.execute?.(null, { action: "snapshot", snapshotFormat: "aria" });
+
+    expect(browserClientMocks.browserSnapshot).toHaveBeenCalled();
+    const [, opts] = browserClientMocks.browserSnapshot.mock.calls.at(-1) ?? [];
+    expect(opts?.mode).toBeUndefined();
+  });
+
   it("defaults to host when using profile=chrome (even in sandboxed sessions)", async () => {
     const tool = createBrowserTool({ defaultControlUrl: "http://127.0.0.1:9999" });
-    await tool.execute?.(null, { action: "snapshot", profile: "chrome", format: "ai" });
+    await tool.execute?.(null, { action: "snapshot", profile: "chrome", snapshotFormat: "ai" });
 
     expect(browserClientMocks.browserSnapshot).toHaveBeenCalledWith(
       "http://127.0.0.1:18791",
@@ -151,6 +180,7 @@ describe("browser tool snapshot maxChars", () => {
 describe("browser tool snapshot labels", () => {
   afterEach(() => {
     vi.clearAllMocks();
+    configMocks.loadConfig.mockReturnValue({ browser: {} });
   });
 
   it("returns image + text when labels are requested", async () => {
@@ -175,7 +205,7 @@ describe("browser tool snapshot labels", () => {
 
     const result = await tool.execute?.(null, {
       action: "snapshot",
-      format: "ai",
+      snapshotFormat: "ai",
       labels: true,
     });
 
diff --git a/src/agents/tools/browser-tool.ts b/src/agents/tools/browser-tool.ts
index 37e71db7d..7513d171a 100644
--- a/src/agents/tools/browser-tool.ts
+++ b/src/agents/tools/browser-tool.ts
@@ -190,11 +190,17 @@ export function createBrowserTool(opts?: {
           return jsonResult({ ok: true });
         }
         case "snapshot": {
+          const snapshotDefaults = loadConfig().browser?.snapshotDefaults;
           const format =
             params.snapshotFormat === "ai" || params.snapshotFormat === "aria"
               ? (params.snapshotFormat as "ai" | "aria")
               : "ai";
-          const mode = params.mode === "efficient" ? "efficient" : undefined;
+          const mode =
+            params.mode === "efficient"
+              ? "efficient"
+              : format === "ai" && snapshotDefaults?.mode === "efficient"
+                ? "efficient"
+                : undefined;
           const labels = typeof params.labels === "boolean" ? params.labels : undefined;
           const refs = params.refs === "aria" || params.refs === "role" ? params.refs : undefined;
           const hasMaxChars = Object.hasOwn(params, "maxChars");
diff --git a/src/cli/browser-cli-inspect.test.ts b/src/cli/browser-cli-inspect.test.ts
new file mode 100644
index 000000000..30111e9e5
--- /dev/null
+++ b/src/cli/browser-cli-inspect.test.ts
@@ -0,0 +1,78 @@
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { Command } from "commander";
+
+const clientMocks = vi.hoisted(() => ({
+  browserSnapshot: vi.fn(async () => ({
+    ok: true,
+    format: "ai",
+    targetId: "t1",
+    url: "https://example.com",
+    snapshot: "ok",
+  })),
+  resolveBrowserControlUrl: vi.fn(() => "http://127.0.0.1:18791"),
+}));
+vi.mock("../browser/client.js", () => clientMocks);
+
+const configMocks = vi.hoisted(() => ({
+  loadConfig: vi.fn(() => ({ browser: {} })),
+}));
+vi.mock("../config/config.js", () => configMocks);
+
+const runtime = {
+  log: vi.fn(),
+  error: vi.fn(),
+  exit: vi.fn(),
+};
+vi.mock("../runtime.js", () => ({
+  defaultRuntime: runtime,
+}));
+
+describe("browser cli snapshot defaults", () => {
+  afterEach(() => {
+    vi.clearAllMocks();
+    configMocks.loadConfig.mockReturnValue({ browser: {} });
+  });
+
+  it("uses config snapshot defaults when mode is not provided", async () => {
+    configMocks.loadConfig.mockReturnValue({
+      browser: { snapshotDefaults: { mode: "efficient" } },
+    });
+    const { registerBrowserInspectCommands } = await import("./browser-cli-inspect.js");
+    const program = new Command();
+    const browser = program.command("browser").option("--json", false);
+    registerBrowserInspectCommands(browser, () => ({}));
+
+    await program.parseAsync(["browser", "snapshot"], { from: "user" });
+
+    expect(clientMocks.browserSnapshot).toHaveBeenCalledWith(
+      "http://127.0.0.1:18791",
+      expect.objectContaining({
+        format: "ai",
+        mode: "efficient",
+      }),
+    );
+  });
+
+  it("does not apply config snapshot defaults to aria snapshots", async () => {
+    configMocks.loadConfig.mockReturnValue({
+      browser: { snapshotDefaults: { mode: "efficient" } },
+    });
+    clientMocks.browserSnapshot.mockResolvedValueOnce({
+      ok: true,
+      format: "aria",
+      targetId: "t1",
+      url: "https://example.com",
+      nodes: [],
+    });
+    const { registerBrowserInspectCommands } = await import("./browser-cli-inspect.js");
+    const program = new Command();
+    const browser = program.command("browser").option("--json", false);
+    registerBrowserInspectCommands(browser, () => ({}));
+
+    await program.parseAsync(["browser", "snapshot", "--format", "aria"], { from: "user" });
+
+    expect(clientMocks.browserSnapshot).toHaveBeenCalled();
+    const [, opts] = clientMocks.browserSnapshot.mock.calls.at(-1) ?? [];
+    expect(opts?.mode).toBeUndefined();
+  });
+});
diff --git a/src/cli/browser-cli-inspect.ts b/src/cli/browser-cli-inspect.ts
index 0e58f4b55..111c888db 100644
--- a/src/cli/browser-cli-inspect.ts
+++ b/src/cli/browser-cli-inspect.ts
@@ -2,6 +2,7 @@ import type { Command } from "commander";
 
 import { browserSnapshot, resolveBrowserControlUrl } from "../browser/client.js";
 import { browserScreenshotAction } from "../browser/client-actions.js";
+import { loadConfig } from "../config/config.js";
 import { danger } from "../globals.js";
 import { defaultRuntime } from "../runtime.js";
 import type { BrowserParentOpts } from "./browser-cli-shared.js";
@@ -62,7 +63,11 @@ export function registerBrowserInspectCommands(
       const baseUrl = resolveBrowserControlUrl(parent?.url);
       const profile = parent?.browserProfile;
       const format = opts.format === "aria" ? "aria" : "ai";
-      const mode = opts.efficient === true || opts.mode === "efficient" ? "efficient" : undefined;
+      const configMode =
+        format === "ai" && loadConfig().browser?.snapshotDefaults?.mode === "efficient"
+          ? "efficient"
+          : undefined;
+      const mode = opts.efficient === true || opts.mode === "efficient" ? "efficient" : configMode;
       try {
         const result = await browserSnapshot(baseUrl, {
           format,
diff --git a/src/config/schema.ts b/src/config/schema.ts
index 667072e66..31979f435 100644
--- a/src/config/schema.ts
+++ b/src/config/schema.ts
@@ -250,6 +250,8 @@ const FIELD_LABELS: Record<string, string> = {
   "commands.useAccessGroups": "Use Access Groups",
   "ui.seamColor": "Accent Color",
   "browser.controlUrl": "Browser Control URL",
+  "browser.snapshotDefaults": "Browser Snapshot Defaults",
+  "browser.snapshotDefaults.mode": "Browser Snapshot Mode",
   "browser.remoteCdpTimeoutMs": "Remote CDP Timeout (ms)",
   "browser.remoteCdpHandshakeTimeoutMs": "Remote CDP Handshake Timeout (ms)",
   "session.dmScope": "DM Session Scope",
diff --git a/src/config/types.browser.ts b/src/config/types.browser.ts
index 3b77be9cf..1c39c050a 100644
--- a/src/config/types.browser.ts
+++ b/src/config/types.browser.ts
@@ -8,6 +8,10 @@ export type BrowserProfileConfig = {
   /** Profile color (hex). Auto-assigned at creation. */
   color: string;
 };
+export type BrowserSnapshotDefaults = {
+  /** Default snapshot mode (applies when mode is not provided). */
+  mode?: "efficient";
+};
 export type BrowserConfig = {
   enabled?: boolean;
   /** Base URL of the clawd browser control server. Default: http://127.0.0.1:18791 */
@@ -39,4 +43,6 @@ export type BrowserConfig = {
   defaultProfile?: string;
   /** Named browser profiles with explicit CDP ports or URLs. */
   profiles?: Record<string, BrowserProfileConfig>;
+  /** Default snapshot options (applied by the browser tool/CLI when unset). */
+  snapshotDefaults?: BrowserSnapshotDefaults;
 };
diff --git a/src/config/zod-schema.ts b/src/config/zod-schema.ts
index 71b577599..c0ba37a88 100644
--- a/src/config/zod-schema.ts
+++ b/src/config/zod-schema.ts
@@ -6,6 +6,13 @@ import { HookMappingSchema, HooksGmailSchema, InternalHooksSchema } from "./zod-
 import { ChannelsSchema } from "./zod-schema.providers.js";
 import { CommandsSchema, MessagesSchema, SessionSchema } from "./zod-schema.session.js";
 
+const BrowserSnapshotDefaultsSchema = z
+  .object({
+    mode: z.literal("efficient").optional(),
+  })
+  .strict()
+  .optional();
+
 export const ClawdbotSchema = z
   .object({
     meta: z
@@ -113,6 +120,7 @@ export const ClawdbotSchema = z
         noSandbox: z.boolean().optional(),
         attachOnly: z.boolean().optional(),
         defaultProfile: z.string().optional(),
+        snapshotDefaults: BrowserSnapshotDefaultsSchema,
         profiles: z
           .record(
             z