# pi-web-surf

A pi extension that gives [pi](https://github.com/earendil-works/pi-coding-agent) internet access. It registers two tools — `internet_search` and `internet_scrape` — backed by [ketch](https://github.com/1broseidon/ketch), a fast Go CLI for web search and scraping.

> **Keywords:** pi extension, pi coding agent, internet search, web search, web scraping, ketch, DuckDuckGo, Brave, SearXNG, Exa, AI agent tools, coding assistant

## What is ketch

ketch is a single statically-linked Go binary (`~4MB`) that does web search, code search, library docs lookup, URL scraping, and site crawling. It was built for AI agents — every command outputs `--json`. No daemon, no runtime, no API key needed (DuckDuckGo works out of the box). Brave, SearXNG, and Exa backends are available if you have keys.

This extension wraps ketch's `search` and `scrape` commands so pi can call them as native tools.

## Tools

| Tool | What it does |
|------|-------------|
| `internet_search` | Calls `ketch search --json`. Returns ranked results: title, URL, and description. Accepts `query` (required) and `limit` (optional, default 5, max 10). |
| `internet_scrape` | Calls `ketch scrape --json`. Fetches a URL and extracts clean markdown. Use after a search to read a page's full content. Accepts `url` (required), `raw` (optional), and `maxChars` (optional). |

## Usage

The model calls these tools when it needs web access. If it reaches for `curl` or `bash` to fetch URLs, tell it:

> Use internet_search for web lookups. Use internet_scrape to fetch pages.

Explicit invocation also works:

> Use internet_search to find the latest Go release date.

## Setup

Install ketch:

```bash
brew install 1broseidon/tap/ketch   # macOS
go install github.com/1broseidon/ketch@latest   # any platform
```

Set the free DuckDuckGo backend:

```bash
ketch config set backend ddg
```

Install pi-web-surf:

```bash
git clone https://github.com/yanralapdy/pi-web-surf ~/.pi/agent/extensions/pi-web-surf
```

Run `/reload` in pi.

## Test

```bash
npx tsx --test index.test.ts
```

## Files

| File | Purpose |
|------|---------|
| `helpers.ts` | Pure functions: `formatResults`, `formatScrape`, `checkKetch`, `runKetch`. Zero dependencies. |
| `index.ts` | Extension entry. Registers the two tools with pi. |
| `index.test.ts` | 10 tests: result formatting, edge cases, and ketch detection. |

## License

MIT