Grounding the agent: how Hipper's pre-flight check actually works

May 28, 2026 · The Hipper team architecturehow-it-worksagents

The premise behind Hipper is one sentence: a model should reason; it shouldn’t be your source of truth for facts that change. Package names, model IDs, API signatures, breaking releases — these all drift continuously, and a frozen model is the wrong place to store them.

So we split the two. The model stays the reasoning engine. A separate, dated knowledge index holds the facts. Hipper sits between them and runs three checks at the moment the agent is planning — before it writes or installs anything.

Where it hooks

Hipper attaches to the agent’s lifecycle at two points:

Planning (the prompt is submitted): inject grounding and modern-syntax deltas into context.
Tool use (the agent is about to run a shell command): inspect install commands and block dangerous ones.

Both run as a local, sandboxed client. It can reach the Hipper API and read the current project — nothing else. A failure never blocks your agent: if Hipper can’t answer, it fails open and the agent proceeds as normal.

Step 1 — Ground

Before the agent relies on an identifier, Hipper checks it against current vendor docs. Is gemini-3.5-flash a real model ID? Has it been deprecated? Is it a typo of something that exists?

The knowledge index is built from real, dated documentation across providers — Gemini, OpenAI, Claude, Mistral — plus the deploy and backend platforms agents reach for (Render, Cloudflare, Railway, Supabase). Identifiers get an existence check and a “did-you-mean” using trigram similarity; the surrounding question gets semantic retrieval over the same index. The agent learns, in context, that a name is wrong before it builds three files around it.

Step 2 — Guard

Every package the agent proposes to install is classified against the live registry — npm and PyPI alike:

$ hipper guard fastapi some-made-up-pkg requestz
✓ fastapi          trusted
✗ some-made-up-pkg HALT — hallucinated (does not exist on PyPI)
✗ requestz         HALT — possible typosquat (did you mean requests)

The verdicts are deliberately blunt: trusted, unverified (real but unknown), possible typosquat, hallucinated. Only a hard verdict — hallucinated or a likely squat — blocks the install. Everything else is surfaced and waved through. The guard understands the package managers agents actually use: npm, pnpm, yarn, bun, pip, uv, poetry, pipx. (We wrote about why this matters in Slopsquatting.)

There’s a quieter signal here too: when a “package” is something the standard library already does in three lines, Hipper says so. Restraint is a feature.

Step 3 — Inject

For the dependencies actually in play, Hipper finds the ones that moved past the model’s training cutoff and injects the delta — the specific breaking change, old symbol to new, in a couple hundred tokens. Not the docs. Not a web-search dump. The difference, stated once. (More on that in The modernization tax.)

Why not just web search?

Because web search optimizes for the wrong things. It returns the most linked answer, not the most current one, and it pays for that in context bloat and nondeterminism. A database-backed index does the opposite: it’s sorted by truth and time, it returns a lean cached delta in sub-second time, and it gives the same answer twice. Roughly ~200 tokens instead of a multi-kilobyte HTML dump — and no retry loop on the other side.

The shape of the system

Backend — a Python agent graph with a FastAPI skin. The brain, and the synthesizer that turns raw changelogs into lean deltas.
Registry — Postgres with trigram and vector search, split into a shared public commons and org-scoped tenant data with strict row-level isolation.
Client — a single sandboxed binary: an MCP server, a coding-agent hook, and a CLI. Net access pinned to the API host, read access pinned to your project.

Three steps, two hook points, one principle: keep the model reasoning, and put the facts somewhere that can actually stay current.

Hipper grounds, guards, and updates your agent before it writes a line of code. Join the waitlist for early access.

Hipper is a pre-flight knowledge guardrail for AI coding agents. Join the waitlist →