TextBrowser for Pi

Headless browser extension for Pi — browse the web with structured DOM + OCR text maps. 10-50x cheaper than screenshot-based browsing.

┌─────────────┐     browser_navigate(url)     ┌─────────────┐
│   Pi Agent  │ ─────────────────────────────>│  Playwright │
│  (you)      │                               │   Chromium  │
│             │ <─ DOM + OCR text map ────────│             │
└─────────────┘        (~200 tokens)          └─────────────┘

Why TextBrowser?

Approach	~Tokens	Relative Cost
PNG 1920×1080 (vision model)	~1,500–3,000	100%
TextBrowser (text-only)	~150–400	5–15%

Vision-model screenshots burn thousands of tokens per page. TextBrowser captures the DOM structure + runs OCR on a screenshot, then discards the image. Only clean, structured text reaches the AI. You get element lists, bounding boxes, visible text, and OCR content — all for a fraction of the cost.

Need to see colors or layout? Flip to visual mode and get the PNG too.

Install

pi install npm:@bytesbrains/pi-textbrowser
npx playwright install chromium

Or add to your .pi/settings.json:

{
  "packages": ["npm:@bytesbrains/pi-textbrowser"]
}

Note: The Playwright Chromium binary is a one-time install.

Tools

Tool	What it does
browser_navigate	Open a URL, return page context
browser_click	Click by selector / text / XPath
browser_type	Fill input fields
browser_scroll	Scroll page or element into view
browser_screenshot	Capture current page context
browser_read	Read current page without changing it
browser_evaluate	Run JavaScript in the page

Dual-Mode Design

Text-only mode (default) — use for 90% of tasks

browser_navigate(url="https://example.com")

• Screenshot captured only for OCR → image discarded
• Returns: structured DOM elements + OCR text
• Zero image tokens reach the AI
• 5-15× cheaper than visual mode

Use when: navigating, form filling, data extraction, workflow automation, reading content

Visual mode — use ONLY for pixels, colors, layout

browser_navigate(url="https://example.com", visual=true)

• Screenshot captured for OCR and returned as base64 PNG
• Returns: text map + actual image
• 5-15× more tokens than text-only

Use ONLY when: checking layout alignment, verifying color/theme, debugging CSS, reviewing design, reading image content

When to use which

Task	Mode
"Open Gitea and explore repos"	Text-only ✅
"Login to LinkedIn and post"	Text-only ✅
"Check if dark mode looks correct"	Visual 🖼️
"Is the button centered on the page?"	Visual 🖼️
"Read the article content"	Text-only ✅
"Compare this page to the mockup"	Visual 🖼️

Example Session

You: Open https://example.com and explore the page

→ browser_navigate(url="https://example.com")

Page: https://example.com/
Title: Example Domain
Viewport: 1920x1080

Elements (14 interactive of 82 total):
  [3] <a> href="https://iana.org/domains/example" text="More information..."
  ...

OCR (full page screenshot):
Example Domain
This domain is for use in illustrative examples in documents.
...

Requirements

• Node.js 18+
• Pi coding agent installed
• Playwright Chromium: npx playwright install chromium

License

MIT © nandal

---

Built by Agent, for Agents 🤖

---

Built and maintained by BytesBrains — AI automation & agents, engineered to production standards. The model proposes, code guarantees.