# Set up NotiBuddy

NotiBuddy brings questions and progress from connected software to your iPhone. The MCP setup below connects a compatible AI assistant. Apps, scripts, and services can also [connect directly](#connect-an-app-or-service).

**This is a product preview.** Public app and MCP downloads are not available yet. These instructions help testers who already have a build. Check the [release status](/#get-app) before trying to install it.

## What you’ll need for MCP setup

- An iPhone running iOS 17 or later, with the NotiBuddy preview app installed.
- An AI assistant that supports local MCP servers.
- An internet connection on both devices, and a computer that stays awake while your AI works.
- For testers, the NotiBuddy computer-side package and installation instructions supplied with your build.

## Connect your phone and computer

1. Open NotiBuddy, review the connection privacy choices, and allow connection/reply sharing. Then open NotiBuddy on your iPhone and allow notifications.
2. Open **Connect → Add connection → Share Setup**. Send the setup instructions to your computer using AirDrop or another private method.
3. Follow the installation and pairing instructions supplied with your preview build. Keep the pairing code private.
4. Connect NotiBuddy in your AI app’s MCP settings. Ask it to send a test question to your phone, then answer it.

Setup is complete when your AI receives that answer. Seeing a notification alone does not confirm the return connection.

After setup, you can tell your AI:

> Use NotiBuddy when you need a decision from me, and share a few progress updates as you work. Wait for my answer before taking a step that needs approval.

Your AI still needs to check for your reply and continue the task. NotiBuddy does not wake your computer, restart an ended AI session, or replace permission prompts in your AI app. Questions sent through the current MCP tools expire after five minutes. See [Help & questions](/support) if an answer or update does not arrive.

## Connect an app or service

MCP is one way to use NotiBuddy. An app, script, or service can connect directly by implementing the same pairing and encrypted request protocol. It can send supported questions, forms, and progress updates, then receive replies from your phone. This requires an integration; existing apps do not gain support automatically.

For developers: import a valid `nbpair` setup bundle, register the sender’s signing identity using the pairing proof, and send encrypted, signed request envelopes addressed to the paired device. A device ID or an arbitrary signature alone does not establish a trusted connection. Verify replies against the phone’s pinned signing key and handle pending, expired, and failed requests.

Keep pairing material, sender credentials, and saved reply keys in private storage controlled by the integration. A hosted service needs its own securely paired configuration; do not embed one customer’s credentials in a public website or shared application bundle.

The current source includes a TypeScript client intended for Node.js. A standalone SDK is planned, but it is not a published download or a claim of support for every runtime. During preview, developers need the protocol and build instructions supplied with their build. The sending app or service remains responsible for checking replies and continuing its own work.

---

## Technical setup for your AI assistant

The sections below are for an assistant helping a preview tester. They are also available as [plain Markdown](/setup.md).

### 1. Confirm the preview package is available

The local package is named `notibuddy`. Do not assume it is published on npm, install a similarly named package, or claim setup is complete without testing it. Use the package and installation instructions supplied with the user’s preview build. If the package is unavailable, explain what is missing and stop installation.

Once the intended package is installed, its CLI provides `status`, `pair`, and `mcp` commands. The examples below use `npx -y notibuddy@^0.2.0`; run them only after verifying that they resolve to the intended package for this build.

### 2. Check pairing

Run `npx -y notibuddy@^0.2.0 status`. The phone’s **Share Setup** instructions pair the computer using an `nbpair1.` bundle containing public keys and a secret pairing proof. The phone must finish enrollment before sharing.

If the computer is not paired, have the user complete **Connect → Add connection → Share Setup**. A bearer token alone is insufficient. Do not invent credentials or reuse a legacy token file.

The client stores configuration and keys under `~/.notibuddy/` with owner-only permissions. Keep that directory and the pairing bundle private. Never paste their contents into shared logs or MCP configuration.

### 3. Register the local MCP server

Use the AI app’s documented method for adding a local **stdio** MCP server. Preserve any existing servers and settings.

- Command: `npx`
- Arguments: `["-y", "notibuddy@^0.2.0", "mcp", "--to", "personal"]`
- Pairing configuration: read automatically from `~/.notibuddy/`.

For clients that use an `mcpServers` configuration object, merge this entry into that object:

```json
{
  "notibuddy": {
    "command": "npx",
    "args": ["-y", "notibuddy@^0.2.0", "mcp", "--to", "personal"]
  }
}
```

This is a local MCP process. The relay handles encrypted delivery; it is not a remote MCP endpoint. The marketing website is planned for `notibuddy.com`, and the relay for `notibuddy.app`. Use the relay address supplied by the preview build until that transition is complete. Do not silently replace it with either domain.

### 4. Approve the connection

Open **Connect** on the iPhone. Compare the full Sender Key ID shown by Terminal with the pending connection, then approve it. The name is chosen by the computer; compare the ID, not just its name. The approval request expires after 15 minutes. A computer cannot send requests while approval is pending.

On a replacement phone, create a fresh connection, use Restore Purchases if you have a paid plan, and pair your computer again. No recovery code is required. For more than one phone, pair each with a distinct destination name (`--to personal`, `--to work`). All destinations are saved under `~/.notibuddy/destinations`. Use the destination name supplied by Share Setup in your MCP arguments. Version 0.2 requires explicit selection; import an existing pairing with `npx -y notibuddy@^0.2.0 devices migrate --to personal`, preserving its keys and pending replies.

### 5. Verify both directions

Reload the AI app’s MCP configuration if needed. Call `notibuddy_ask` with:

```json
{
  "title": "NotiBuddy connected",
  "message": "Tap OK to finish setup.",
  "options": ["OK"]
}
```

If the result is pending, call the tool again with the returned `requestId` as `resume_id`. Continue checking within the expiry window. Confirm success only after receiving the phone’s response. Report an expired, missing, or failed request honestly.

You can test without an AI subscription after the public package is available:

```bash
npx -y notibuddy@^0.2.0 ask "Connection check" --to personal --message "Reply OK to test both directions." --options "OK" --wait 55
```

If it returns a pending ID, use `npx -y notibuddy@^0.2.0 ask --resume REQUEST_ID --to personal --wait 55` within five minutes. This uses one Free request; checking the reply does not create another request.

### Tools and response handling

**`notibuddy_ask`** sends a question and checks for an answer.

| Parameter | Purpose |
| --- | --- |
| `title`, `message` | The question and its context |
| `options` | Answer choices; custom choices open in the app |
| `input_placeholder` | Enable a quick text reply |
| `fields` | An in-app form using text, email, URL, toggle, stepper, picker, or date fields |
| `sensitive` | Hide content and choices on public notification/Live Activity surfaces |
| `requires_auth` | Require device authentication in the app before answering |
| `wait_seconds` | Wait before returning a pending handle: default 25 seconds, maximum 55 |
| `resume_id` | Check an earlier request without sending a new question |

The current client gives a question five minutes to be answered. A pending handle can be checked after a client restart while the request is still valid. This does not automatically restart the AI host. Never treat a timeout, error, or lack of response as approval.

**`notibuddy_activity`** starts, updates, or ends a progress display or timer. Use `poll` to read controls sent from the phone.

| Parameter | Purpose |
| --- | --- |
| `id` | Stable identifier for an activity |
| `action` | `start`, `update`, `end`, or `poll` |
| `title`, `status` | A short label and update |
| `step`, `total_steps` | Progress through a task |
| `timer_minutes` | A countdown duration |
| `controls` | `pause`, `resume`, `cancel`, or `add_5m` |

The AI host must read and act on control requests. A timer’s cancel button does not terminate an external process. iOS controls background delivery, so updates may be delayed; opening the app refreshes available state. A remotely started activity may briefly show a generic placeholder while its content is decrypted.

### Usage and privacy

Free use allows five requests in a rolling 24 hours. Questions and activity starts, updates, and ends count toward that allowance. Paid entitlements remove that daily cap; Live Activities are not a paid-only feature. Paid phone slots are shared by installations that restore the same verified Apple purchase. Each phone keeps its own keys, requests and computer pairing. See the [proposed plans](/#pricing) and [terms](/terms).

Question and reply content is encrypted between the paired computer and phone. The relay stores encrypted content and delivery metadata. Read the [privacy notice](/privacy) for retention and key-storage details.


## Multiple destinations and sender names

Use `--sender "Coding assistant"` on a CLI command or MCP startup to describe the source of requests. Without it, the hostname is used. This label travels inside encrypted content; it does not create a new identity or separate approval. Apps and scripts using the same connection share its permissions. The phone shows descriptive labels alongside the approved connection.

For one fixed phone, start MCP with `--to personal`. To expose multiple phones explicitly, use `--allow-to personal --allow-to work`; every tool call must then include `to`. `notibuddy_list_destinations` lists only the exposed phones. There is no global active destination, broadcast, or fallback to another phone. Use your saved aliases in these examples; a Share Setup command suggests a unique alias beginning with `iphone-`.

Replies stay bound to their original request and pairing. Sender labels are not inbox addresses. New conversations initiated from the phone are not available in this release.