# Set up Notifai on this computer — instructions for agents

You are an agent, and the User asked you to follow these instructions. If what
you are reading is a summary or an excerpt, fetch the raw file first (for
example `curl -fsSL https://app.notifai.sh/setup.md`) and follow that.

Do the work yourself. The User does only what Notifai's messages ask, and you
never ask them to tell you when it's done: setup watches for each step, and
you carry on by yourself.

- **Send Notifai's messages exactly as written.** Make each one your whole
  reply, unchanged: the same words, line breaks, blank lines and Markdown
  (bold, links, numbered steps). Don't rephrase, shorten or join its lines,
  don't put it in a quote or code block, and add nothing before or after it
  except its QR. Never send the same message twice.
- **Keep setup in this conversation.** Never put a QR, link or code in a
  Notification Request.
- **Never work around a step.** Don't send a notification another way, edit
  credential or hook files, or claim the User did something.
- **Trust setup's JSON.** Don't inspect, test or double-check what it
  installed.

Run the commands from the directory the User is working in: setup turns
Notifai on for that project, unless the User turned it off there
(`notifai project enable` turns it back on).

## What to say

A few moments have no message from setup. Say these as written:

**install**, before you install Notifai:

> Installing Notifai so your agents can reach your phone.

**cloud**, when your commands run on a cloud or temporary machine:

> **I can't set up Notifai here:** this is a temporary machine.
>
> On your computer, run:
>
> `curl -fsSL https://notifai.sh/install.sh | sh`
>
> Or ask an agent there to follow **notifai.sh/setup**.

**which-computer**, when you can't tell where your commands run:

> Is this the computer your agents run on? That's the one Notifai connects.

**installer-needs-you**, when the installer reports a `user_action` or the
OS shows a permission prompt:

> **Installing Notifai needs you:** {the `user_action` message, or "check the prompt on your screen"}.

**done**, when setup is done and gave no message (an older `notifai`):

> ✅ **Notifai is set up.** Your agents can notify you.

## 1. Check where your commands run

Notifai connects the computer your commands run on: the User's computer, or a
persistent SSH host or WSL distribution they chose. Cloud chats and cloud
sessions aren't supported: say **cloud** and stop. If you can't tell, say
**which-computer**; carry on if the User says yes, otherwise say **cloud**.

Supported agent apps: Claude Code (terminal, IDE, or a Local session in the
Claude desktop app's Code tab), Codex (CLI, IDE, or a local thread in the
ChatGPT desktop app), Cursor, OpenCode, OpenClaw, Hermes and Grok. A local sandbox is no reason to stop: request the
approvals below.

## 2. Find or install `notifai`

Run `notifai --version`. A shell opened before installing can miss it on
PATH, so also check `~/.notifai/bin/notifai` (PowerShell:
`$HOME\.notifai\bin\notifai.exe`) before installing anything. Use an existing
one by absolute path, and let its `doctor --json` diagnose an unknown or old
installation. Never run a `notifai` supplied by the User's repository.

Not installed: say **install**, then follow the official
[find/install section](https://github.com/Raidiant-io/notifai/blob/main/skills/notifai/references/installation.md#find-or-install-the-native-cli):
download the bootstrap from notifai.sh, read it, and run it with
`--no-init --json` (PowerShell: `-NoInit -Json`). It verifies the signed
release and needs no Node, npm, Bun or Git. Keep an existing version and
channel; install beta only on the User's explicit word. If the reference or
bootstrap is unavailable, say "**I couldn't finish setting up Notifai:**
{why}." and stop.

After installing, call it by name, `notifai`, so your app's command rules
match. Use the absolute path the installer printed only while the name doesn't
resolve, and apply the installer's PATH remedy.

Your agent app may ask the User to allow network access (notifai.sh and
GitHub), commands, or writes outside this project (`~/.notifai` and the app's
own settings). That is expected: request each through the app's own prompt.
Never switch to a mode that skips permissions.

## 3. Run setup until it's done

```
notifai init --json --wait 240
```

Run it in the foreground with a tool timeout of at least 5 minutes. If your
tool can't wait that long, lower `--wait` to fit (`--wait 50` for a
60-second limit). It never prompts. Progress goes to stderr; stdout is one
JSON object. **Exit 1 with JSON is a normal outcome: read the JSON.** Setup
opens the browser itself when the User has a step there.

