browse

name	browse
description	Web browsing for legal work: extract contracts from portals, navigate legal research sites, pull documents from cloud storage, capture evidence screenshots.

Browse — Document Extraction & Web Research

You are using a headless browser to access web resources for legal work. This skill enables extracting contracts from data rooms, navigating legal research sites, pulling documents from cloud storage web interfaces, and capturing screenshots as evidence.

Use Cases

• Data room extraction: Pull contracts and exhibits from virtual data rooms (Intralinks, Datasite, Box, etc.)
• Legal research: Navigate case law databases, regulatory agency sites, corporate registries
• Cloud storage access: Download documents from Google Drive, SharePoint, Dropbox web interfaces
• Portal navigation: Access client portals, filing systems, government databases
• Evidence capture: Take full-page screenshots of web pages for litigation or compliance purposes
• Contract import: Extract agreement text from web-based contract management platforms

Setup

Setup is automatic for most installs: browse/bin/find-browse downloads three assets from the plugin's GitHub release on first use (~320MB total, one time) — the prebuilt binary, the playwright runtime packages, and the matching Chromium builds. No bun, node, or build step required. Set COUNSEL_OS_NO_DOWNLOAD=1 to disable the download fallback (airgapped or build-from-source-only environments).

To build from source instead (development, or when no prebuilt binary exists for the platform), run from the plugin root:

cd [counsel-os directory]
bun install
bun run build
bunx playwright install chromium   # the headless browser itself

Finding the Binary

The helper script browse/bin/find-browse locates (or installs) the browse binary, in order:

1. browse/dist/browse in the current git repo (development build)
2. The active plugin root's browse/dist/browse
3. ~/counsel-os/browse/dist/browse
4. ~/.counsel-os/browse/dist/browse (a previously downloaded prebuilt binary)
5. Download fallback: the prebuilt counsel-browse-{platform} from the release matching the plugin VERSION (or latest), installed under the plugin root (or ~/.counsel-os if the plugin tree is read-only).

Downloaded installs also self-provision two companion assets when missing: counsel-browse-runtime.tar.gz (the playwright packages, extracted as node_modules/ two directories above the binary — playwright is external in the compiled binary because bundling it bakes build-host paths) and counsel-browse-{platform}-browsers.tar.gz (the matching Chromium builds, extracted into the ms-playwright cache).

Daemon Lifecycle

The browse CLI is a thin client for a persistent background server. You normally never manage the server directly:

• The first command auto-starts the server; later commands reuse it, so cookies, tabs, headers, and snapshot refs persist between CLI invocations.
• Server state (port, token, PID) lives in ~/.counsel-os/browse/browse-server.json, an owner-only (0700) directory — the file carries the daemon's auth token, so it never goes in world-writable /tmp. It is suffixed -<port> when BROWSE_PORT or CONDUCTOR_PORT is set, so parallel worktrees get isolated instances.
• The CLI health-checks before each command and restarts the server automatically if it crashed.
• status shows the server's health, current URL, tab count, and PID. stop shuts it down; restart brings up a fresh server (browser state, tabs, and refs are cleared).
• Single commands time out after 30s; chain gets 120s.

Selectors & Refs

Interaction commands take either a CSS selector or a ref. Plain visible text is NOT a selector.

• Run snapshot first to get @e1, @e2, … refs for the page's elements, then click @e3, fill @e4 "value", etc.
• snapshot -C additionally finds non-ARIA clickable elements (cursor:pointer, onclick) as @c1, @c2, … refs.
• Refs go stale after navigation or significant DOM changes — re-run snapshot to refresh them.

Command Reference

Generated from browse/src/commands.ts (51 commands). Do not edit by hand — regenerate with python3 scripts/gen_browse_reference.py.

Navigation

Command	Description
goto <url>	Navigate to a URL. Waits for DOM content to load (15s timeout).
back	Go back in browser history.
forward	Go forward in browser history.
reload	Reload the current page.
url	Print the current page URL.

Content Extraction

Command	Description
text	Extract the visible text of the page (scripts, styles, and SVG stripped).
html [selector]	Full page HTML, or the innerHTML of a selector/ref.
links	List all links on the page as text -> URL.
forms	List forms and their fields as JSON (password values redacted).
accessibility	Print the raw ARIA accessibility tree of the page.

Snapshot & Compare

Command	Description
snapshot [-i] [-c] [-d N] [-s sel] [-D] [-a] [-o path] [-C]	Accessibility snapshot with @e1, @e2... refs for interaction. -i interactive elements only; -c compact; -d N limit depth; -s sel scope to a selector; -D/--diff diff against the previous snapshot; -a annotated screenshot (path via -o); -C find non-ARIA clickable elements as @c refs.
diff <url1> <url2>	Navigate to each URL in turn and show a unified diff of their text content. To see what changed on the current page since your last snapshot, use snapshot -D instead.

Interaction

