# One-Page Setup Guide

Get Haystack running on your repos in under 5 minutes. This guide covers setup, the inbox, and all the features that keep your PRs moving.

## Setup

### 1. Sign in

Go to [tryhaystack.dev](https://tryhaystack.dev) and click **Log in with GitHub** in the top right.

### 2. Install the GitHub App

The GitHub App requires the Pro plan, which starts with a 14-day free trial (no payment information required to start).

1. Open the [Haystack GitHub App](https://github.com/apps/haystack-code-reviewer-pr-hook/installations/new) and click **Install GitHub App**.
2. Choose the GitHub account or organization to install it on.
3. Select one or more repositories and click **Install & Authorize**.
4. Start the Pro plan free trial.

Every new PR on those repos now gets an automatic Haystack review, with a link posted as a PR comment.

### 3. Install the CLI and run setup

Strongly recommended. The CLI powers instruction drift detection, session tracking (via Entire), and pre-PR triage.

```bash
npm install -g @haystackeditor/cli
haystack login
haystack setup
```

The setup wizard handles everything in one flow: selecting repos, scanning for coding rules and review policies, writing config, and installing session tracking (Entire CLI + git hooks). Coding agents can run `haystack setup --repo owner/name --yes` (or `--json` for NDJSON agent mode).

## How It Works

Every time a PR is opened or updated:

1. Haystack picks up the PR and analyzes it. While analysis runs, the PR appears in the **Analyzing** tab.
2. Haystack posts a comment on the GitHub PR linking to the full review.
3. When analysis completes, the PR is routed to the right inbox tab:
   - **Clean** goes to **Good to Merge** (queues automatically if auto-merge is on).
   - **Issues found** (bugs, instruction drift, rules violations) goes to **Issues Found**.
   - **Review requested** by a teammate goes to **Review Requests**.
   - **No reviewer assigned** goes to **Needs Assignment**.
   - **Human review required, reviewer already assigned** goes to **Awaiting Review**.
   - **External AI reviewers still running** goes to **Waiting for AI Reviewers**.
4. The **Feed** pulls actionable items from across these tabs and presents them one at a time.

## The Inbox

The [Inbox](https://tryhaystack.dev/inbox) is your home base. It organizes every PR across your repos into tabs so you always know what needs attention.

## Feed

The Feed is a card stack that shows one PR at a time and tells you what action it needs, for example:

- **Issues Found** - bugs, instruction drift, or rules violations. Use **Fix issues** to open the agent prompt.
- **Review Requested** - a teammate requested your review.
- **Needs Assignment** - you must assign a reviewer.

Act on the top card and the feed advances to the next item.

## Good to Merge

PRs land here when analysis comes back clean. Each card shows a short "Why it's safe to merge" summary, CI / review / merge-queue status, and a **Merge** button (squash by default). You can also manually mark a PR as Good to Merge from Issues Found.

## Issues Found

Collects PRs where Haystack found something to act on, grouped into:

- **Instruction Drift** - the AI agent deviated from the original instructions (shows what you asked vs. what it did).
- **Bugs** - verified bugs with severity (low / medium / high / critical) and evidence.
- **Rules Violations** - code that breaks your custom rules (`.haystack/pr-rules.yml`).

From here you can open the full review, dismiss the alert, or override with Good to Merge.

## Review Requests, Awaiting Review & Needs Assignment

- **Review Requests** - PRs where a teammate asked for your review.
- **Awaiting Review** - your PRs that need human review and already have a reviewer assigned.
- **Needs Assignment** - your analyzed, clean PRs that do not have a reviewer yet.

## Analyzing, Waiting & Snoozed

- **Analyzing** - PRs currently being analyzed. They move automatically when done.
- **Waiting for AI Reviewers** - analyzed PRs still waiting on external AI reviewer runs or the retriage that folds in their feedback.
- **Snoozed** - dismissed PRs. Restore them at any time.

## Auto-Merge

Lets Haystack merge PRs automatically once they pass all checks.

1. Enable auto-merge in **Triage Settings** (gear icon in the inbox sidebar).
2. Label a PR with `haystack:auto-merge`.
3. When analysis is clean and CI passes, the PR is queued for merge with a countdown timer.

Useful for AI-generated PRs you want to land without babysitting the merge button.

## Babysitting (Auto-Resolve Conflicts)

When multiple PRs are queued, merging one can create conflicts in the next. Babysitting automatically rebases and resolves conflicts on queued PRs so the queue keeps moving. Enable it in **Triage Settings > Babysitting**; it pairs naturally with auto-merge.

## Auto-Fix (Alpha)

With `haystack submit --auto-fix` (alpha, discouraged by default), Haystack sends analysis findings to a coding agent in a sandbox that fixes clearly mechanical issues and leaves anything requiring judgment for the Feed. It runs at most once per PR, and the fix commit is tagged `[haystack-auto-fix]` so re-analysis does not loop.

## haystack submit

Instead of `git push` plus creating a PR on GitHub, run `haystack submit`. Before creating the PR it runs pre-PR triage in parallel:

- **Code review** - scans for bugs before the PR is opened.
- **Rules validation** - checks against your `.haystack/pr-rules.yml` rules.
- **Instruction drift detection** - flags when an AI agent deviated from your instructions.

Then it pushes your branch, creates the PR, and waits for the full analysis, showing the result inline.

Common flags:

| Flag | What it does |
|------|--------------|
| `--title "Fix login"` | Set the PR title |
| `--draft` | Create as a draft PR |
| `--auto-fix` | Alpha opt-in to auto-fix mechanical issues before surfacing to the Feed (discouraged) |
| `--force` | Skip triage checks |
| `--review` | Route to human review instead of auto-merge (lands in Needs Assignment) |
| `--review <user>` | Request review from a specific teammate (lands in their Review Requests) |
| `--no-wait` | Do not wait for analysis results |

If your repo has auto-merge enabled in `.haystack.json`, PRs submitted with `haystack submit` enter the auto-merge queue and merge automatically once analysis is clean and CI passes.

## haystack triage

View the full analysis for any PR - the same data shown in the feed, designed for coding agents to read from the terminal.

```bash
haystack triage 42                             # Current repo, PR #42
haystack triage owner/repo#99                  # Fully qualified
haystack triage https://github.com/o/r/pull/1  # From a GitHub URL
```

Output includes a 1-5 rating, a `clean` or `has-issues` verdict, structured findings, verified bugs with severity, and ready-to-paste agent fix prompts. Use `--json` for machine-readable output (includes `agentFixPrompt` fields) and `--no-wait` to exit immediately if analysis is still pending (otherwise it polls for up to 5 minutes).

## Triage Settings

Open Triage Settings from the gear icon in the inbox sidebar to configure:

- **Review Policies** - what should always get human review (e.g. infrastructure changes, secrets, specific file paths). Stored in `.haystack/review-policy.md`.
- **Auto-Merge** - toggle the merge queue for labeled PRs.
- **Babysitting** - toggle automatic conflict resolution.

Review policies are version-controlled markdown, so your team can review and iterate on them like any other code.

## Chat & Full Review

Clicking any PR in the inbox opens a chat panel. From there you can ask questions about the PR, view the structured findings in the **Issues** tab, and use commands like `/approve`, `/request-changes`, or `/merge`. Click **Details** for the full review - navigator view, diff, sandbox browser, and edit mode. See [PR Chat](/docs/pr-chat) and [Edit Mode](/docs/edit-mode).

## Keyboard Shortcuts

| Shortcut | Action |
|----------|--------|
| `Cmd/Ctrl+1` - `Cmd/Ctrl+7` | Jump to a visible inbox tab |
| `Cmd/Ctrl+Left/Right` | Cycle through inbox tabs |

## Next Steps

- [Setup Wizard](/docs/verification-flow) - configure automated PR verification
- [PR Chat](/docs/pr-chat) - chat with AI about your PR
- [Edit Mode](/docs/edit-mode) - apply AI edits in review
- [Browser Tab](/docs/browser-tab) - preview frontend changes