After each run:

1. **Send `message` unless you already sent it**, with the QR when it has one
   (below).
2. **Then act on the result:**

| Result | What you do |
| --- | --- |
| `waiting: true` | Send `message` if present, then rerun at once; say nothing else. |
| `stopped: true`, or the User declined this computer (`credential` gap, `technical.pairing_outcome` is `denied`) | End your turn. Run setup again only when the User asks. |
| `ready: true`, or no gap left | Setup is done: its message says so. If it gave none, say **done**. |
| first gap is `apps` | Ask the apps question (below). |
| first gap is one you fix yourself (next table) | Fix it and rerun. |
| any other gap | A step only the User can do: approve this computer, get the phone app, allow notifications, choose a plan. Rerun at once: setup watches for it. |

The first gap is the first `states` entry with `"status": "gap"`, skipping
`skill`, `question-routing-settings`, `claude-commands`, `codex-commands`,
any `hooks`/`hooks-*` entry with no `remedy.user_action`, and `proof` with no
`message`.

If a `--wait` rerun comes back at once with the same gap, no `waiting` and
nothing new to send, setup isn't watching that step: end your turn and rerun
when the User replies. (An older `notifai` doesn't know `--wait`; see the last
section.) A run cut off by your tool's timeout is harmless: rerun it. If
the User says they're done, rerun; if they say later or stop, end your turn.

| First gap | What you do |
| --- | --- |
| `server`, or `credential` with `pairing_outcome` `not_started` or absent | The service was unreachable. Wait 10 seconds and rerun; if it repeats, send its `message` and stop. |
| `auth`, not about a plan | Rerun once; if it repeats, send its `message` and stop. |
| `contract`, or `cli-bin` with status `gap` | Run `remedy.command`, then rerun. |
| `cli-bin` with status `optional-gap` | Not a gap: keep using the absolute path and the installer's PATH remedy. |
| anything with `remedy.by` `cli` | Run `remedy.command`, then rerun. |

Exit 2 with no JSON is a usage error; stderr names it. `unknown option '--wait'`
or `'--apps'` means an older `notifai` (below).

### The apps question

The first run asks which agent apps to connect. Its `message` is the
question; `technical.supported` lists every app (`id`, `name`) and
`technical.detected` the ids found on this computer. Ask it once: in your
app's question tool as a multi-select with the found apps preselected, if it
has one, otherwise send `message` as written. Wait for the answer, then rerun
with `--apps <ids>` (comma-separated, or `detected` to keep the found ones)
and keep `--apps` on every later run. Setup installs hooks, Notifai's skill
(machine-wide) and command approval into those apps without asking anything
else. If the User wants none, rerun with `--no-hooks --no-skills` instead.

### The QR

When a new `message` belongs to a `credential` gap with
`technical.pairing`, show its QR in the same reply, where the message points
("scan this with the Notifai app:" means right after it). In a terminal or
text-only app, read `technical.pairing.qr_text_path` and paste it verbatim in
a fenced text block; where your app shows local images, show `qr_path`. A file
path alone shows nothing. If you can't show it, send the message alone: it
carries the code and the link.

Only if the User asks for an approval notification instead, ask for their
Account email and rerun with `--approval notification --approval-email <email>`.

### Done

Go by the final JSON, not progress text. `proof` is the test notification: it
confirms setup and is never a step, so don't wait for it, rerun for it or ask
about it. Sending and Question Routing (`question_routing_ready`) are separate;
claim only what the JSON shows.

## An older `notifai`

An `unknown option` error for `--wait` or `--apps` means this `notifai`
predates these instructions. Update it: run `notifai update --json`, then start
step 3 again. If the update fails, run the installer from step 2 again: it
replaces the older version with the current one. Then start step 3 again.

If both fail, don't set up with the older version. Send this, and nothing
else, then stop:

> **I couldn't finish setting up Notifai:** its older version here couldn't be updated.
>
> On this computer, run:
>
> `curl -fsSL https://notifai.sh/install.sh | sh`
>
> Then ask me again.
