Houston Beta
Houston docs

Context, worktrees, and history

Compaction

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

  1. it first trims large tool output the agent has moved past (the agent can re-read anything it still needs)

  2. then it summarizes the older part of the conversation, including the earlier steps of one long request

  • Your current request is always kept word for word.
  • Sized to the model. The threshold is set automatically from the selected model's context window: a large-window model compacts later, a small local model sooner.
  • Built up, not redone. The summary is saved with the conversation, so later turns extend it instead of re-summarizing from scratch.
  • Nothing disappears on screen. The full transcript stays visible; only what's sent to the model is compacted.
  • Settings: set a fixed token threshold, or turn compaction off, in Settings, Agent Behavior, Context window.

Tools loaded on demand

Every tool definition sent to the model costs context on every request, so Houston preloads only the tools a coding task uses all the time:

  • reading, searching, and editing
  • the shell, the todo list, questions, and plans
  • research subagents, skills, and the web
  • git status and diff

The rest are listed with a one-line summary in a find_tools catalog, and the agent loads one when it needs it: the GitHub tools, scheduled runs, spawned and proposed sessions, the localhost preview, images and mockups, notebook editing, ast_grep, review_changes, recall_history, pr_sweep, saving and deleting memories, and writable subagents.

  • A loaded tool stays loaded for the rest of the conversation.
  • Loading changes only what the model sees. Approval modes, plan mode, permission rules, and hooks apply to these tools exactly as to the preloaded ones.

Worktrees

In a git repo, a new chat runs in a fresh, isolated worktree on its own branch under .houston/worktrees/ by default, so the agent's edits never touch your current checkout.

  • Untick New worktree to work in the repo directly.
  • In a repo whose current branch has no commits yet (a fresh git init), the toggle starts off. A worktree can only branch from a branch that has commits, and isn't offered when no branch has any.

Conversations

  • Saved per project folder.
  • Searchable, and you can fork them. A fork starts its own cost at zero: what the original spent stays with the original, so usage totals don't count it twice.
  • Export as JSON or self-contained HTML, and import from either. An HTML export from an older version brings back only the chat text.
  • The File menu starts a new chat (⌘N), a new chat in another folder (⇧⌘N), or one in a recent folder (Open Recent), starts a fresh side chat for the open chat (New Side Chat), and imports or exports chats.

Undoing a turn's file changes

Before the agent edits a file, Houston snapshots it, so the latest turn's changes can be reverted with one click (and re-applied after a revert).

  • Covers every file-editing tool, including multi-file patches (adds, updates, deletes, and moves) and edits made by a writable subagent the turn dispatched.
  • Survives restarts. Checkpoints are kept on disk in your Houston profile, for the most recent 200 turns.
  • Shell side effects aren't covered. Revert only restores files the editing tools touched.

To go back further than the last turn, see "Rewinding to an earlier message".