pi-ios-notify 📱

Send iOS push notifications via Bark when pi completes agent turns. Get notified right on your iPhone when long-running tasks finish, errors occur, or after each individual turn — without watching the terminal.

Package: @aslamplr/pi-ios-notify Repository: github.com/aslamplr/pi-ios-notify

How it works

pi (your Mac)
  │
  │ agent completes a turn → extension fires
  │
  ▼
pi-ios-notify extension
  │
  │ POST https://api.day.app/YOUR_KEY
  │ { title: "✅ pi Complete", body: "…" }
  │
  ▼
Bark server → Apple Push Notification service → Your iPhone 📱

Prerequisites

1. Bark iOS app — Free on the App Store
2. A computer running pi (macOS, Linux, or Windows)
3. pi 0.50+ (uses native fetch and ExtensionAPI)

Installation

via npm

pi install npm:@aslamplr/pi-ios-notify

via git

pi install git:github.com/aslamplr/pi-ios-notify

Manual (local path)

pi install /path/to/pi-ios-notify

Quick test (no install)

pi -e /path/to/pi-ios-notify

Setup

1. Get your Bark device key

1. Install Bark on your iPhone
2. Open the app — you'll see your device key URL, like:

   https://api.day.app/YOUR_DEVICE_KEY_HERE

3. Copy the YOUR_DEVICE_KEY_HERE part (the UUID string)

2. Configure the extension

Inside pi, run:

/ios-notify setup

Paste your Bark device key when prompted.

3. Test it

/ios-notify test

You should receive a "🔔 Test" notification on your iPhone within a second or two.

Commands

