Houston docs

On first launch, the welcome screen shows a three-step Get started checklist:

Houston is a coding agent that runs on your own machine and works inside a single project folder.

Houston runs in six places. All of them share one agent core, so tools, permissions, and skills behave the same everywhere.

Bring any model with your own key: Anthropic, OpenAI, Google, any OpenAI-compatible endpoint, or a local model runtime.

Settings opens as a full page over the window. Back to app (at the top of the sidebar) or Esc returns to the chat.

The interactive terminal's composer is a full line editor, so a message can be as long as it needs to be.

Type / in the composer for the command menu.

You don't have to wait for a turn to finish before saying the next thing.

A turn has a step budget: 40 by default, where each model reply is one step. Near the end, the agent is told to wrap up.

Default: high, since coding and long multi-step work gain the most from deeper thinking.

A long run can stop on an approval, a question, or a plan, and then it's just waiting.

Type ! and a command to run it in your own shell without leaving the session: !git status, !npm test. Output streams as it happens.

Start a line with # to turn it into a standing instruction:

Houston remembers what a later session should know, so you don't have to explain the same thing twice.

The side chat answers a quick question about the open chat without adding anything to it.

While a turn runs, each tool result collapses to one line: the transcript is a conversation, not a log.

A turn that ran checks or changed files ends with a line marked Recorded by Houston under the agent's last message.

You can keep working in your own editor while a turn runs. Your changes are never overwritten by an older copy.

When the working tree has changes, the bar above the composer and the Changes panel offer one button that fits the repository:

Rewind takes a chat back to just before one of your earlier messages.

review_changes (or /review) reviews uncommitted changes for correctness, security, and quality.

In the desktop app, the agent can answer with pictures as well as text. In the terminal these blocks stay code, with a line pointing at the desktop app.

When a language server for the project's language is installed, Houston uses it the way an editor would: to check the agent's edits, and to give the agent...

Approval is layered: a mode for the chat, permission rules that refine it, and guardrails that projects and administrators can add.

Shell commands run under the host OS sandbox where one exists, confined to the project folder: writes outside the project are blocked, and network access is...

Houston folds a small hierarchy of rules files into the system prompt on each run, in this order:

When a conversation grows too large, Houston keeps it inside the model's context window:

A subagent reports back into the current turn. spawn_session instead spins off a separate chat that runs in the background.

When the agent spots parallel work you didn't ask for (a fix noticed in passing, the natural follow-up), it proposes it with propose_session instead of...

When the agent hands a task to a separate session (see "Spawn separate sessions"), it runs in the background, often on its own branch and worktree.

Ask the agent for a recurring (or one-time) background run, such as "every morning at 9, run the tests and summarize failures", and it stores a schedule...

A skill is a reusable bundle of instructions the agent loads only when a task needs it.

A subagent works on a task in its own fresh context and reports back, keeping the main conversation clean.

Hooks (Settings, Hooks) run your own shell commands at set points in the agent loop.

Drop a JS file in .houston/plugins/ to register observational lifecycle hooks for logging, metrics, or notifications:

Connect Model Context Protocol servers in Settings: a local stdio process, or a remote HTTP (streamable) or SSE endpoint.

When the gh CLI is installed and signed in, Houston offers dedicated tools for the GitHub loop.

/cost breaks the session down by model:

/doctor reports what Houston can see, in both the desktop app and the terminal:

The desktop app updates itself separately.

The desktop app's menus list what its shortcuts do, with the shortcut beside each item. A shortcut you rebind in Settings shows up in the menus too.

The desktop app's Help menu is last in the menu bar on every platform.

To invite a friend, any of these works:

Houston is open-source software under the Apache License 2.0 (LICENSE in the repository, and a copy inside the packaged app under Resources/).