---
## What it does
PI extension that wraps [Camoufox](https://github.com/daijro/camoufox) — a Firefox fork patched at the C++ level for anti-fingerprint resistance — to give the coding agent a stealth-capable web search and URL fetcher. For sites that block conventional headless browsers (Cloudflare, DataDome, PerimeterX, Turnstile, Google's bot wall, LinkedIn, etc.).
Sibling to [`@the-forge-flow/lightpanda-pi`](https://github.com/MonsieurBarti/lightpanda-pi). Where `lightpanda-pi` is the fast/light choice for cooperative targets, `camoufox-pi` is the choice when sites actively block bots. Camoufox patches fingerprint surfaces inside SpiderMonkey / Gecko C++, before JavaScript can observe them — fundamentally more robust than runtime JS-injection approaches like `puppeteer-extra-plugin-stealth`. Independent benchmarks report ~100% bypass rate vs ~33% for Playwright-Chromium.
## Features
- `tff-fetch_url` — fetch a URL via stealth Firefox and return HTML
- `tff-search_web` — web search via DuckDuckGo (Google lands in a follow-up slice)
- **Stealth properties** — C++-level fingerprint spoofing, patched canvas/WebGL, Juggler (Firefox remote) protocol — not CDP
- **SSRF protection** — private IP ranges, link-local, loopback, cloud metadata, and CGNAT blocked pre-navigation AND on every redirect hop and subframe request
- **Scheme allow-list** — only `http:` / `https:` accepted at the tool boundary; `file:`, `javascript:`, `data:`, `chrome://` rejected
- **Response size caps** — UTF-8-safe truncation at `max_bytes` (default 2 MiB, max 50 MiB) with `truncated` flag
- **`isolate: true` opt-in** — one-shot browser context per call, no cookie/storage bleed
- **Lazy binary download** — ~500 MB Camoufox binary fetched on first use, not install
## Trade-offs vs lightpanda-pi
| | lightpanda-pi | camoufox-pi |
|---|---|---|
| RSS per session | ~50 MB | 200–1300 MB |
| Binary size | few MB | 300–700 MB (lazy download on first use) |
| Cold start | instant | 1–3 s |
| Cooperative sites | yes | yes |
| WAF-protected sites | no | yes |
| Canvas/WebGL | not rendered | spoofed (except post-2026-03 regression — see SPEC §17) |
| TLS/JA3 fingerprint | libcurl | Firefox (unspoofed — use proxy if target fingerprints TLS) |
Pick one based on target profile. They can coexist but share no runtime.
## Requirements
- Node.js >= 22.5.0
- PI (`pi` CLI) installed
- ~500 MB disk space for the Camoufox binary (lazy downloaded on first use)
- macOS or Linux (Windows untested)
## Installation
```bash
# From npm (recommended)
pi install npm:@the-forge-flow/camoufox-pi
# Project-local only
pi install -l npm:@the-forge-flow/camoufox-pi
# From GitHub (tracks main)
pi install git:github.com/MonsieurBarti/camoufox-pi
# Pin a version
pi install npm:@the-forge-flow/camoufox-pi@0.1.0
```
Then reload PI with `/reload` (or restart it). First tool call downloads the Camoufox binary (~500 MB, one-time).
## Usage
### Tools
| Tool | Description | Key parameters |
|---|---|---|
| `tff-fetch_url` | Fetch a URL via stealth Firefox, return HTML/markdown with optional selector/screenshot | `url`, `timeout_ms`, `max_bytes`, `isolate`, `render_mode`, `wait_for_selector`, `selector`, `format`, `screenshot` |
| `tff-search_web` | Web search (DuckDuckGo) | `query`, `max_results`, `timeout_ms`, `isolate` |
**`tff-fetch_url` parameters:**
- `render_mode`: `"static"` | `"render"` (default) | `"render-and-wait"` — page wait strategy.
- `wait_for_selector`: CSS selector; waits for element visibility. Only valid with `render_mode: "render-and-wait"`.
- `selector`: CSS selector; returns `outerHTML` of first match. No-match raises error.
- `format`: `"html"` (default) | `"markdown"` — body format. Markdown drops HTML to save tokens.
- `screenshot`: `{ full_page?, format? ("png"|"jpeg"), quality? (1-100, jpeg only) }` — base64 image in response. Images > 10 MiB rejected.
**`tff-fetch_url` returns:** `{ url, finalUrl, status, html, markdown?, screenshot?, bytes, truncated }`. `truncated: true` means the response exceeded `max_bytes` and was cut at a UTF-8-safe boundary.
**`tff-search_web`** returns `{ engine, query, results[], atLimit }` where each result is `{ title, url, snippet, rank }`. `atLimit` means `results.length === max_results` — could mean DDG had more, or exactly that many. No ground-truth "has_more" signal is available from the engine.
### Security
- **Scheme allow-list.** Only `http:` and `https:` accepted at the tool boundary. `file:`, `javascript:`, `data:`, `chrome://` and similar are rejected before any navigation.
- **SSRF protection.** Per-hop validation: the caller-supplied URL is checked pre-navigation, and every document-type request the browser issues (main-frame initial, redirect hop, subframe navigation) is re-checked via a Playwright route handler. Any unsafe hop — loopback, RFC1918, link-local, cloud metadata 169.254.169.254, CGNAT, IPv6 ULAs — aborts the whole call with `ssrf_blocked { hop: "initial" | "redirect" | "subframe", url, reason }`. Sub-resources (images, scripts, XHR) are not intercepted.
- **Response truncation.** Bodies exceeding `max_bytes` are cut at a UTF-8-safe byte boundary and flagged `truncated: true`. Default 2 MiB, max 50 MiB.
- **Untrusted content.** The `tff-fetch_url` prompt guidelines explicitly warn the LLM that fetched HTML is UNTRUSTED and must not be executed, eval'd, or treated as authoritative instructions.
- **`isolate: true`** for sensitive fetches — fresh `BrowserContext` per call, no cookie/storage reuse with the shared session context.
## Configuration
v0.1.0 does **not** load a config file. All configuration is per-call via tool parameters. A layered config (project-local + user-global + env + fs.watch reload) lands in a later slice.
Defaults baked into `DEFAULT_CONFIG`:
| Field | Default | Description |
|---|---|---|
| `timeoutMs` | `30000` | Per-navigation timeout (ms), overridable via `timeout_ms` |
| `maxBytes` | `2097152` | 2 MiB response cap for `fetch_url`, overridable via `max_bytes` |
| `defaultEngine` | `"duckduckgo"` | Only valid value in v0.1.0 |
## Programmatic API (library mode)
`@the-forge-flow/camoufox-pi` can be imported directly from non-PI code (TFF daemon, scripts, CI harnesses). This is an off-label integration path — PI itself does not officially document cross-extension imports — but the client is PI-agnostic by design and has no PI runtime dependency.
```typescript
import { createClient } from "@the-forge-flow/camoufox-pi";
const client = createClient();
// Optional: wait for ready up-front (factory is lazy; first op would block otherwise).
await client.ensureReady();
const { html, status } = await client.fetchUrl("https://example.com", {
signal: AbortSignal.timeout(30_000),
});
const { results } = await client.search("claude code", {
signal: AbortSignal.timeout(30_000),
maxResults: 10,
});
await client.close();
```
### `createClient(opts?)`
- `opts.config?: Partial