| Command | Description | |---------|-------------| | /ios-notify setup | Enter your Bark device key | | /ios-notify test | Send a test notification | | /ios-notify status | Show current configuration | | /ios-notify events <type> <true\|false> | Enable/disable notification types (agent-end, prompt-tools, turn-end, error) | | /ios-notify prompt-tools list | List configured prompt tool names and labels | | /ios-notify prompt-tools add <name> [label] | Add a tool name to watch with optional label | | /ios-notify prompt-tools remove <name> | Remove a tool from the watch list | | /ios-notify prompt-tools clear | Remove all prompt tools | | /ios-notify sound <name> | Set notification sound | | /ios-notify icon <url|pi|default> | Set a custom notification icon | | /ios-notify url <value> | Set optional URL to open when notification is tapped (URL scheme, e.g. ssh://user@host) | | /ios-notify debug <on\|off> | Enable/disable debug logging | | /ios-notify hostname <true\|false> | Append hostname to notifications |

Notification events

| Event | Default | Description | |-------|---------|-------------| | agent-end | ✅ on | Notify when agent finishes a response | | prompt-tools | ✅ on | Notify mid-turn when a configured tool calls for user input | | turn-end | ❌ off | Notify after each individual LLM turn (can be noisy!) | | error | ✅ on | Notify when a tool execution fails |

Toggle with:

/ios-notify events agent-end false
/ios-notify events prompt-tools false
/ios-notify events turn-end true
/ios-notify events error false

Prompt tools

Prompt tools are tools registered by extensions that may ask for user input mid-turn (e.g. ask_user from pi-ask-user, safe_shell_approve from pi-safe-shell). When the LLM calls one of these tools, you get notified immediately.

Configure which tools to watch:

/ios-notify prompt-tools list
/ios-notify prompt-tools add my_custom_tool "My Label"
/ios-notify prompt-tools remove ask_user

The label is shown as the notification title suffix. Default configured tools:

| Tool | Label | Source | |------|-------|--------| | ask_user | Asking | pi-ask-user extension | | ask-user | Asking | pi-ask-user extension | | safe_shell_approve | Permission | pi-safe-shell extension |

Cross-extension notifications

Any extension can send a push notification by emitting an event on pi's shared event bus:

pi.events.emit("pi-ios-notify:notify", {
  title: "🔒 Approval needed",
  body: "bash: rm -rf node_modules",
  source: "safe-shell", // optional
});

pi-ios-notify listens for pi-ios-notify:notify and forwards the title and body to Bark. The emitter controls the notification content entirely. Requires the prompt-tools event toggle to be enabled.

See the companion extension @aslamplr/pi-safe-shell for a usage example — it emits pi-ios-notify:notify before blocking on user approval prompts.

Custom icon

/ios-notify icon https://example.com/my-icon.png

Use default to reset to Bark's default icon, or pi to use the pi logo:

/ios-notify icon pi
/ios-notify icon default

Notification URL

Set a URL that opens when the notification is tapped. Supports any URL scheme:

/ios-notify url ssh://user@myserver          # opens Termius/Blink (SSH)
/ios-notify url https://my-dashboard.com      # opens Safari
/ios-notify url pi://settings                 # custom scheme
/ios-notify url ""                            # clear (no-op on tap)

Debug mode

Enable debug logging to see why notifications are or aren't firing:

/ios-notify debug on

Debug output appears as informative notifications in pi's UI, each prefixed with 🔍. Each event handler logs its name, relevant config state, and throttle flags:

🔍 tool_call name=ask_user inPromptTools=true promptTools=true throttled=false
🔍 send title="pi Asking" body="ask_user"
🔍 agent_end agentEnd=true
🔍 send title="pi ✅ Complete" body="..."

Turn off with:

/ios-notify debug off

Notification sounds

Bark supports various iOS notification sounds. Change with:

/ios-notify sound birdsong

Common sounds: default, minuet, alarm, anticipate, birdsong, bloom, calypso, chime, descant, electronic, fanfare, horn, ladder, mazurka, nightingale, piano, rocket, sirius, strums, suspense, telegraph, tiptoes, tritone, tuberose, twinkle.

Configuration file

The extension stores its config at ~/.pi/ios-notify.json. You can edit it directly:

{
  "barkKey": "YOUR_DEVICE_KEY",
  "barkServer": "https://api.day.app",
  "events": {
    "agentEnd": true,
    "promptTools": true,
    "turnEnd": false,
    "error": true
  },
  "promptTools": {
    "ask_user": "Asking",
    "ask-user": "Asking",
    "safe_shell_approve": "Permission"
  },
  "sound": "default",
  "title": "pi",
  "icon": "",
  "showHostname": false,
  "url": ""
}

Add more tools directly in the config:

{
  "promptTools": {
    "ask_user": "Asking",
    "safe_shell_approve": "Permission",
    "my_custom_tool": "Waiting"
  }
}

Custom Bark server

If you self-host Bark, set the server:

{
  "barkServer": "https://bark.yourdomain.com",
  "barkKey": "YOUR_KEY"
}

What notifications look like

| Event | Notification | |-------|-------------| | Agent completes response | ✅ pi Complete — "refactor the auth module to use JWT" (3 turns) | | Prompt tool called mid-turn | 💬 pi Asking — ask_user | | Prompt tool called mid-turn | 💬 pi Permission — safe_shell_approve | | Cross-extension event emit | 💬 pi {emitter's title} — {emitter's body} | | Each turn | 🔄 pi Turn — Turn 3 finished | | Tool error | ⚠️ pi Error — Error in bash: command not found: foobar (includes error detail) |

Privacy

• Only the Bark device key and notification content are sent to the Bark server
• Your code or conversation content is never transmitted — only the prompt summary you see
• Bark stores notification content encrypted on their server
• You can optionally set up end-to-end encryption in the Bark app

Project structure

pi-ios-notify/
├── index.ts        # Extension entry point (no compilation needed)
├── utils.ts        # Pure utility functions
├── utils.test.ts   # Vitest test suite for utilities
├── defaults.json   # Default icons/images
├── package.json    # Package manifest with pi.extensions entry
└── README.md       # This file

Standard npm package layout — the pi.extensions field in package.json tells pi where to find entry points.

Development

git clone <repo-url>
cd pi-ios-notify
# No npm install needed (pure TypeScript / Node built-ins only)

Load for testing:

pi -e /path/to/pi-ios-notify

Reload changes:

/reload

Tests

npm test

Runs vitest on the extracted utility functions (utils.test.ts):

• formatPrompt — truncation, edge cases
• pluralize — singular, plural, auto-pluralize
• onOff — boolean to on/off
• parseBool — all truthy/falsy strings, edge cases

⚖️ No Warranty

THIS SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND. The authors make no representations that this extension will deliver notifications reliably or in a timely manner. You are responsible for testing notification delivery and configuring appropriate settings.

License

MIT

Credits

• Bark — the wonderful free iOS push notification app
• Inspired by doublezz10/opencode_ios_notifications, Stephanvs/opencode-ntfy, and blanboom/bark-notification-for-claude-codex-opencode