Cheating at search for Astro docs

This week I completed Doug Turnbull’s excellent Cheat at Search with Agents Maven course. I have been immersed in search for several years now, but Doug is a decades-long veteran, and his course pulled together so many agent-based techniques that I felt inspired to build something new with my learnings.

As ever, I am finding myself writing technical documentation for an API project. I got to choose the CMS, and have recently fallen in love with Astro for this purpose. So I decided I’d try to build a web-based, agent-assisted search for small to medium sized corpuses.

My goals were as follows:

• Match the instant type-ahead experience of Pagefind and Algolia — the two most common choices for docs search — but improve on it with agents.
• Keep inference costs really low, so you can put this on a site without much thought.
• Make it really easy to use — no vector DB, no embedding pipeline, nothing like that.
• Offer a true Q&A experience. I wanted users to feel like they added “AI search to their site,” not just a better Algolia.

Having framed the problem, I started pulling from the course materials for inspiration. One technique I found especially effective, and elegant in its simplicity, was PageIndex, which Matt Overstreet demonstrated in the course. The idea is to simply create a typical book-style index — it was literally built for searching literature (pun intended).

I also love CLIs and file-based techniques, and thought: okay, there is something here we can work from.

What if you just used Claude to read your docs and pull out the key learnings? Most docs are not so big, and Claude is great at making glossaries, FAQs, and such. Plus, doing it in an agent session leverages a developer’s already-paid subscription, and it happens entirely before inference time.

This turned out to be a pretty elegant idea, but on its own it wasn’t going to keep inference-time costs down. I needed to avoid just stuffing a summary of the docs into the context window.

Two things came to mind, out of my own research and the industry at large. First, bash tools work super well. Second, so does progressive disclosure. I combined those two facts, implemented a simple constrained agent loop — four tool calls max by default — and stood up my first experiments.

The result is hev ask, an Astro integration shipped as @hev/ask on npm. Claude reads your docs offline and commits a small, reviewable digest to your repo. While you type, you get instant keyword results — keyless, no model in the path. When you press Enter, a small model (Haiku by default) runs that short search loop over your content and streams back a grounded answer with deep links to the sections it drew from.

Pretty impressed with how it turned out. If you use Astro for your docs, give it a try. Feedback welcome.