Skip to main content
PeonPing sends visual notifications on desktop and mobile when tasks finish or need attention.

​
Desktop Notifications

​
desktop_notifications
boolean
default:"true"
Enable or disable desktop notification popups.When false, sounds continue playing but visual popups are suppressed. Mobile notifications are unaffected.
CLI commands: 
peon notifications on         # Enable desktop popups
peon notifications off        # Disable desktop popups
peon popups off               # Alias for 'notifications off'
peon notifications test       # Send a test notification
Example: 
{
  "desktop_notifications": true
}

​
Notification Style

​
notification_style
string
default:"overlay"
Controls how desktop notifications appear.Options:
  • "overlay" — Large, visible banners using native OS APIs (JXA Cocoa overlay on macOS, Windows Forms popup on WSL/MSYS2). Clicking focuses your terminal.
  • "standard" — System notifications using terminal-notifier / osascript on macOS, Windows toast on WSL/MSYS2.
Overlay notifications appear on all screens and are more visible than standard system notifications.
CLI commands: 
peon notifications overlay    # Use large overlay banners
peon notifications standard   # Use system notifications
Example: 
{
  "notification_style": "overlay"
}
On macOS, install terminal-notifier for richer standard notifications:
brew install terminal-notifier
With terminal-notifier, clicking a standard notification automatically focuses your terminal (supports Ghostty, Warp, iTerm2, Zed, Terminal.app).

​
Overlay Theme (macOS)

​
overlay_theme
string
default:"null"
Choose a visual theme for overlay notifications on macOS.Options:
  • "jarvis" — Circular HUD with rotating arcs, graduation ticks, and progress ring
  • "glass" — Glassmorphism panel with accent color bar, progress line, and timestamp
  • "sakura" — Zen garden with bonsai tree and animated cherry blossom petals
  • Omit or set to null for the default overlay theme
macOS only.
Example: 
{
  "notification_style": "overlay",
  "overlay_theme": "jarvis"
}

​
Notification Position

​
notification_position
string
default:"top-center"
Where overlay notifications appear on screen.Options:
  • "top-left"
  • "top-center"
  • "top-right"
  • "bottom-left"
  • "bottom-center"
  • "bottom-right"
CLI commands: 
peon notifications position              # Show current position
peon notifications position top-right    # Set to top-right
Example: 
{
  "notification_position": "top-right"
}

​
Auto-Dismiss Time

​
notification_dismiss_seconds
number
default:"4"
Auto-dismiss overlay notifications after N seconds.Set to 0 for persistent notifications that require a click to dismiss.
CLI commands: 
peon notifications dismiss        # Show current dismiss time
peon notifications dismiss 6      # Set to 6 seconds
peon notifications dismiss 0      # Persistent (click to dismiss)
Example: 
{
  "notification_dismiss_seconds": 6
}

​
Notification Title Override

​
notification_title_override
string
default:""
Override the project name shown in notification titles.When empty, the project name is auto-detected from:
  1. .peon-label file in project root
  2. project_name_map config key
  3. Git repository name
  4. Directory name
Set a custom label to override auto-detection.
CLI commands: 
peon notifications label                  # Show current label
peon notifications label "My Project"     # Set custom label
peon notifications label reset            # Clear override
Example: 
{
  "notification_title_override": "Client Portal"
}

​
Project Name Map

​
project_name_map
object
default:"{}"
Map directory paths to custom project labels for notifications.Keys are path patterns (exact paths, not globs). Values are display names.Checked before falling back to git repo name or directory name, but after notification_title_override.
Example: 
{
  "project_name_map": {
    "/home/user/work/client-a": "Client A",
    "/home/user/work/client-b": "Client B",
    "/home/user/personal/side-project": "Side Project"
  }
}

​
Notification Templates

​
notification_templates
object
default:"{}"
Custom message format strings for notification events.Keys:
  • stop — Task completion
  • permission — Permission request
  • error — Tool/command error
  • idle — Session idle
  • question — Agent needs input
Available variables:
  • {project} — Project name
  • {summary} — Event summary
  • {tool_name} — Tool name (for permission events)
  • {status} — Event status
  • {event} — Event type
When a template is not set, the default is "{project}".
CLI commands: 
peon notifications template                          # Show all templates
peon notifications template stop                     # Show single template
peon notifications template stop "{project}: done"   # Set template
peon notifications template --reset                  # Clear all templates
Example: 
{
  "notification_templates": {
    "stop": "{project}: {summary}",
    "permission": "{project}: {tool_name} needs approval",
    "error": "{project}: error in {tool_name}",
    "idle": "{project}: waiting for input",
    "question": "{project}: {summary}"
  }
}

​
Mobile Notifications

​
mobile_notify
object
default:"{}"
Configuration for push notifications to your phone.Supports three services:
  • ntfy.sh (free, no account needed)
  • Pushover (paid, one-time fee)
  • Telegram (free, requires bot setup)
Mobile notifications fire on every event regardless of window focus. They’re independent from desktop notifications and sounds.

​
ntfy.sh (Free)

CLI setup: 
peon mobile ntfy my-peon-notifications
Manual config: 
{
  "mobile_notify": {
    "enabled": true,
    "service": "ntfy",
    "topic": "my-peon-notifications",
    "server": "https://ntfy.sh",
    "token": ""
  }
}
​
mobile_notify.enabled
boolean
default:"true"
Enable or disable mobile push notifications.
​
mobile_notify.service
string
Push notification service to use.Options:
  • "ntfy" — ntfy.sh
  • "pushover" — Pushover
  • "telegram" — Telegram
​
mobile_notify.topic
string
ntfy.sh topic name.Choose a unique topic (e.g., my-peon-notifications) and subscribe to it in the ntfy mobile app.ntfy only.
​
mobile_notify.server
string
default:"https://ntfy.sh"
ntfy server URL.Use https://ntfy.sh for the public server, or specify a self-hosted instance.ntfy only.
​
mobile_notify.token
string
default:""
ntfy authentication token (optional).Required if your topic is protected with ACLs. Leave empty for public topics.ntfy only.

​
Pushover

CLI setup: 
peon mobile pushover <user_key> <app_token>
Manual config: 
{
  "mobile_notify": {
    "enabled": true,
    "service": "pushover",
    "user_key": "your-user-key",
    "app_token": "your-app-token"
  }
}
​
mobile_notify.user_key
string
Pushover user key.Find this in your Pushover dashboard.Pushover only.
​
mobile_notify.app_token
string
Pushover application token.Create an application in your Pushover dashboard to get a token.Pushover only.

​
Telegram

CLI setup: 
peon mobile telegram <bot_token> <chat_id>
Manual config: 
{
  "mobile_notify": {
    "enabled": true,
    "service": "telegram",
    "bot_token": "your-bot-token",
    "chat_id": "your-chat-id"
  }
}
​
mobile_notify.bot_token
string
Telegram bot token.Create a bot via @BotFather to get a token.Telegram only.
​
mobile_notify.chat_id
string
Telegram chat ID.Send a message to your bot and visit https://api.telegram.org/bot<token>/getUpdates to find your chat ID.Telegram only.

​
Mobile CLI Commands

peon mobile on                # Enable mobile notifications
peon mobile off               # Disable mobile notifications
peon mobile status            # Show current config
peon mobile test              # Send a test notification

Build docs developers (and LLMs) love

Get started for freeTalk to us