Nyantifier

A lightweight macOS notification CLI tool with custom app icon support.

Features

• Send notifications from the command line
• Custom app icon (shown in notification center)
• Image attachments (thumbnail in notification)
• Click to activate specified app
• Notification grouping (same group replaces previous)

Requirements

• macOS 11.0 or later
• Xcode Command Line Tools

Installation

Build from source

1. Clone the repository:

git clone https://github.com/shivaduke28/nyantifier.git
cd nyantifier

2. (Optional) Add your custom icons to icons/ directory:

cp /path/to/your/icon.png icons/myapp.png
cp /path/to/another/icon.png icons/another.png

3. Build:

make build

This will create:

• dist/myapp.app and bin/myapp for icons/myapp.png
• dist/another.app and bin/another for icons/another.png
• If no icons are provided, dist/nyantifier.app and bin/nyantifier will be created without an icon.

4. Add to your PATH (e.g. in ~/.zprofile):

export PATH="/path/to/nyantifier/bin:$PATH"

5. Grant notification permission:
   • Run the command once (e.g. myapp -title "test")
   • Go to System Settings → Notifications → myapp
   • Enable Allow Notifications

Usage

nyantifier [options]

Options

Option	Description
-title <string>	Notification title
-subtitle <string>	Notification subtitle
-message <string>	Notification message
-activate <bundle>	Bundle ID of app to activate on click
-group <string>	Group ID (same group replaces previous notification)
-image <path>	Path to image file to attach (shows as thumbnail)
-sound <type>	Sound type: default or none (default: default)
-truncate <int>	Truncate message to specified length (adds "..." if truncated)
-version	Show version
-help	Show help message

Examples

# Simple notification
nyantifier -title "Hello" -message "World"

# With app activation on click
nyantifier -title "Build Done" -message "Click to open VSCode" \
  -activate "com.microsoft.VSCode"

# With image attachment
nyantifier -title "Screenshot" -message "New capture" \
  -image ~/Desktop/screenshot.png

# Grouped notification (replaces previous with same group)
nyantifier -title "Progress" -message "50%" -group "build-progress"
nyantifier -title "Progress" -message "100%" -group "build-progress"

Why Nyantifier?

Nyantifier is inspired by terminal-notifier. We built Nyantifier because:

• Custom app icon on macOS 11+: macOS 11 (Big Sur) changed how notification icons work, making it difficult to customize app icons with existing tools. Nyantifier solves this by building as a standalone .app bundle with your own icon.
• Lightweight Swift implementation: Simple, single-file Swift implementation (~250 lines) with no external dependencies.
• Easy icon customization: Just drop your PNG file and rebuild - no need to modify source code.

Use with Claude Code

Get notified when Claude Code stops, waits for permission, or asks a question.

See examples/claude-code/ for hook script and settings.

Troubleshooting

Notification permission dialog appears when running from terminal

After building, if you run the command from the terminal and see a "Allow notifications?" dialog, try opening the .app file directly first:

open dist/myapp.app

This registers the app with macOS's notification system. After that, running the command from terminal should work without the dialog.

License

MIT License