> For the complete documentation index, see [llms.txt](https://docs.aviator.co/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.aviator.co/verify/setting-up-your-machine.md).

# Setting up your machine

Your team uses Aviator Verify, which checks each pull request against the intent and acceptance criteria behind it. Your coding agent captures those as you work, once you've done the setup below.

## 1. Sign in to Aviator and connect your GitHub account

Sign in at [app.aviator.co](https://app.aviator.co). You need an invite to your company's workspace, so ask whoever set up Verify if you don't have one.

Then open [Settings → Personal → Integrations](https://app.aviator.co/settings/personal/integrations). The GitHub card should read **Connected**. If it reads **Not connected**, click **Connect with GitHub**. Without this, the pull requests you open never link back to Verify.

<figure><img src="https://273246003-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FOAPqUQVbLbsfI5YESl32%2Fuploads%2Fgit-blob-01d8ba4f5a40e1aaf6b71b2d9a7a6b2892c6db16%2Fverify-github-integration.png?alt=media" alt="The GitHub Integration card in Aviator settings, badged Not connected, with a Connect with GitHub button on the right"><figcaption><p>Click <strong>Connect with GitHub</strong> when the card reads <strong>Not connected</strong></p></figcaption></figure>

## 2. Install and set up the Aviator CLI

```bash
brew trust aviator-co/tap
brew install aviator-co/tap/aviator
aviator login
```

`brew trust` is needed on Homebrew 6 and later, and Linux users can grab the `.deb` or `.rpm` from the [releases page](https://github.com/aviator-co/aviator-cli/releases). `aviator login` opens your browser and stores the session in your OS keychain.

## 3. Install the Aviator skill

Your agent runs `/verify-submit` to capture the intent and criteria. It ships separately from the CLI, in the [Aviator agent plugins](https://github.com/aviator-co/agent-plugins).

In Claude Code:

```
/plugin marketplace add aviator-co/agent-plugins
/plugin install aviator@aviator-plugins
```

Codex users install the `verify-submit` skill from the same repository, then run `/hooks` and trust the Aviator hook. Nothing fires until you do.

<figure><img src="https://273246003-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FOAPqUQVbLbsfI5YESl32%2Fuploads%2Fgit-blob-f0de5afd71f2bedb3f9069702c453c91ef3fcaa1%2Fverify-codex-hooks-trust.png?alt=media" alt="The Codex hooks screen warning that 3 hooks need review before they can run, listing PreToolUse, PostToolUse and SessionStart with counts, and offering to press t to trust all"><figcaption><p>Codex lists the three Aviator hooks as needing review until you trust them</p></figcaption></figure>

## Check that it works

Start a **fresh** agent session in the repo, make a small change, and let it open a pull request. The agent should run `/verify-submit`, print a session URL, and put a `Runbook:` line at the top of the PR body. The Aviator Verify check then appears on the pull request.

<figure><img src="https://273246003-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FOAPqUQVbLbsfI5YESl32%2Fuploads%2Fgit-blob-04076b07b1be087255d58659bc88d0e29b5fb364%2Fverify-check-on-pull-request.png?alt=media" alt="The aviator/verify check on a pull request, reading Successful in 2m, Verification passed"><figcaption><p>The <code>aviator/verify</code> check on the pull request</p></figcaption></figure>

## When something doesn't fire

| Symptom                                                   | Cause                                                                                                                                                                 |
| --------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| The agent never mentions Verify                           | The session predates the hooks. Start a new one.                                                                                                                      |
| Nothing fires in Codex                                    | The hook isn't trusted yet. Run `/hooks` in Codex.                                                                                                                    |
| `/verify-submit` isn't a command                          | The Aviator skill isn't installed on this machine.                                                                                                                    |
| The agent says the CLI isn't installed                    | It isn't on `PATH` here. Install it, step 2 above.                                                                                                                    |
| The agent says no credentials were found                  | Run `aviator login`.                                                                                                                                                  |
| Submitting fails with "Repository not found"              | You're signed in to a personal account rather than your company's workspace.                                                                                          |
| The session exists but the pull request never links to it | Your GitHub account isn't connected. Check Settings → Personal → Integrations.                                                                                        |
| The pull request has no Verify check                      | The `Runbook:` line is missing from the body, or the repo isn't connected. See [Fixing verification failures](/verify/how-to-guides/fixing-verification-failures.md). |

## See also

* [Your first verification](/verify/your-first-spec.md), a hands-on run through the whole loop
* [Writing effective acceptance criteria](/verify/how-to-guides/writing-effective-acceptance-criteria.md)
* [Fixing verification failures](/verify/how-to-guides/fixing-verification-failures.md)


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.aviator.co/verify/setting-up-your-machine.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.