Skip to main content
Get push notifications on your phone when AI tasks finish or need attention — useful when you’re away from your desk.

​
Quick start (ntfy.sh — free)

ntfy.sh is the recommended option. No account required, fully open source.
1

Install the ntfy app

Download from ntfy.sh:
2

Subscribe to a unique topic

Open the app and subscribe to a topic like my-peon-notifications or alice-coding-alerts.
Topics are public by default. Use a random/unique name to avoid collisions (e.g., peon-a8f3d9c2).
3

Configure PeonPing

peon mobile ntfy my-peon-notifications
This enables mobile notifications and sets the topic.
4

Test it

peon mobile test
You should receive a test notification on your phone.

​
Pushover setup

Pushover is a paid service ($5 one-time) with richer notification features.
1

Create a Pushover account

Sign up at pushover.net and install the app.
2

Register an application

  1. Go to pushover.net/apps/build
  2. Create an app named “PeonPing”
  3. Copy the API Token
3

Get your User Key

Find it on your Pushover dashboard.
4

Configure PeonPing

peon mobile pushover <user_key> <app_token>
5

Test it

peon mobile test

​
Telegram setup

1

Create a bot

  1. Message @BotFather on Telegram
  2. Send /newbot and follow the prompts
  3. Copy the bot token (looks like 110201543:AAHdqTcvCH1vGWJxfSeofSAs0K5PALDsaw)
2

Get your chat ID

  1. Message your bot (send any text)
  2. Visit: https://api.telegram.org/bot<YOUR_BOT_TOKEN>/getUpdates
  3. Find "chat":{"id":123456789} in the response
3

Configure PeonPing

peon mobile telegram <bot_token> <chat_id>
4

Test it

peon mobile test

​
Mobile commands

CommandDescription
peon mobile ntfy <topic>Enable ntfy notifications
peon mobile pushover <user> <token>Enable Pushover
peon mobile telegram <token> <chat_id>Enable Telegram
peon mobile onEnable mobile notifications
peon mobile offDisable mobile notifications
peon mobile statusShow current config
peon mobile testSend a test notification

​
Event mapping

Mobile notifications fire on these events:
EventNotification
Task completes”Project: task complete”
Permission needed”Project: approval required”
Error occurs”Project: error”
Rate limit hit”Project: rate limit”
Session start and spam events do NOT trigger mobile notifications.

​
Independent controls

Mobile notifications work independently from desktop notifications and sounds:
Config KeyControlsAffects SoundsAffects DesktopAffects Mobile
enabledMaster audio switch✅ Yes❌ No❌ No
desktop_notificationsDesktop popups❌ No✅ Yes❌ No
mobile_notify.enabledPhone push❌ No❌ No✅ Yes
This means you can:
  • Keep sounds but disable desktop popups: peon notifications off
  • Keep desktop popups but disable sounds: peon pause
  • Enable mobile push without desktop popups: set desktop_notifications: false and mobile_notify.enabled: true

​
Configuration

Mobile settings live in config.json: 
{
  "mobile_notify": {
    "enabled": true,
    "service": "ntfy",
    "ntfy_topic": "my-peon-notifications",
    "pushover_user_key": "",
    "pushover_app_token": "",
    "telegram_bot_token": "",
    "telegram_chat_id": ""
  }
}
Never commit config.json to version control if it contains API tokens.

​
Privacy & security

​
ntfy

  • Messages are not encrypted by default
  • Anyone who knows your topic can subscribe to it
  • Use a random topic name: peon mobile ntfy peon-$(uuidgen | head -c 8)
  • For better privacy, self-host ntfy or use access control

​
Pushover

  • Messages are encrypted in transit (HTTPS)
  • Pushover stores messages on their servers (see privacy policy)

​
Telegram

  • Bot API uses HTTPS
  • Messages are stored on Telegram servers
  • Bots can’t initiate conversations — you must message the bot first

​
Troubleshooting

​
No notifications received (ntfy)

  1. Check the topic name: peon mobile status
  2. Test manually: curl -d "Test" ntfy.sh/YOUR_TOPIC
  3. Verify app is subscribed to the correct topic
  4. Check app notification permissions

​
No notifications received (Pushover)

  1. Verify keys: peon mobile status
  2. Test the API manually: 
    curl -X POST https://api.pushover.net/1/messages.json \
  -d "token=YOUR_APP_TOKEN" \
  -d "user=YOUR_USER_KEY" \
  -d "message=Test"
  3. Check monthly quota (7,500 messages/month on free tier)

​
No notifications received (Telegram)

  1. Verify bot token and chat ID: peon mobile status
  2. Test manually: 
    curl -X POST "https://api.telegram.org/bot<TOKEN>/sendMessage" \
  -d "chat_id=<CHAT_ID>" \
  -d "text=Test"
  3. Make sure you’ve sent at least one message to the bot

​
Advanced: Custom notification server

You can point PeonPing to your own notification endpoint by editing the notification logic in peon.sh (around line 800+). Look for the send_mobile_notification function.

Build docs developers (and LLMs) love

Get started for freeTalk to us