Command	Description
click <selector>	Click an element (CSS selector or @e/@c ref from snapshot).
fill <selector> <value>	Fill a form field. Use "" to clear it.
select <selector> <value>	Select an option from a dropdown.
hover <selector>	Hover over an element (reveals tooltips and menus).
type <text>	Type text via the keyboard at the current focus.
press <key>	Press a key (e.g. Enter, Tab, Escape).
scroll [selector]	Scroll to the page bottom, or scroll an element into view.
wait <selector|--networkidle|--load|--domcontentloaded> [timeout-ms]	Wait for an element to become visible, or for the given load state. Default timeout 15000ms.
upload <selector> <file1> [file2...]	Set one or more files on a file input.
viewport <WxH>	Set the viewport size (e.g. 1920x1080, 375x812).

Dialogs

Command	Description
dialog-accept [text]	Auto-accept future dialogs, optionally answering prompts with text.
dialog-dismiss	Auto-dismiss future dialogs.
dialog [--clear]	Show captured dialog events (--clear empties the buffer).

Inspection & Debugging

Command	Description
js <expression>	Evaluate a JavaScript expression on the page and print the result.
eval <js-file>	Evaluate JavaScript from a file (path must be under /tmp or the working directory).
css <selector> <property>	Print the computed CSS property value of an element.
attrs <selector>	Print an element's attributes as JSON.
console [--clear|--errors]	Show buffered console messages (--errors: errors and warnings only).
network [--clear]	Show buffered network requests: method, URL, status, duration, size.
is <property> <selector>	Check element state. Properties: visible, hidden, enabled, disabled, checked, editable, focused.
perf	Navigation timing breakdown (DNS, TCP, TTFB, download, DOM ready, load).

Cookies, Session & Identity

Command	Description
cookie <name>=<value>	Set a cookie on the current page's domain.
cookie-import <json-file>	Import cookies from a JSON array file (path must be under /tmp or the working directory).
cookie-import-browser [browser] [--domain <domain>]	Import cookies from an installed Chromium browser (Comet, Chrome, Arc, Brave, Edge). With --domain imports directly; otherwise opens the picker UI.
cookies	Dump the browser context's cookies as JSON.
storage [set <key> <value>]	Show localStorage and sessionStorage, or set a localStorage key.
header <name>:<value>	Set an extra HTTP header for subsequent requests.
useragent <string>	Set the user agent (recreates the browser context).

Visual Capture

Command	Description
screenshot [path]	Full-page screenshot (default /tmp/browse-screenshot.png). Paths must be under /tmp or the working directory.
pdf [path]	Save the page as an A4 PDF (default /tmp/browse-page.pdf).
responsive [prefix]	Capture mobile (375x812), tablet (768x1024), and desktop (1280x720) screenshots.

Tabs

Command	Description
tabs	List open tabs with id, title, and URL (active tab marked).
tab <id>	Switch to a tab by id.
newtab [url]	Open a new tab, optionally navigating to a URL.
closetab [id]	Close the current tab, or a specific tab by id.

Multi-Step

Command	Description
chain	Run a JSON array of commands in sequence, read from stdin: echo '[["goto","url"],["text"]]' | browse chain.

Server

Command	Description
status	Server health, current URL, tab count, and PID.
stop	Stop the background server.
restart	Restart the background server (fresh browser; tabs and refs are cleared).

Cookies & Authentication

Many data rooms and client portals require authentication. Two ways to get session cookies into the headless browser:

• cookie-import <file> — import from a JSON array file. Cookie JSON paths must be under /tmp or the current working directory.
• cookie-import-browser [browser] [--domain <domain>] — import directly from a local Chromium browser (Comet, Chrome, Arc, Brave, Edge). Prefer this for local browsers; with --domain it imports without UI, otherwise it opens a picker in the user's browser.

cookie-import /tmp/dataroom-cookies.json
cookie-import-browser chrome --domain docusign.com

Cookie files contain credentials — see Security Notes below.

Common Workflows

Extract a Contract from a Data Room

1. cookie-import /tmp/dataroom-cookies.json
2. goto https://dataroom.intralinks.com/deal/12345
3. snapshot                                          # see the page structure
4. click @e3                                         # navigate to documents
5. click @e7                                         # find the right folder
6. links                                             # list available documents
7. click @e12                                        # open the document
8. text                                              # extract the text

Research a Legal Question

1. goto https://www.law.cornell.edu/uscode/text/15/chapter-2A
2. text                                              # read the statute
3. screenshot "ftc-act-section-5.png"                # capture for reference

Capture Evidence Screenshot

1. goto https://counterparty-website.com/terms-of-service
2. screenshot "/tmp/counterparty-tos-2026-03-13.png"
3. text                                              # extract text for analysis

Download from Cloud Storage

1. cookie-import /tmp/google-drive-cookies.json
2. goto https://drive.google.com/drive/folders/abc123
3. links                                             # list files
4. snapshot                                          # get fresh refs
5. click @e8                                         # navigate to folder
6. click @e14                                        # select file
7. click @e20                                        # trigger download

Multi-Step in One Call

chain runs a JSON array of commands in one round trip:

echo '[["goto","https://dataroom.example.com"],["snapshot"],["text"]]' | browse chain

Security Notes

• Cookie files contain credentials. Store them securely and do not commit them to git.
• Data room content is confidential. Extracted text should be treated with the same confidentiality as the original document.
• Screenshots may contain privileged information. Label and store them appropriately.
• Session cookies expire. If access fails, re-export fresh cookies from your browser.