The loopctl Knowledge Base
This is a complete, plain-language guide to loopctl, the Rust framework for building agents. An agent is a program where an AI model does multi-step work by calling tools you write.
This knowledge base is written for end users like you. Every concept is explained at first use, every abbreviation is decoded in the Glossary, and every claim is grounded in the source code of the crate.
Start here
Section titled “Start here”If you are new to loopctl, read these four pages in order, because they build on each other. Once you finish them, you will know which section to open for any question you hit later:
- What is loopctl? covers the problem it solves, a working example in 20 lines, and the five ideas behind the design.
- The big idea covers the brain and hands split, the two buffers, and who decides what. It is the most important page here.
- Anatomy of a run traces one full run through every layer, step by step.
- The codebase map lists every folder and file, one line each.
The reference sections
Section titled “The reference sections”Reading paths
Section titled “Reading paths”You want to build an agent today
Section titled “You want to build an agent today”Read What is loopctl, then The big idea, then Tools. After that go to Recipes and start with recipes 1 through 3, then Gotchas.
Something went wrong and you want to know why
Section titled “Something went wrong and you want to know why”Read Errors, then Termination, then the subsystem page for your symptom, whether that is compaction, fallback, or detection. Finish with Gotchas.
You are reading the source code
Section titled “You are reading the source code”Read the Codebase map, then the File reference, where every file has a page.
You want the concepts, not the code
Section titled “You want the concepts, not the code”Read The big idea, then the Principles section in order, where each page stands alone. Then go back to any engine or safety page, which will now read like an old friend.
You are going deep on the engine
Section titled “You are going deep on the engine”Read The big idea, then Sans-IO, then state machines. After that take the state machine page, the driver loop, and the four mechanism pages on LLM turn, dispatch, cancellation, and compaction. Finish at Termination.
You are evaluating loopctl for production
Section titled “You are evaluating loopctl for production”Read What is loopctl, then the whole safety section, then the Production hardening recipe, and finally Gotchas.
About this knowledge base
Section titled “About this knowledge base”These pages are grounded in source. They were written against loopctl v0.4.1, so every default value, threshold, and behavior stated here comes from the code or its tests.
They are plain by design. You get no unexplained jargon, short sentences, and every diagram can be read on its own.
They are honest about limits. Where the crate drops images, where defaults surprise you with zero retries, and where heuristics are only heuristics, it is all in the open, mostly in Gotchas.
You can read these pages in any order once you know the four start-here pages. You can also cite them in your own docs, since each page names the file it describes.
For companion resources, see the crate’s API documentation on docs.rs for the item-level reference, its README for the feature matrix, and TESTING.md in the repository.