Houston docs

What actually ran (the receipt)

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

No tests ran · install failed (no network) · build failed · 14 files changed

Houston builds it from the commands it executed and the files its tools changed. The agent can't write it, so it's what to check the agent's own summary against: if the reply says the tests pass and the receipt says no tests ran, believe the receipt.

What it lists

  • Checks. Commands that test, typecheck, build, lint, install, start a server, or send an HTTP request to a local server, each with its real exit code. For most test runners (pytest, vitest, jest, mocha, node:test, cargo, unittest) it also shows the passed and failed counts from the runner's own summary. When the agent prints a test's status with echo (npm test; echo "exit=$?"), the exit code shown is the one that echo printed for the test, not the echo's own, and a later part of the command that times out doesn't count against the test.
  • Other commands (ls, git status) are only counted. Click the line to expand it.
  • Browser checks. A page the agent looked at with view_localhost is listed with how its steps went. It counts as passed only when a check of the page (expect_text or wait_for) passed after the last click or keypress. Clicking through a flow shows it didn't break, not that it did the right thing.
  • Subagents. Commands a writable subagent ran, each by name with its exit code and which subagent ran it (even an ls, since you didn't watch it happen), and files a subagent changed, marked with who changed them.
  • Your verify command, when Houston runs it at the end of a turn.
  • Background commands: how one ended, or that it's still running (for a dev server).
  • Stale checks. A check that ran before the turn's last file change says so, since it may not cover the final code.

Todo items it can't back

When the agent marks a todo done that says a check ran ("Backend tests with pytest", "Verify the build") and no passing run of that check is recorded this turn:

  • the receipt lists it as marked done with nothing recorded
  • the agent is told at the moment it marks it
  • the todo list itself stays as the agent wrote it

Items about writing something ("Write tests for the API") never need a run behind them.

An accepted plan's progress

After you accept a plan, each turn that works on it shows how far along it is, counting every turn since you accepted it. For example: "plan: 9 of 11 files, 1 of 3 checks passed".

  • It lists the files the plan named that nothing has changed yet, and each of its checks: passed, ran with nothing passing, or not run yet.
  • It holds across turns, so "finish the planned implementation" two turns later picks up where it was.
  • It says "plan complete" once, and stops when a newer plan replaces it or the chat moves on to other work.
  • If you ask to skip the checks, they show as skipped.

Outcomes it can't tell

These show as unknown rather than passed:

  • an HTTP request made without curl -f (so an error page still exits 0)
  • a test whose exit code is hidden by what follows it (pytest | tail, pytest; echo done)
  • a page that loaded with nothing on it checked

Where it lives

  • It's saved with the conversation and shown again when you reopen it.
  • It never goes to the model.
  • Importing a conversation doesn't bring receipts along, since Houston didn't record those runs.
  • The terminal client and headless mode print it too, --json includes it in the result line, and an HTML export shows it under the turn.
  • It costs nothing: no extra model calls and no extra commands. It only reads what already ran.