From ac03a25137af6b5773d480a8e61af7eaff636947 Mon Sep 17 00:00:00 2001
From: Shrey Pandya <shrey@browserbase.com>
Date: Tue, 30 Jun 2026 19:15:37 -0700
Subject: [PATCH] refactor(cli): remove redundant `browse refs` command
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

`browse snapshot` already returns the xpathMap/urlMap, and the ref maps are
cached for element commands regardless — so `browse refs` only re-printed the
maps from the last snapshot (and returned stale data if the page had changed).

Removes the command, its driver handler, the "refs" DriverCommandName, the now
unused getRefMaps accessor, and doc references.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 .changeset/remove-browse-refs.md              |  5 +++++
 packages/cli/README.md                        |  3 +--
 packages/cli/skills/browse/SKILL.md           |  1 -
 packages/cli/src/commands/refs.ts             | 21 -------------------
 .../cli/src/lib/driver/commands/snapshot.ts   |  9 --------
 packages/cli/src/lib/driver/commands/types.ts |  1 -
 .../cli/src/lib/driver/session-manager.ts     |  4 ----
 7 files changed, 6 insertions(+), 38 deletions(-)
 create mode 100644 .changeset/remove-browse-refs.md
 delete mode 100644 packages/cli/src/commands/refs.ts

diff --git a/.changeset/remove-browse-refs.md b/.changeset/remove-browse-refs.md
new file mode 100644
index 000000000..03425549b
--- /dev/null
+++ b/.changeset/remove-browse-refs.md
@@ -0,0 +1,5 @@
+---
+"browse": patch
+---
+
+Remove the `browse refs` command. It only re-printed the `xpathMap`/`urlMap` cached from the last `browse snapshot` — which `browse snapshot` already returns — so it was redundant, and it returned stale maps if the page had changed since that snapshot.
diff --git a/packages/cli/README.md b/packages/cli/README.md
index 53e5b6abd..08cf37049 100644
--- a/packages/cli/README.md
+++ b/packages/cli/README.md
@@ -84,7 +84,7 @@ browse back           # Navigate backward
 browse forward        # Navigate forward
 ```
 
-### Snapshot & refs
+### Snapshot
 
 The accessibility snapshot is the recommended way for agents to discover elements. It prints a tree of refs like `@0-12` that the element commands accept directly.
 
@@ -93,7 +93,6 @@ browse snapshot                 # Accessibility snapshot + cached refs
 browse snapshot --compact       # Tree only, no ref maps
 browse snapshot --filter submit # Filter lines by text or /regex/, keeping ancestors
 browse snapshot --max-depth 4   # Trim output deeper than this depth
-browse refs                     # Show refs cached from the last snapshot
 ```
 
 ### Element actions
diff --git a/packages/cli/skills/browse/SKILL.md b/packages/cli/skills/browse/SKILL.md
index 6f424749a..b4d2c38af 100644
--- a/packages/cli/skills/browse/SKILL.md
+++ b/packages/cli/skills/browse/SKILL.md
@@ -134,7 +134,6 @@ Page state:
 ```bash
 browse snapshot
 browse snapshot --compact
-browse refs
 browse get url
 browse get title
 browse get text body
diff --git a/packages/cli/src/commands/refs.ts b/packages/cli/src/commands/refs.ts
deleted file mode 100644
index 463c58248..000000000
--- a/packages/cli/src/commands/refs.ts
+++ /dev/null
@@ -1,21 +0,0 @@
-import { BrowseCommand } from "../base.js";
-import {
-  driverCommandFlags,
-  runDriverCommandFromFlags,
-} from "../lib/driver/command-cli.js";
-
-export default class Refs extends BrowseCommand {
-  static override description =
-    "Show refs cached from the last browse snapshot in this session.";
-
-  static override examples = ["browse refs", "browse refs --session research"];
-
-  static override flags = {
-    ...driverCommandFlags,
-  };
-
-  async run(): Promise<void> {
-    const { flags } = await this.parse(Refs);
-    await runDriverCommandFromFlags("refs", {}, flags);
-  }
-}
diff --git a/packages/cli/src/lib/driver/commands/snapshot.ts b/packages/cli/src/lib/driver/commands/snapshot.ts
index 70101fb29..f174833a5 100644
--- a/packages/cli/src/lib/driver/commands/snapshot.ts
+++ b/packages/cli/src/lib/driver/commands/snapshot.ts
@@ -34,13 +34,4 @@ export const snapshotHandlers: DriverCommandHandlers = {
       xpathMap: snapshot.xpathMap,
     };
   },
-
-  async refs(manager) {
-    const refMaps = manager.getRefMaps();
-    return {
-      count: Object.keys(refMaps.xpathMap).length,
-      urlMap: refMaps.urlMap,
-      xpathMap: refMaps.xpathMap,
-    };
-  },
 };
diff --git a/packages/cli/src/lib/driver/commands/types.ts b/packages/cli/src/lib/driver/commands/types.ts
index b72480f2c..a2d3e9b51 100644
--- a/packages/cli/src/lib/driver/commands/types.ts
+++ b/packages/cli/src/lib/driver/commands/types.ts
@@ -21,7 +21,6 @@ export const DRIVER_COMMAND_NAMES = [
   "network.on",
   "network.path",
   "open",
-  "refs",
   "reload",
   "screenshot",
   "select",
diff --git a/packages/cli/src/lib/driver/session-manager.ts b/packages/cli/src/lib/driver/session-manager.ts
index a10f78c3b..f8885d5b7 100644
--- a/packages/cli/src/lib/driver/session-manager.ts
+++ b/packages/cli/src/lib/driver/session-manager.ts
@@ -226,10 +226,6 @@ export class DriverSessionManager {
     this.refMaps = refMaps;
   }
 
-  getRefMaps(): RefMaps {
-    return this.refMaps;
-  }
-
   async openResult(page: DriverPage): Promise<OpenResult> {
     return {
       ...this.browserbaseIdentity(),