How the engine actually works.
A walkthrough of every piece of Houston, what it does today, what it should do next, and the reason for every decision in between. If you are a new hire, you should be able to read this top to bottom and start building. If you need more, the code is linked at the bottom of each chapter.
Reading legend
Each chapter has a status pill. Four states.
- Shipped already in the codebase today.
- Partial some of it works, the rest is on the plan.
- Planned proposed design, code not written yet. Some planned work is gated.
- Gate plan sequencing, decisions, and acceptance gates.
Each planned chapter also lists which milestone it belongs to (M1a, M1b, M2, M3, M4, M5) and a rough size in weeks or months. Sizes are honest estimates, not commitments. Where the work depends on something else landing first, the chapter says so.
The big idea, in one paragraph
Houston is a desktop app, an engine, and folders on disk. The desktop app is what users click. The engine is a Rust binary that does the work. The folders are where agents and their data live. The desktop talks to the engine over HTTP. The engine spawns provider CLIs (Claude Code, Codex, Gemini) and watches files. This guide separates shipped truth from proposed work: reliability and scoped auth can improve the native engine now; Linux runtime isolation is a later, spike-gated bet that only ships after cold start, migration, support, and entitlement risks are proven.