pi-lean-dimension

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

A monorepo of three Pi extensions that let your AI agent browse the web interactively, fetch static pages as Markdown, search via SearXNG, and call REST APIs through declarative recipe guides. Each surface has its own toggle (/web for browser tools, /api for API tools), so the ones you aren't using are removed from the agent's context entirely and don't consume tokens or attention. Search is an optional add-on if you run a SearXNG instance.

Quick start (recommended)

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

Once installed, the core browsing and API tools are enabled by default; the guide-authoring tools stay off until you opt in (see Commands below). To set a different default for new sessions, add a toolsetDefaults block to your Pi settings (~/.pi/agent/settings.json or .pi/settings.json). The key pattern is the same for every toggle:

{
  "toolsetDefaults": {
    "toolset-state:pi-lean-dimension.web": { "enabled": false },
    "toolset-state:pi-lean-dimension.api": { "enabled": false }
  }
}

toolsetDefaults is read by the pi-tool-masking library on restore, before the toolset's packaged default. Omit a key to use the packaged default; keys only apply when their package (pi-lean-search for search, pi-lean-host for api) is installed.

---

Packages & install

The Quick start above shows a common mix (portal + host). Install any combination from the table below, or the full suite via pi install npm:pi-lean-dimension ([^1], [^2]).

Package	What you get	Requires
pi-lean-portal	Interactive browser tools + /web command	Playwright browser packages[^1]
pi-lean-host	Declarative API tools + /api command	none
pi-lean-search	web-search + /searxng-status	a SearXNG server[^2]

[^1]: Browser binaries aren't downloaded during npm install. The first browser-navigate call prompts you to install them if they're missing. [^2]: SearXNG is only required by pi-lean-search. 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 with { "searxng": { "url": "http://localhost:8888" } }.

Tools

Portal

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

Search

Tool	Purpose
web-search	Web search via SearXNG

Host

Tool	Purpose
api-guide	Browse or inspect API guides
api-fetch	Execute an API operation from a guide
api-learn	Write or update an API guide
api-probe	Discover an endpoint's shape and draft a recipe operation block
api-scaffold	Bootstrap starter verify.json / helper.ts files (local write)
api-store	Read-only inspection of the secrets + token-slot stores (learn-gated)
oauth-mint	Human-in-the-loop OAuth2 token mint

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
/api on|off|learn|status|helpers|secrets|verify|delete|oauth|bootstrap	host	Independent API tools toggle, guide verification, secrets, management, OAuth2 token mint/status, and agent-driven OAuth2 bootstrap

Status bar

Each installed package contributes one independent status-bar glyph:

• ● idle (browser) — browser tools enabled
• ● searxng (search) — SearXNG health (accent=healthy, yellow=degraded, red=unreachable)
• ● api (host) — API tools enabled (accent=on, success=learn, ○=off)

---

Extending it

Beyond the toggles, three 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.
• API recipes — api-learn authors site-specific recipe guides (endpoints, auth, pagination, response shape) that api-fetch executes. For a head start, the caritas repo maintains a library of prebuilt, verified recipes (arxiv, github, wikidata, coingecko, and more) — copy any one into ~/.pi/agent/pi-lean-host/api-guides/ and it loads immediately. Recipes are inert until you copy them, and the primary path is still having your agent author guides on demand via /api learn. See the host README for the full flow.
• 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