# AI Agent Voice, Phone, and Watch Notification Easy Setup Kit

Version: 2026-08-31  
Supported environment: macOS  
Purpose: Hand this file to an AI that can operate local files and the terminal, and ask it to help set up AI-agent notifications for task complete, awaiting a human decision, and failure.

---

## For the user

1. Upload this file to an AI you trust and that can operate this Mac.
2. Tell it: “Follow this file. Detect and plan first. Modify only after I agree.”
3. The AI will first check whether you use Claude Code, Codex, or another AI agent, and whether notification settings already exist on this computer.
4. You should handle Pushover keys, account sign-in, system permissions, and any existing settings the AI is unsure about.

This kit does not guarantee that every AI agent supports local event notifications. If the platform has no official hook, event, or plugin entry point, the AI must stop and explain the limit. It must not invent a polling loop or a long-running process as a substitute.

---

## Work instructions for the AI

You are helping a macOS user who is not comfortable with program setup. Your job is to build trustworthy AI-agent progress notifications so the user does not have to keep watching the screen, and still receives alerts at the right moments:

- The full task is complete, and the user knows what was completed.
- The AI agent needs a person to approve, choose, or supply more information, and the user knows what decision is required.
- Work truly cannot continue, and the user knows where it is stuck.

Notification output, based on the user’s choice, may include:

- macOS local speech.
- Pushover delivery to iPhone.
- Apple Watch display or haptics via iPhone notification mirroring.

### Highest-priority rules

1. Detect and plan first. Modify only after the user gives explicit consent.
2. Do not overwrite or delete existing settings. Read first, explain conflicts, then make the smallest change.
3. Do not ask the user to paste an API token, password, or other secret into the conversation. Create only a least-privilege local template, then stop so the user can fill it in themselves.
4. If you hit sign-in, MFA, payment, account authorization, system privacy permissions, or key entry, stop immediately and hand control back to the user.
5. Notification hooks only remind. They must not approve, reject, or answer on the user’s behalf.
6. Report each event at most once. Do not create a daemon, launchd job, or automatic retry loop that would replay on a schedule.
7. Pushover must always use normal priority `priority=0`. Do not use emergency priority that repeats until acknowledged.
8. Mark every test with `TEST`, and enable only one output at a time.
9. If notifications duplicate, event meaning is unclear, or a full task cannot be identified safely, disable notifications immediately and stop making changes.
10. Do not declare unverified phone delivery or Apple Watch haptics a success. The user must confirm in person.

## Stage 1: Detect only, do not modify

Complete the checks below, and list the results in language a non-technical user can understand:

1. Confirm the operating system is macOS, and note the current shell.
2. Detect installed AI agents and versions, for example Claude Code, Codex, or a platform the user names. Do not install a new AI agent on your own.
3. Consult current official documentation for that version and confirm which complete, permission-request, waiting-for-input, and failure events are available. Do not rely only on event names from memory.
4. Read existing settings and hooks, but do not display secret contents. Common Claude Code locations include `~/.claude/settings.json` and `~/.claude/hooks/`; common Codex locations include `~/.codex/config.toml`, `~/.codex/hooks.json`, and `~/.codex/hooks/`. Use the actual paths on this machine and in current official docs.
5. Check whether speech, Pushover, notification scripts, background processes, or multiple hooks already handle the same events.
6. Confirm that `/usr/bin/say`, Python 3, and any required system commands are available.
7. Ask which outputs the user wants: Mac speech only, or also Pushover, iPhone, and Apple Watch.
8. Explain every file you plan to change, its purpose, how to disable it, how it will be tested, and which steps the user must still complete in person.

After detection, stop and wait for the user to approve the plan. Do not enter the next stage without consent.

## Stage 2: Build the notification architecture

After consent, implement according to platform capability. Prefer this architecture over copying fixed paths:

```text
The AI agent's official events
├─ Full task complete
├─ Human decision required
└─ Work cannot continue
          │
          ▼
Platform event adapter: parse the event, identify the source and the work
          │
          ▼
Safety core: content redaction, one-shot lock, rate fuse, disable switch
          │
          ├─ macOS speech
          └─ Pushover → iPhone → Apple Watch
```

### Event meaning

- Do not treat every reply stop, tool-step end, or intermediate message as “full task complete.”
- If Claude Code uses `Stop`, you must add an explicit full-task marker or another reliable gate; stay silent when the marker is absent.
- If Codex uses `agent-turn-complete`, you must confirm that the current version can reliably tell the primary task’s final result from intermediate output.
- Prefer the platform’s official permission-request or waiting-for-input events for decision-needed notices, for example `PermissionRequest` in the current version’s docs; verify the event name at the time of work.
- If the platform cannot distinguish events reliably, the safe default is no notification. Explain the limit to the user.

### Notification content

Every notice should include a source and a safe summary, for example:

- `Claude task complete: finished the website article draft.`
- `Codex needs your decision: allow changes to the specified config file?`
- `Claude cannot continue: missing input that only the user can provide.`

The summary must:

- Prefer the public description in the event.
- Stay short; keep it to 120 characters or fewer.
- Redact API tokens, passwords, Bearer tokens, full local paths, raw terminal commands, and other likely secrets.
- If there is no safe description, name only the tool type and ask the user to look at the screen. Do not speak or push the raw input.

### One-shot and disable design

- Each hook may start only one short-lived process, then exit immediately after sending the notice.
- Use an atomic one-shot lock, for example a SQLite unique primary key, or a one-time task marker that fits the platform.
- Also add a short rate fuse, so a change in upstream event IDs cannot produce a flood of notices.
- Multi-window speech must use a queue or mutex so voices do not overlap.
- Create an easy-to-understand enable file or disable switch. When disabled, neither speech nor push may run.
- Network failures may be logged locally, but Pushover must not be resent automatically.

### Pushover and secrets

If the user chooses Pushover:

1. Create a local credential template, for example `~/.config/ai-agent-notify/pushover.env`.
2. Set directory permissions to `700` and the credential file to `600`.
3. Stop, and ask the user to fill in `PUSHOVER_TOKEN` and `PUSHOVER_USER` themselves.
4. Do not read out, display, or log the credentials, and do not write them into a repository.
5. Always use `priority=0`, with no automatic retry.

## Stage 3: Layered testing

Test in this order. Advance to the next layer only after the current layer passes:

1. **Disable test**: With the notification switch off, every event stays silent.
2. **Dry-run test**: Write only a local test record. Play no sound and make no network call.
3. **One-shot lock test**: Feed the same fake event twice; only the first is accepted.
4. **Completion-meaning test**: Intermediate replies do not notify; a full task notifies once.
5. **Decision-needed test**: The same request notifies once, the content explains what must be decided, and the original agent still waits for the user.
6. **Mac speech test**: Play only one short utterance labeled `TEST`.
7. **Pushover test**: After the user agrees, send only one normal-priority message labeled `TEST`.
8. **iPhone and Apple Watch test**: Ask the user to confirm notification permissions, Watch app mirroring, Focus modes, mute, and worn-and-unlocked state, then report whether the notice arrived and whether the Watch vibrated.
9. **Master-switch test**: Disable again and confirm that no background process continues to play or send.

If any step fails, keep later outputs closed. Do not loosen the completion condition, turn off deduplication, or add retries just to pass a test.

## Report format when finished

When finished, give the user:

1. Supported AI agents and event types.
2. Files changed or added, and what each is for.
3. How to disable notifications.
4. Tests that passed, and who confirmed them.
5. Anything still unverified or unsupported by the platform.
6. What must be retested after a future AI-agent upgrade.

You may say setup is complete only after full-task, decision-needed, one-shot lock, the disable switch, and the user-chosen outputs have all been verified accordingly.