Working with runs

Read what a crawl found, follow onboarding, and answer its questions.

Reading the results

When the crawl answers, haystack verify prints three things:

• where your change shows up in the app: each changed spot, how far the crawl got with it, and the steps that reached it;
• what the crawl found, bugs first, each judged bug, not a bug or can't tell, with the steps to see it;
• the changed code the crawl never ran.

Differences the crawl had no time to check are listed as not finished in time; --minutes gives the next crawl longer. With --json, the same results are in crawl.manifest (or crawl.answer while the crawl is still sealing them).

Onboarding

haystack verify onboarding  # where onboarding of this checkout's base is
haystack verify onboarding --wait  # follow it until it is ready or blocked

haystack init starts onboarding, and so does the first haystack verify. When onboarding cannot go on it says why and what would unblock it. When it needs a fact about your app that the repository does not say, it asks a question with fixed choices:

haystack verify answer <question-id> "<choice>"  # then run haystack init

Every result says when Haystack had to choose for you, for example that the app ran with an empty database, or which version of a service it picked because the repository does not pin one.

The stop hook

With Claude Code, haystack init adds a Stop hook, haystack verify precompute --hook, to the per-developer .claude/settings.local.json. When a session stops it captures the checkout, and Haystack builds the app with and without the change and works out what the change touches, without crawling. haystack verify then crawls from that prepared app instead of building it again. The hook takes at most five seconds and never fails the session.

Hosted runs of pushed commits

haystack verify hosted start owner/repo --base <sha> --head <sha>
haystack verify hosted status <run-id> --wait
haystack verify history owner/repo

A hosted run verifies two exact pushed commits on the production Cloud Verifier. haystack verify cases <run> lists its saved cases, and haystack verify explore <run> <case-id> opens your own copy of one for 24 hours after the run.