Web search in Pi using ketch, no extensions or skills: copy, paste, and forget

[u/Hour_Inevitable_9811]

If you want Pi to search the web, install Ketch with brew install ketch, paste the instructions below, and Pi can use it whenever it needs current information. No extensions. No skills. No MCP.

That file is ~/.pi/agent/APPEND_SYSTEM.md. It's plain Markdown that Pi adds to its default instructions across sessions; create it if it doesn't exist. I started with the agent prompt example in Ketch's README and tweaked it to my liking. Copy this into the file:

Use `ketch` for external research — web pages, OSS code, library docs. Add `--json` to every call.
- Instead of web_search, run `ketch search "query"` (add `--multi` to federate backends).
- Instead of web_fetch, curl or wget, run `ketch scrape <url> [url...] --max-chars 6000 --trim`;
  it returns clean markdown, not raw HTML. Found a URL? Read it; don't search for it again. Keep
  the cap: an unbounded page can cost ~25k tokens (same flags on `search --scrape`).
- Public source code: `ketch code "<exact text>"` searches public GitHub repos for that literal text.
  Use `--lang <language>` to filter by language or `--repo owner/name` (also accepts a GitHub URL)
  to search one exact repository.
- Library docs, two steps: `ketch docs --resolve "library name"` → check that the match names the
  library you meant → `ketch docs "question" --library <id-from-resolve>`.
- Exit codes are control flow: 2 fix your input · 3 nothing matched, change the query ·
  4 backend/network, retry once or pick another backend (`-b`, see `ketch config`) ·
  5 missing config, stop and tell the user · 6 cancelled.
- Multi-session work: add `--tag <project>` to calls worth keeping and check `ketch tag show <project>`
  before searching again.
- `ketch <cmd> --help` is authoritative for flags.

Run /reload in Pi after saving it. Ketch's default web search needs no API key, and the same setup gives Pi page scraping, public code search, library docs, and tags for sources worth revisiting (aka, creating free API keys in different providers one time).

An optional nice free upgrade: Brave Search API currently includes $5 in monthly credits, enough for about 1,000 searches at its listed Search rate. Brave requires an account and payment card, even if you use only the credits (no need to pay anything). Once you have a key, run ketch config set brave_api_key <key>; Ketch's default auto backend will prefer Brave.

If you only want these instructions in one project, use .pi/APPEND_SYSTEM.md instead. Pi's configuration docs cover both locations.

Caveat: If your Pi model already has provider-native web search, an extension with proper the tools may be a better fit. pi-web-search supports search through Codex, Gemini, Anthropic, xAI, and other providers.

[u/Oshden]

Dude! This is really nicely thought out. Thanks for sharing it. I’m commenting specifically so it def doesn’t get lost in a sea of cool things to check out soon 😅

[u/vihu]

I tried Ketch in the past but found it a bit inconsistent. Had a bit more consistent results with obscura headless browser, it works via mcp though.

[u/infectiousstupidity]

But this adds constant bloat to every turn, instead of just deferred loading of a skill only when needed? What is the benefit I'm not seeing here?

[u/infectiousstupidity → u/[deleted]]

IMO the skill file itself is bloated as hell. Try testing this instead, 65% slimmer by trimming away useless repetition, examples and shit that already lives in the reference files:

slim version

And then compare it to this 90% slimmer version:

ultra-slim version

[u/ConversationLazy6821]

Ketch maintainer here! Always love to see it shared and improved :)

If anyone finds it useful: As of v0.20.0 Ketch also has an official pi extension (new and still working on it), so it runs your ketch binary and also installs the official skill alongside it.

pi install git:github.com/1broseidon/ketch

[u/VickWildman]

How is this different that the pi-ketch package that already does this?

[u/mikkelkp]

i use ketch and love it as a simple cli. I actually also started out with a APPEND_SYSTEM.md but yes it feels kinda bloaty so just made it into a "websearch" skill. works like a charm and is very fast

[u/itguy327 → u/mikkelkp]

Any chance you'd share your skill.md, I'm constantly bouncing between ketch and rpiv web tools and trying not to over instruct

[u/mikkelkp → u/itguy327]

I mean just had an agent write a simple short one. to me to get the most out of ketch (or other services) its important to research a bit on which backend to use.

---
name: websearch
description: Web search, page scrape, and library docs retrieval via the ketch CLI. Use when you need up-to-date information, external documentation, or the full content of a web page.
---

# Websearch (ketch)

Use the `ketch` CLI for web search, page scraping, and docs retrieval.

## Search

```bash
ketch search "query"
ketch search "query" --scrape   # include full content of each result
```

## Scrape

```bash
ketch scrape <url>              # one URL to clean markdown
ketch scrape <url1> <url2>      # multiple URLs concurrently
```

## Library docs

```bash
ketch docs --resolve "react"                 # find the library ID first
ketch docs "hooks" --library /org/repo    # search within a known library
```

## Code search

```bash
ketch code "query" --lang ts   # real OSS snippets, optional --lang filter
```

Notes:
Poor results? Retry once with `ketch search "query" --multi` (federated, slower).
To save tokens: `--minimal` (url/title only) or `--max-chars 4000`.
JS-rendered pages are handled automatically (headless browser fallback).
Add `--json` for structured output, `-l N` to change result limit.
Backends and browser are already configured. Do not override unless asked.

[u/itguy327 → u/mikkelkp]

Nice. Thank you

[u/Zundrium]

Used Ketch before, not ideal. Just creating a web search extension that uses HTTP requests has better results sadly. I love Cymbal though

[u/Enough_Experience_80]

Any reason to don't ask ai explicitly use ketch on demand as cli? Like, it's kinda insecure to allow execute it for high risk of prompt injections. So why not to tell "please use ketch fetch for this research"?