pi-lynx

pi-lynx

Pi extension for web search and page fetch via lynx + DuckDuckGo Lite. Terminal browser, web scrape, and search tools with zero API keys.

Install

pi install npm:pi-lynx

Then reload or restart pi:

/reload

Requirements

• lynx installed and on PATH
• Pi coding agent

Alternative: install from git

pi install git:github.com/dabito/pi-lynx

Alternative: install from source

git clone https://github.com/dabito/pi-lynx.git
cd pi-lynx
npm install
pi -e .

Tools

Tool composition

Tools are composed in a layered hierarchy to avoid duplication:

lynx_web_fetch            ← base layer (lynx -dump + parse)
  ↑ used by
lynx_web_search           ← DDG Lite URL construction + result parsing
  ↑ used by
lynx_web_search_github    ← convenience wrapper (pre-set site:github.com)
lynx_web_search_wikipedia ← convenience wrapper (pre-set site:wikipedia.org)

lynx_web_fetch

Fetch a web page and extract its text content and links using lynx.

Name	Type	Required	Default	Description
url	string	✓	—	URL to fetch
max_lines	number		300	Max lines of body text (50–2000, excludes Links section)
include_links	boolean		true	Include extracted links section

lynx_web_search

Search the web using DuckDuckGo Lite. Returns structured results with titles, snippets, domains, and URLs.

Name	Type	Required	Default	Description
query	string	✓	—	Search query; supports !gh and !w shortcuts
max_results	number		8	Max results to return (1–20)
site	string		—	Restrict to "github" or "wikipedia"

Shortcuts:

• !gh <query> or site: "github" → restricts to GitHub
• !w <query> or site: "wikipedia" → restricts to Wikipedia

If both a bang shortcut and an explicit site filter are provided, the explicit filter wins. For example, query: "!gh rust", site: "wikipedia" searches Wikipedia for rust.

lynx_web_search_github

Search GitHub using DuckDuckGo Lite. Convenience wrapper around lynx_web_search with site:github.com pre-set.

Name	Type	Required	Default	Description
query	string	✓	—	Search query
max_results	number		8	Max results to return (1–20)

lynx_web_search_wikipedia

Search Wikipedia using DuckDuckGo Lite. Convenience wrapper around lynx_web_search with site:wikipedia.org pre-set.

Name	Type	Required	Default	Description
query	string	✓	—	Search query
max_results	number		8	Max results to return (1–20)

Configuration catalog

Variable	Default	Min	Description
PI_LYNX_SITE_SEARCH_INTERVAL_MS	3000	1000	Minimum spacing between DDG Lite site: searches. Use 4000 or higher if DuckDuckGo throttles repeated GitHub/Wikipedia searches.

Command catalog

Command	Purpose
npm test	Run fixture-based unit tests. Live DDG search stays skipped by default.
PI_LYNX_INTEGRATION=1 npm test	Run live DDG Lite integration tests. May throttle repeated site: searches.
npm run typecheck	Run strict TypeScript checking.
npm run lint	Run ESLint.
npm pack --dry-run	Preview publish tarball contents.

Notes on DuckDuckGo Lite

Raw DDG bangs such as !gh and !w redirect away from DDG Lite, so pi-lynx converts them to site: filters before searching.

DuckDuckGo Lite can temporarily rate-limit repeated site: searches. pi-lynx spaces site-filtered searches by at least 3 seconds by default; tune with PI_LYNX_SITE_SEARCH_INTERVAL_MS. If GitHub/Wikipedia searches fail during testing, retry after the configured interval or use a general search without site:.

How it works

1. lynx_web_fetch runs lynx -dump on a URL to get plain text + link references.
2. The References section is parsed to build a [N] → URL mapping.
3. DDG redirect URLs (duckduckgo.com/l/?uddg=...) are resolved to real target URLs.
4. [N] markers are stripped from body text for clean output.
5. lynx_web_search constructs a DDG Lite URL and parses search results.
6. Site-specific tools call lynx_web_search with the appropriate site: filter.

Development

npm test
npm run typecheck

Unit tests use committed DuckDuckGo Lite fixtures in test/fixtures.

The live DDG Lite integration test is opt-in because repeated site: searches can be rate-limited:

PI_LYNX_INTEGRATION=1 npm test