pi-lean-dimension

Web browsing and search tools for Pi, the AI coding agent.

A monorepo housing three Pi extension packages that give your AI agent the ability to browse the web interactively, fetch static pages as Markdown, and search via SearXNG — all toggled from a single /web command. When the toggle is off, the tools are removed from the agent's context entirely, so web browsing doesn't consume tokens or attention on sessions that aren't doing web work. The same surfaces are user-extensible: author navigation guides that resurface by domain, or drop in a stealth browser backend like Camoufox when a site blocks the shipped Chromium/Firefox.

Quick start (recommended)

pi install npm:pi-lean-portal
npx playwright install chromium firefox

That's it — the tools are registered and start enabled by default. Control them with /web on|off|learn (on = browser tools, learn = browser tools plus guide-saving via web-learn, off = everything off). The state persists per session. To set a different default for new sessions, add this to your Pi settings (~/.pi/agent/settings.json or .pi/settings.json):

{ "browserToggle": { "defaultEnabled": false } }

Install options

| Mode | Command | What you get | Requires | |---|---|---|---| | A — Browser (recommended) | pi install npm:pi-lean-portal | 12 browser tools + /web command | npx playwright install chromium firefox | | B — Full suite | pi install npm:pi-lean-dimension | 13 tools (browser + search) + /web | Playwright browsers + SearXNG server | | C — Search only | pi install npm:pi-lean-search | web-search tool only | SearXNG server |

Notes the table doesn't cover:

• Browser binaries aren't downloaded during npm install (configured via .npmrc). The first browser-navigate call prompts you to run npx playwright install chromium firefox if they're missing.

• SearXNG is optional for Mode B. The browser works immediately without it; web-search returns a clear setup message on first call. When you do run it, point the suite at your instance in Pi settings:

  { "searxng": { "url": "http://localhost:8888" } }

• Search-only has no /web command — a single tiny tool has nothing to toggle.

What's included

Packages

| Package | Type | Description | |---|---|---| | pi-lean-portal | Extension | Interactive browser + /web command owner. 12 tools + 1 command. | | pi-lean-search | Extension | SearXNG search tool (web-search). 1 tool + 1 command (/searxng-status). | | pi-lean-dimension | Umbrella meta-package | Bundles portal + search for one-command install. |

Tools (13 total with search)

| Tool | Package | Purpose | |---|---|---| | browser-navigate | portal | Navigate to a URL, get an accessibility tree with @e element refs | | browser-snapshot | portal | Re-extract the current page's accessibility tree (@e refs) and capture a screenshot to a temp file | | browser-click | portal | Click an element by @e ref | | browser-type | portal | Type text into an input by @e ref | | browser-scroll | portal | Scroll the page | | browser-back | portal | Navigate back | | browser-press | portal | Press a key | | browser-console | portal | Read console messages from the page | | browser-inspect | portal | Query and extract text from elements | | web-fetch | portal | Stateless fetch → Markdown (no JS) | | web-guide | portal | Navigation guidance for a site or pattern | | web-learn | portal | Save/update navigation guidance | | web-search | search | Web search via SearXNG |

Commands

| Command | Owner | Description | |---|---|---| | /web on\|off\|learn\|cookies\|profile\|status | portal | Unified toggle and management | | /searxng-status | search | Test SearXNG connection and update status glyph |

Status bar

When search is installed, two independent glyphs appear:

• ● idle (browser) — browser tools enabled
• ● searxng (search) — SearXNG health (accent=healthy, yellow=degraded, red=unreachable)

Extending it

Beyond the /web toggle, two surfaces are user-driven rather than hardcoded:

• Navigation guides — web-learn saves site-specific playbooks that auto-match by domain and resurface in later sessions.
• Custom browser backends — if a site blocks the shipped Chromium/Firefox, drop a bridge.py subclass into ~/.pi/agent/pi-lean-portal/user-backends/ and drive a patched engine like Camoufox yourself. A quirks schema declares how the engine diverges from base Playwright, and launch options flow from settings.json to the subprocess at runtime. This is user-authored, user-audited code that the extension never auto-downloads. Most installs never need it; the portal README and contributed/README.md cover the full flow when you do.

Development

git clone https://github.com/coreyryanhanson/pi-lean-dimension.git
cd pi-lean-dimension
npm install
npm test                    # vitest run — all workspace tests

License

AGPL-3.0-only