| 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
Finding the Binary
The helper script browse/bin/find-browse locates (or installs) the browse binary, in order:
browse/dist/browse in the current git repo (development build)- The active plugin root's
browse/dist/browse
~/counsel-os/browse/dist/browse~/.counsel-os/browse/dist/browse (a previously downloaded prebuilt binary)- 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.
