The loopctl Knowledge Base

A complete, plain-language guide to loopctl — the Rust framework for building agents: programs where an AI model does multi-step work by calling tools you write.

This knowledge base is written for end users. Every concept is explained at first use, every abbreviation is decoded (full list in the Glossary), and every claim is grounded in the source code of the crate.

---

Start here

New to loopctl? Read these four pages in order — they build on each other:

1. What is loopctl? — the problem it solves, a working example in 20 lines, the five ideas behind the design.
2. The big idea — the brain/hands split, the two buffers, who decides what. The most important page here.
3. Anatomy of a run — one full run traced through every layer, step by step.
4. The codebase map — every folder and file, one line each.

The reference sections

Section	What’s inside
01 Core data	The vocabulary everything else uses: messages · tools · the API client · stream events · errors · configuration
02 The engine	How a run actually works: state machine · driver loop · LLM turn · tool dispatch · cancellation · compaction · termination · model switch
03 Safety systems	Keeping agents alive and harmless: middleware · loop detection · convergence · model fallback · reflection & recovery · tool health · safety shield · permissions
04 Extensions	Watching and shaping runs: observers · hooks · memory · contributors · the component bundle
05 Providers	Real models: overview & features · OpenAI family · Anthropic · Gemini · Bedrock · SSE · grammar
06 Integration	Structured answers and the wider world: structured output · MCP · derive macro · presets · testing
07 File reference	One page per source file — what it is, its key items, its gotchas.
08 Cookbook	Every gotcha collected · 14 complete recipes.
09 Principles	The ideas under the hood, each explained from scratch: sans-IO · state machines · tokens & context windows · soft vs hard errors · backoff & jitter · circuit breakers · windows, EWMA & similarity · cooperative cancellation · caching & invalidation · rate limiting · parallel waves · text matching

Reading paths

“I want to build an agent today” What is loopctl → The big idea → Tools → Recipes (start with 1–3) → Gotchas.

“Something went wrong — why?” Errors → Termination → the subsystem page for your symptom (compaction, fallback, detection…) → Gotchas.

“I’m reading the source code” Codebase map → File reference — every file has a page.

“I want to understand how it works, conceptually” Big idea → the Principles section (in order — each page is standalone) → back to any engine or safety page, which will now read like an old friend.

“I’m going deep on the engine” Big idea → Sans-IO → state machines → State machine → Driver loop → the four mechanism pages (LLM turn, dispatch, cancellation, compaction) → Termination.

“I’m evaluating loopctl for production” What is loopctl → Safety section (all of it) → Production hardening recipe → Gotchas.

---

About this knowledge base

• Grounded in source: written against the loopctl codebase (v0.3.0) — every default value, threshold, and behavior stated here comes from the code or its tests.
• Plain by design: no unexplained jargon; short sentences; every diagram can be read on its own.
• Honest about limits: where the crate drops images, where defaults surprise (zero retries!), where heuristics are heuristics — it’s all in the open, mostly in Gotchas.

Companion resources: the crate’s API documentation on docs.rs (item-level reference), its README (feature matrix), and TESTING.md in the repository.