The three layers.

There are exactly three pieces of Houston. Once you understand them, everything else clicks into place.

The desktop app

Tauri shell plus a React UI. What you see when you launch Houston. It doesn't do any real work. It's a window onto the engine.

Tauri gives us OS integration: file pickers, notifications, deep links, tray icons. React gives us the chat, the board, the file browser, all the components in @houston-ai/*.

The UX is not interchangeable. It is the actual product. Most of our target users (non-technical people running agents) will never see the engine. They see the desktop. The point of the split is not that the desktop is unimportant. The point is that the engine doesn't know or care that the desktop exists, so we can put a mobile app, a CLI, or a third-party UI in front of the same engine without rewriting anything.

The engine

A Rust binary called houston-engine. It speaks HTTP under /v1/* and a WebSocket at /v1/ws. Every action a user takes goes through this protocol. The engine spawns the Claude or Codex CLI, watches files, fires crons, writes to SQLite.

The engine doesn't know about React or Tauri. It only speaks HTTP. That's the most important architectural decision Houston has made. Today it runs natively on your Mac, your PC, or your Linux box. After Chapter 3 lands, it always runs inside a Linux runtime, even on Mac and Windows. The protocol does not change.

Agents

Folders on disk. Each agent lives at ~/.houston/workspaces/<Workspace>/<Agent>/. Inside that folder: a CLAUDE.md file with instructions, a .houston/ directory with typed data files, and an .agents/skills/ directory with installed skills.

An agent has no process attached to it. It's not "running" except when the engine spawns its CLI to handle a turn. Otherwise it's just a folder waiting to be invoked.

Why the split matters

The engine is reusable. You can put any frontend on it. examples/smartbooks/ is a 400-line React app that talks to the same engine, with its own brand, zero @houston-ai/* UI deps. The desktop is one consumer. Houston Mobile (the PWA at tunnel.gethouston.ai) is another. Houston Cloud will be another.

Same engine. Same protocol. Different shells.