adriankarlen/dots/ketch

Ketch

Route every live-source question to one of ketch's five research surfaces — search, code, docs, scrape, crawl — over the transport the operator gave you, with a token budget on every fetch and a source URL on every claim. ketch is one stateless binary — call, result, exit — with web search, OSS code grep, curated library docs, and page/site extraction together, so a complete research pipeline needs no other tool and no daemon.

Transport: stateless CLI by default, MCP when the operator wired it

The CLI is ketch's identity: call → result → exit, --json on every call, exit codes as control flow, zero daemon. That is the default transport and the zero-infrastructure path. The MCP server is a supported alternative for operators who want it — never a prerequisite.

Decide once per session, before the first call:

1. which ketch succeeds → the CLI is your transport: --json on every call, exit codes as control flow.
2. Also check for ketch's tools in your tool list — the MCP tools search, code, docs, scrape, crawl and tag from a server named ketch (in Claude Code: mcp__ketch__search, …), or in pi the package's ketch_search, ketch_code, ketch_docs, ketch_scrape, ketch_crawl and ketch_tag. Present → the operator wired them up on purpose, and using them for research calls is correct and good: structured output, per-URL errors, the same options and error prefixes as MCP. Do not shell out around tools the operator set up. (pi's tools run the CLI for you, so the page-cache tradeoff in step 3 does not apply to them.)
3. Both live → either transport serves research calls, but know the tradeoff: a running MCP server holds the single-process page-cache lock, so concurrent CLI scrapes silently run cache-disabled.
4. Neither CLI nor MCP tools → ketch is not installed. Offer brew install ketch, npm i -g ketch-cli or go install github.com/1broseidon/ketch@latest — an operator action: propose, wait for confirmation.

The rule: use the transport the operator gave you — when both are live, either is fine for research calls, and operator actions are always CLI.

tag is the one exception to the operator-action rule below: it changes local state but the agent is both writer and reader, so it is published over MCP as well as the CLI.

Config discovery is CLI regardless of transport: ketch config prints effective settings and available backends as JSON; there is no config tool over MCP. Operator actions — config set, cache, browser install, crawl --background/status/stop, doctor — are deliberately not in MCP. They are always CLI.

Glossary

Use only these terms in ketch output.

How to use this skill

• Default: answer one question with one or two routed calls. Use the surface routing table, token budgets, and error control flow below.
• ketch research <question>: deep multi-source research — search fan-out → scrape top hits → optional code/docs corroboration → synthesized, cited answer. Read references/verbs/ketch-research.md.
• ketch setup: configure backends with the operator — probe current state, propose exact commands, mutate only on confirmation. Read references/verbs/setup.md. Enter this verb whenever any call returns [precondition] / exit 5.

One question = one plan. Escalate a default run into ketch research when the first search shows the answer is contested, multi-part, or needs corroboration.

Non-negotiable disciplines

1. Use the transport the operator gave you. The CLI is the default; MCP tools in your list mean the operator opted in — use them for research rather than shelling out around them. When both are live, either serves research calls (a running MCP server holds the page-cache lock, so concurrent CLI scrapes run uncached); operator actions — config, cache, browser, background crawls, doctor — are always CLI.
2. Bound every fetch. max_chars 4000–8000 plus trim on any scrape of a page you have not seen — an unguarded page can cost ~25k tokens. Skipping the cap requires a stated one-line reason ("known ~200-word page").
3. Cite every claim. A research synthesis without source URLs is not a deliverable.
4. Error prefixes are control flow. Classify before reacting. Never retry [validation] or [not_found] unchanged.
5. Propose, then mutate. config set, browser install, docker runs, installs — only after the operator confirms the exact command. Never touch a value that is already configured and working.
6. The binary outranks this file. ketch config and --help are ground truth; where they disagree with a table here, trust the binary and flag the skill as drifted.

Gold decision trace

Request: "ketch research — do people actually use Go's iter.Seq in real projects, and what are the gotchas?"
 
Transport: operator wired mcp__ketch__* into this session → honor it; research calls go over MCP.
Plan: 2 queries · scrape top 3 · max_chars 6000 + trim · ≤8 calls
 
search {query: "Go iter.Seq real-world experience gotchas", limit: 5}
  → "[upstream] ddg rate limited" → an explicit backend failed; rotate to another
    usable provider from available_backends, retry once:
    search {query: ..., backend: "brave", limit: 5} → ok
search {query: "Go range-over-func adoption production", backend: "brave", limit: 5}
  → 10 results, 8 unique hosts → picked 3: official blog post, one experience
    report, one issue thread (primary sources over aggregators)
 
scrape {urls: [u1, u2, u3], max_chars: 6000, trim: true}
  → isError=false; checked results[] one by one: u1, u2 ok;
    u3.error = "[upstream] … 503" → dropped, will be named in synthesis
 
code {query: "iter.Seq", lang: "go", limit: 3}      # corroborate real usage
  → 3 repos with file/line URLs
 
Synthesis: five claims, each cited to its URL; u3 listed as unretrieved;
one conflict between u1 and u2 stated and attributed, not averaged.
Budget: 5 of 8 calls (the rate-limited attempt counts).

Surface routing

First match wins:

In reverse: search finds URLs; scrape reads them; crawl reads a site; code reads public source; docs reads library docs. search with scrape: true fuses the first two when you will want full content from every hit — budget it like a scrape.

Keeping a working set with tag

On work that spans more than one session or more than a handful of sources, pass --tag <name> (CLI) or tag (MCP) on the calls you will want again, naming the project or scope of work — remote-access, not results-3.

It works on every surface, and one tag holds them all: search, code, docs, scrape, crawl. So a project tag ends up holding the vendor's documentation, the code that calls it, and the write-up that explained the undocumented flag, in one list. Later, tag show returns that as an llms.txt-shaped index — titles, URLs, descriptions — limited to the newest 50, and you re-read one source instead of re-running the searches that found them. Tag the sources you actually used, not every hit.

Use --limit N / MCP limit for a smaller view; 0 explicitly requests all. entries counts the whole tag and shown counts returned pages. Read the index before searching again, but do not request all of a large tag by default.

The index is durable and outlives the cached page bodies, so it still answers days later. cached: false means no fresh body was confirmed, not a dead link. When cache_status is unavailable, the page cache could not be checked; bookmarks still work and sources can still be fetched. Entries from code, docs and unscraped search hits start that way by nature, since those calls return snippets rather than fetched pages; scrape the URL when you want the whole thing. Read the index first, then fetch only what you need: assembling the whole tag defeats the point.

Check bookmark diagnostics separately from research success: CLI warnings go to stderr (structured under --json), and MCP returns warnings. A failed write does not discard the useful research result. Durable bookmarks use a separate file; test labs must set KETCH_TAGS_PATH as well as isolating the page cache.

Token budgets

Error control flow