Skip to main content
PeonPing sends visual notifications alongside sounds so you know when the agent needs attention — even if you’re in another app.

​
Notification Styles

Choose between two desktop notification styles:
Large, visible banners that appear on all screens.Technology:
  • macOS: JXA Cocoa overlay
  • WSL/MSYS2: Windows Forms popup
  • Linux: Custom implementation
Features:
  • Appears on top of all windows
  • Click to focus your terminal (Ghostty, Warp, iTerm2, Zed, Terminal.app)
  • iTerm2: clicks focus the correct tab/pane/window — not just the app
  • Customizable themes (macOS only)
  • Configurable position and auto-dismiss timing
Enable overlay style:
peon notifications overlay
Configuration:
{
  "notification_style": "overlay",
  "overlay_theme": "jarvis",
  "notification_position": "top-center",
  "notification_dismiss_seconds": 4
}

​
Overlay Themes (macOS)

Customize the appearance of overlay notifications with built-in themes:
Inspired by Iron Man’s JARVIS interface.Features:
  • Circular HUD with rotating arcs
  • Graduation ticks around the perimeter
  • Progress ring animation
  • Tech-forward aesthetic
Set theme:
peon notifications overlay
# Then edit config.json:
# "overlay_theme": "jarvis"
Modern glassmorphism design with blur effects.Features:
  • Frosted glass panel
  • Accent color bar on the left
  • Progress line at bottom
  • Timestamp display
  • Soft shadows and blur
Configuration:
{
  "overlay_theme": "glass"
}
Peaceful Japanese zen garden aesthetic.Features:
  • Bonsai tree illustration
  • Animated cherry blossom petals
  • Soft pastel colors
  • Calming, minimalist design
Best for: Distraction-free coding sessions
Simple, minimal overlay without custom styling.Set default:
{
  "overlay_theme": ""
}
Or omit the overlay_theme key entirely.

​
Positioning

Control where overlay notifications appear on screen: 
# View current position
peon notifications position

# Set position
peon notifications position top-left
peon notifications position top-center
peon notifications position top-right
peon notifications position bottom-left
peon notifications position bottom-center
peon notifications position bottom-right
Configuration: 
{
  "notification_position": "top-center"
}
Default: top-center

​
Auto-Dismiss Timing

Set how long notifications stay visible before automatically dismissing: 
# View current timing
peon notifications dismiss

# Set auto-dismiss to 8 seconds
peon notifications dismiss 8

# Persistent notifications (click to dismiss)
peon notifications dismiss 0
Configuration: 
{
  "notification_dismiss_seconds": 4
}
Default: 4 seconds
Set to 0: Notifications persist until clicked

​
Project Labels

Customize the project name shown in notification titles:

​
Auto-Detection Priority

  1. notification_title_override (config)
  2. .peon-label file in project root
  3. project_name_map (path pattern matching)
  4. Git repository name
  5. Directory name

​
Override for Specific Project

# Set label for current directory
peon notifications label "Client A Dashboard"

# Reset to auto-detection
peon notifications label reset

​
Map Paths to Labels

Define labels for multiple projects: 
{
  "project_name_map": {
    "/home/user/work/client-a": "Client A",
    "/home/user/personal/blog": "Personal Blog",
    "*/services": "Microservices"
  }
}
Pattern matching: Use * wildcards for flexible path rules

​
Create .peon-label File

Place a .peon-label file in your project root: 
echo "My Project" > .peon-label
This takes precedence over path mapping but is overridden by notification_title_override.

​
Message Templates

Customize notification text for each event type: 
# View current template
peon notifications template stop

# Set custom template
peon notifications template stop "{project}: Task finished"
peon notifications template permission "{project}: {tool_name} needs approval"
peon notifications template error "Error in {project}: {summary}"

# Reset to default
peon notifications template stop reset

​
Available Template Variables

VariableDescriptionAvailable In
{project}Project name (auto-detected or overridden)All events
{summary}Event summary or messageAll events
{tool_name}Name of the tool being usedpermission, stop
{status}Success/failure statusstop
{event}Event category (e.g., task.complete)All events

​
Event Types

KeyWhen It Fires
stopAgent finishes task
permissionTool needs approval
errorTool or command fails
idleAgent waiting for input
questionAgent has a question

​
Configuration

{
  "notification_templates": {
    "stop": "{project}: {summary}",
    "permission": "{project}: {tool_name} needs approval",
    "error": "{project}: Error — {summary}",
    "idle": "{project}: Waiting for input",
    "question": "{project}: {summary}"
  }
}

​
Independent Controls

Notifications, sounds, and mobile push work independently:

​
Common Combinations

# Sounds only (no visual distractions)
peon notifications off

# Silent mode with popups
peon pause
# (desktop_notifications remains true)

# Mobile only (working remotely)
peon pause
peon notifications off
peon mobile on

# Complete silence
peon pause
peon notifications off
peon mobile off

​
Mobile Notifications

Get push notifications on your phone when tasks finish or need attention.

​
Quick Start (ntfy.sh — free, no account)

  1. Install ntfy app on your phone
  2. Subscribe to a unique topic (e.g., my-peon-notifications)
  3. Run: 
    peon mobile ntfy my-peon-notifications

​
Supported Services

Free, open-source, no account required
peon mobile ntfy your-unique-topic
Security tip: Use a long, random topic name to prevent others from subscribing

​
Mobile 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
Behavior: Mobile notifications fire on every event regardless of window focus — they’re independent from desktop notifications and sounds.

​
Testing Notifications

Send a test notification to verify your setup: 
peon notifications test
This sends a sample notification using your current style (overlay or standard) and configuration.

​
Related Configuration

Sound Events

CESP event categories and when sounds play

Sound Packs

Browse 165+ packs and customize notification themes

Build docs developers (and LLMs) love

Get started for freeTalk to us