# evan/pi-search

Web search extension for [pi coding agent](https://github.com/mariozechner/pi-coding-agent). Registers a single `search` tool. Choose your provider via config.

## Providers

| Provider  | How it works                                                                                  | Requires                                     |
| --------- | --------------------------------------------------------------------------------------------- | -------------------------------------------- |
| `kagi`    | Drives a headless Firefox session against `kagi.com/search?token=…&q=…` and scrapes results. | Kagi session token, `firefox`, `geckodriver` |
| `searxng` | Calls a SearXNG instance's `/search?format=json` endpoint.                                    | A SearXNG base URL with JSON format enabled  |

The Kagi driver is shared across calls for the lifetime of the pi process, so you only pay browser startup once per session.

## Config

Drop a JSON file at `~/.pi/pi-search/config.json`:

```json
{
  "provider": "searxng",
  "kagi": {
    "token": "<your kagi session token>"
  },
  "searxng": {
    "baseUrl": "https://search.example.com"
  }
}
```

### Env Var Overrides

| Variable                  | Overrides            |
| ------------------------- | -------------------- |
| `PI_SEARCH_PROVIDER`      | `provider`           |
| `KAGI_TOKEN`              | `kagi.token`         |
| `PI_SEARCH_SEARXNG_URL`   | `searxng.baseUrl`    |

### Getting A Kagi Session Token

Open `kagi.com`, sign in, then go to **Settings → Session Link**. Copy the `token=` value from the link. Treat it like a password — it grants full account access.

## Tool

| Name     | Args                | Returns                                                |
| -------- | ------------------- | ------------------------------------------------------ |
| `search` | `query: string`     | Markdown list of `## [title](url)\n> description` items |

## Install

```bash
cd ~/.pi/agent/extensions/pi-search
npm install
```

`pi` picks up the extension via the `pi.extensions` entry in `package.json`.