Agents
Set Haystack up with your coding agent, and let it check its own changes.
Set up with your agent
Paste this into Claude Code, Codex, Cursor or any agent that can run commands:
Set up Haystack for me: fetch https://haystack.sh/agents.md and follow it
The playbook at /agents.md walks the agent through installing the CLI, signing in, previewing haystack init and applying it once you agree, checking onboarding, and setting up telemetry. Setup asks you for two things at most: a sign-in code to enter on GitHub, and installing the Haystack GitHub App if it is not installed yet. Telemetry asks for your production origins and consent choice, your review of the settings it may record, and three things only you do: minting the ingest token (haystack telemetry token), profiling your database, and deploying. It never asks for a secret.
The loop
After an agent changes the app's code, it runs two commands:
haystack verify # the handshake: what the change touches, and Haystack's ideas of what could break
haystack verify --intent "<the task>" --idea "<something to try>" # explore, with the agent's steering first
The note haystack init adds to AGENTS.md tells every agent working in the repository to do this, without asking. The agent reads the short report it ends with: each finding's verdict (bug, not a bug, can't tell), why and steps, where the change shows up, and the changed code that never ran. It fixes each bug its change caused and runs the command again. Exit code 4 is the handshake asking for --intent; exit code 3 means onboarding is blocked, and the report says what would unblock it. Exit code 5 means the app copy is broken and the change could not be tested. --json prints the same report as data; --raw prints the crawl's whole record, for scripts.
Onboarding questions
When onboarding needs a fact the repository does not say, it asks a question with fixed choices. The agent shows it to you and files your choice:
haystack verify answer <question-id> "<choice>"
Feedback
When Haystack fails, confuses the agent or gets in its way, the agent says so in a sentence and keeps going:
haystack feedback "<what happened>"
The Haystack team sees it at once.
HTTP API
Everything the CLI does is plain REST under https://haystackeditor.com/v1, with the repository in the path. Send Authorization: Bearer <token>; haystack login --headless gives a long-lived token for CI and agents. Errors are JSON, { "error": "..." }, with a status that says what kind.
| Method and path | What it does | |||
|---|---|---|---|---|
POST /v1/repos/{owner}/{repo}/checks | Check a captured change (the body haystack verify sends) | |||
GET /v1/repos/{owner}/{repo}/checks?commit={sha} | Your newest check of that commit | |||
GET /v1/repos/{owner}/{repo}/checks/{id} | One check; ?waitAfter={updatedAt} holds the read until it changes | |||
DELETE /v1/repos/{owner}/{repo}/checks/{id} | Cancel it | |||
POST /v1/repos/{owner}/{repo}/checks/{id}/verdicts | Your verdict on one of its findings: `{findingId, verdict: bug\ | intended\ | noise, why, decidedBy: agent\ | user} (what haystack verify verdict` sends) |
GET /v1/repos/{owner}/{repo}/checks/{id}/verdicts | The verdicts given on it, oldest first | |||
PUT /v1/repos/{owner}/{repo}/patches/{sha256} | Upload the captured change's patch | |||
GET /v1/repos/{owner}/{repo}/onboarding?base={sha} | Where onboarding of that base is; POST starts it | |||
POST /v1/repos/{owner}/{repo}/onboarding/answers | Answer an onboarding question | |||
GET /v1/repos/{owner}/{repo}/runs | Recent finished hosted runs | |||
POST /v1/feedback | Tell the Haystack team what went wrong |
Ask a check read for Accept: text/markdown and the answer is the report as haystack verify prints it: headline, findings with their steps, where the change shows up, and what never ran.
MCP server
haystack verify hosted mcp # stdio MCP server for hosted runs
It exposes verify_start, verify_status and verify_wait for hosted runs of pushed commits. No credential, repository source or sandbox is reachable through it.