# NotiBuddy Setup Guide — Claude Code

> Connect Claude Code and Claude Desktop to NotiBuddy over local MCP. Send custom native screens, approve commands with Face ID, review code diffs, and reply from your iPhone or Apple Watch.
> Human-readable page: https://notibuddy.app/claude-code
> Full CLI, MCP & protocol reference: https://notibuddy.app/setup.md

## 1. Prerequisites & package verification

- **iOS/iPadOS app:** NotiBuddy (iOS 17+ / watchOS 10+ companion included).
- **Computer client:** `notibuddy` **0.4.0** (use `notibuddy@^0.4.0` with `npx` on Node.js 20+, or `brew install yourbit-network/tap/notibuddy`).
- **Publisher:** Yourbit, LLC ([npm](https://www.npmjs.com/package/notibuddy) · [GitHub](https://github.com/yourbit-network/notibuddy)). Do not substitute similarly named packages or invent pairing credentials.
- Verify the CLI runs before pairing:

```bash
npx -y notibuddy@^0.4.0 --help
```

## 2. Check existing pairing before creating a new one

Run:

```bash
npx -y notibuddy@^0.4.0 status
```

- If a destination alias (such as `personal`) is already saved, verify it with `npx -y notibuddy@^0.4.0 doctor --to personal`. **Do not delete or regenerate existing sender keys** just because a check fails.
- If no destination is paired yet, ask the user to open **NotiBuddy** on iPhone → **Connect → Add** → **Create setup code → Share Setup** (valid for 10 minutes; keep NotiBuddy open and online), and **have the user run pairing directly in their own Terminal — never ask the user to paste `nbpair1.` secrets into chat**:

```bash
pbpaste | npx -y notibuddy@^0.4.0 pair --to personal
```

- If more than one destination is paired, bind this host explicitly by immutable `connectionId` (e.g. `npx -y notibuddy@^0.4.0 bind --client claude-code --to personal`).
- Keep `~/.notibuddy/` and the `nbpair1.` bundle strictly private; never paste secrets or keys into chat, logs, repo files, or MCP configuration.

## 3. Configure Claude Code

**Target:** `Claude Code plugin marketplace or global user MCP`

Install the official NotiBuddy plugin in one step (starts cleanly before pairing, auto-uses your sole phone, or pin with nb bind --client claude-code --to personal):

```bash
# Inside Claude Code (recommended — includes MCP + skills):
/plugin install notibuddy --marketplace yourbit-network/notibuddy

# Or register MCP manually in Terminal (global user scope):
claude mcp add -s user notibuddy -- npx -y notibuddy@^0.4.0 mcp --client claude-code
```

### Optional: native PermissionRequest hook (approve tool & Edit diffs on iPhone)

Install the local CLI once (brew install yourbit-network/tap/notibuddy or npm install -g notibuddy), then run /plugin install notibuddy-hooks --marketplace yourbit-network/notibuddy — or add this directly to ~/.claude/settings.json (waits 10s so local terminal answers cost zero requests; previews hidden by default; add --requires-auth for Face ID):

```json
{
  "hooks": {
    "PermissionRequest": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "nb hook claude PermissionRequest --client claude-code --timeout 300",
            "timeout": 330
          }
        ]
      }
    ]
  }
}
```

### Claude Desktop JSON (`~/Library/Application Support/Claude/claude_desktop_config.json`)

If the user is configuring **Claude Desktop** instead of Claude Code CLI, merge this entry into `mcpServers`:

```json
{
  "mcpServers": {
    "notibuddy": {
      "command": "npx",
      "args": ["-y", "notibuddy@^0.4.0", "mcp", "--client", "claude-desktop"]
    }
  }
}
```

> **Homebrew alternative (faster startup):** If the user installed NotiBuddy via `brew install yourbit-network/tap/notibuddy`, you may configure `"command": "notibuddy-mcp"` with `"args": ["--client", "claude-code"]` (or `["--to", "personal"]` to pin a single alias directly).

Preserve all existing servers, workflows, or settings when editing configuration files. Always configure NotiBuddy as a **local stdio MCP server or local CLI** — never point an MCP client at `https://notibuddy.app` as a remote MCP server.

## 4. Recommended rule — Drop this line into CLAUDE.md

> When a task takes more than two minutes, needs a design choice, or is about to run a destructive or production action, call notibuddy_notify (using a Custom Screen or requires_auth: true for production/destructive actions) and wait for my signed reply. Never treat a timeout as approval.

## 5. Verify both directions

1. Run `npx -y notibuddy@^0.4.0 doctor --to personal` (replacing `personal` with the actual saved alias) and confirm approval and protocol health.
2. Reload/restart the MCP server in the host app if required.
3. Call `notibuddy_notify` with:

```json
{
  "title": "NotiBuddy connected",
  "message": "Tap OK to confirm two-way replies.",
  "options": ["OK"]
}
```

Or test from Terminal:

```bash
npx -y notibuddy@^0.4.0 gate "NotiBuddy connected" --to personal --message "Tap OK to confirm two-way replies." --approve "OK" --reject "Cancel" --timeout 120
```

Confirm setup only after receiving a verified signed reply from the phone.

## 6. Tool contract & hard rules

- `notibuddy_notify` (`nb notify`): One-way encrypted notification by default; pass `options`, `input_placeholder`, `fields`, `diff`, `screen`, or `requires_auth: true` for interactive signed replies, or `resume_id` to poll an existing request. Ordinary requests allow up to **10,800 seconds (3 hours)**; `wait_seconds` / `--wait` is a separate poll budget (max 55s).
- **Custom Screens (0.4.0+):** Pass `screen: { templateId, labels, data }` (8 built-in layouts) or `screen: { template }` (12 native blocks: `vstack`, `card`, `divider`, `heading`, `text`, `badge`, `alert`, `kpiStrip`, `keyValueList`, `checklist`, `diffViewer`, `formField`, plus `actions` with optional Face ID) to `notibuddy_notify` or `nb notify --screen <json-file>` (or pre-register with `nb screen register <file> [--strict]`). The server validates and caches only the content-free layout template for up to 30 days while all text, metrics, diffs, and replies remain end-to-end encrypted.
- `nb gate`: Fail-closed CLI gate for scripts and CI/CD (exits `0` approved, `2` rejected/unauthenticated, `3` expired, `1` operational error).
- `nb hook claude PermissionRequest`: Native Claude Code permission hook with 10s local grace period, hidden Lock Screen previews by default, opt-in `--requires-auth`, rolling hourly cap, and silent pass-through on non-decision outcomes. Requires a local `nb` install (never `npx`).
- `notibuddy_activity`: Start, update, end, or poll Lock Screen / Dynamic Island / Apple Watch progress and timers (1-hour lifetime; the agent must poll and act on pause/resume/cancel controls).
- `notibuddy_files`: `action: "list"` and `action: "receive"` (`id` required) to download encrypted phone uploads up to 10 MB under `~/.notibuddy/inbox/`. Never auto-execute received files.
- **Fail closed:** Never treat a timeout, expiry, error, or silence as approval.
- **Keep sessions awake:** The sending host or workflow must stay running to receive replies; NotiBuddy cannot wake a sleeping machine or restart an ended session.
- **Full specification:** https://notibuddy.app/setup.md
