@lincoln504/pi-research

---

Search and scraping run locally in a stealth browser, with no search provider and no monthly cap. The only cost is LLM tokens.

Currently recommended model to configure for research: openrouter/inclusionai/ling-3.0-flash.

Install

As a Pi Coding Agent extension:

pi install npm:@lincoln504/pi-research

Standalone, as an agent skill for Claude Code, Codex, and other skills-compatible agents:

npm install -g @lincoln504/pi-research
pi-research skill install

No extra setup is needed. The package ships ready-made bindings for every platform and runs no install scripts. The stealth browser (~500MB) downloads on first use, so the first scrape takes a few minutes. npm ≥11.19 skips install scripts by default. Leave it that way: nothing needs approving or building. Only Windows with npm older than 11.19 can fail when the install tries to compile from source. Upgrading npm fixes it.

In pi, the extension works out of the box on the session's model and pi's configuration. Standalone use (agent skill or SDK) needs a model configured. See Configuration.

Uninstall

pi remove npm:@lincoln504/pi-research removes the extension. npm uninstall -g @lincoln504/pi-research removes the standalone engine. npm 7+ no longer runs preuninstall, so nothing else is removed on its own: skill links into other agents (Claude Code, Codex, …), the state directory (~/.pi/research/state), and the cache (~/.cache/pi-research, including any downloaded embedding models) stay in place. Remove the skill links first with pi-research skill uninstall (or /research-config → Remove from External Agents). The shared stealth-browser cache (~/.cache/camoufox) is preserved unless PI_RESEARCH_PURGE_BROWSERS=1. See AGENT-SKILL.md for the full picture.

How it works

A research run works in rounds. A coordinator plans each round and starts the first search, researcher agents scrape and read pages in parallel, and a research lead then either starts another round or writes the final report from everything collected. The result is one cited Markdown report, optionally saved to the knowledge store.

Three depth levels (normal, deep, ultra) set the team size and number of rounds. Just describe what you need in plain language, and the tool picks the right one:

Use cases

• Researching inside pi. No search subscription needed.
• Researching from Claude Code, Codex, or another coding agent while a cheaper or local model drives the run. The main agent's budget stays untouched.
• Saving findings to a persistent, searchable knowledge store, scoped globally or per project.
• Building agent systems that find and read web content, or collecting a dataset of web sources.

Why

• No quota and no monthly fee. Most AI search providers cap free searches and then charge, serving results from their own index. pi-research searches and scrapes locally through DuckDuckGo in a stealth browser.
• The index is local. Findings can be saved to a local LanceDB knowledge store that seeds future runs. Repeat questions get faster and cheaper answers.
• Read-only by design. The research agent cannot run shell commands or write, edit, or delete anything. Prompt injection picked up mid-run has nothing to act on.
• Search a little or a lot. Depth levels range from a quick pass to a large-scale investigation.

Requirements / limitations

• Node.js >= 22.19.0
• An LLM with a 100k+ context window (an API key or a local model)
• Internet access on a residential IP, since search, scraping, and YouTube transcripts get bot-blocked from datacenter/VPS/cloud IPs
• pi. The pi extension uses the host's copy while the standalone CLI and agent skill install it as a dependency.
• Local knowledge-store embeddings need @huggingface/transformers, an optional dependency. If its native image chain (sharp) cannot install, npm skips it with a warning and the install still succeeds, so everything works except local embeddings. The store tells you how to restore them.
• Cloudflare Turnstile and similar systems block scraping on some sites. A run compensates with a wide pool of search results to scrape.
• npm reports 1 moderate advisory (adm-zip, pulled in by onnxruntime and the camoufox browser downloader). Installs are unaffected; just don't run npm audit fix --force (its suggested downgrade reintroduces a high-severity advisory). Details: docs/AUDIT-GATE.md.

Channels

npm (npm:@lincoln504/pi-research) is the stable channel and is kept current with breaking pi changes. A git install is the development channel. It has the latest commits and receives breaking changes first.

License

MIT. Bundled third-party licenses are listed in docs/THIRD-PARTY-NOTICES.md.

Package identity

This project is always @lincoln504/pi-research on npm. The pi-research (unscoped) package is unrelated and deprecated.

Versioning

pi-research typically follows the latest pi version and is not actively backwards compatible.