chore: initial commit

pi extension exposing a single search tool. Providers: Kagi (headless Firefox against kagi.com session-token endpoint) and SearXNG (JSON API). Config lives at ~/.pi/pi-search/config.json with env overrides.
2026-05-25 11:25:41 -04:00
commit ebd7218b95
13 changed files with 4546 additions and 0 deletions
--- a/README.md
+++ b/README.md
@@ -0,0 +1,55 @@
+# 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`.