CLAUDE.md
~/.usebrowser/CLAUDE.md is auto-loaded into every Claude Code session inside UseBrowser. It’s how the agent knows what tools are available, what patterns to follow, and how to approach tasks.
Two files, two purposes
Section titled “Two files, two purposes”| File | Purpose | Who manages it |
|---|---|---|
~/.usebrowser/CLAUDE.md | App-managed. Tools reference, core principles, automation patterns. Refreshed with each update. | UseBrowser |
~/.usebrowser/CLAUDE.user.md | Your customizations. Preferences, workflows, site-specific notes. Never overwritten. | You |
The stock CLAUDE.md is loaded first, then CLAUDE.user.md (if it exists) is appended. Your instructions take priority.
What’s in the stock CLAUDE.md
Section titled “What’s in the stock CLAUDE.md”The app-managed file teaches Claude how to operate the browser effectively. Here’s what each section does:
Session Start
Section titled “Session Start”Tells Claude to call browser_get_extensions() on startup to discover installed extensions. This is how it knows MetaMask is available for crypto tasks, or that an ad blocker might remove DOM elements.
Tools Quick Reference
Section titled “Tools Quick Reference”A compact reference of all 22 MCP tools, grouped by category. Claude doesn’t need to memorize tool names — it reads this on every session start.
Rich Terminal Output
Section titled “Rich Terminal Output”Instructions for rendering screenshots, markdown, and tables inline in the built-in terminal using ub-render. This is why Claude shows you images and formatted tables directly in the terminal.
Core Principles
Section titled “Core Principles”15 rules that govern how Claude approaches browser automation:
- Skills First — check for existing
ubs:skills before writing custom code - Data-First Extraction — probe JS globals and API responses before falling back to DOM selectors
- Two-Phase Architecture — search for URLs first, then extract details in parallel
- Exhaustive Extraction — extract every field the API provides, not just what seems relevant
- Variant-Level Analysis — present data at the most granular level (e.g., each product variant as a separate row)
- True Parallelism — use
asyncio.gatherwithcontext.new_page(), not sequential page loads - Test One Before Scaling — validate extraction on one item before running a batch
These principles are the result of real-world usage. They prevent common mistakes like DOM-first scraping (fragile), sequential navigation (slow), and incomplete extraction (frustrating).
Crypto Skills (UBCS)
Section titled “Crypto Skills (UBCS)”Detailed patterns for MetaMask and Uniswap automation. MetaMask popups are fully automatable — the agent finds them via context.pages, brings them to front, and clicks Confirm. Uniswap swaps use URL parameters for chain selection and JS clicks to bypass overlay elements.
Anti-Patterns
Section titled “Anti-Patterns”A quick-reference list of things Claude should never do: DOM-first extraction, multiple parallel execute_playwright calls, undated output files, string prices instead of floats, etc.
What to put in CLAUDE.user.md
Section titled “What to put in CLAUDE.user.md”This is where you teach Claude your preferences:
# My Preferences- Save research to ~/research/{date}/- When scraping e-commerce, always include seller ratings + shipping cost- Default currency: MYR- I prefer tables over bullet lists
# My Workflows- "morning research": HN front page top 10 → markdown- "price check {product}": compare Shopee MY, Lazada MY, Taobao
# Site-Specific Notes- Shopee MY: filter by "Ships from Malaysia"- Taobao: convert CNY→MYR at 0.65Preferences, named workflows, site-specific quirks — anything you’d tell a colleague who’s helping you.