shelldone

Cross-platform terminal notification system for long-running commands. Get desktop notifications, sounds, and external alerts (Slack, Discord, Telegram, and more) when your builds, deploys, and tests finish.

Works with bash and zsh on macOS, Linux, WSL, and Windows. Notify via desktop popup, sound, voice, Slack, Discord, Telegram, Email, WhatsApp, or webhook. Integrates with AI CLIs: Claude Code, Codex, Gemini, Copilot, Cursor, and Aider.

Table of Contents

• Features
• Quick Start
• Installation
• Usage
• Configuration
• External Notifications
• Commands Reference
• Platform Support
• Alternatives
• Contributing
• License

Documentation

Document	Description
Commands Reference	Every CLI command with detailed ASCII flowcharts
Architecture	System design, notification flow, module loading, state management
External Channels	Setup guides for Slack, Discord, Telegram, Email, WhatsApp, webhooks
Configuration	Full environment variable reference and config file format
Troubleshooting	Debug mode, common issues, and fixes

Features

• Desktop notifications on macOS, Linux, WSL, and Windows (Git Bash/MSYS2/Cygwin)
• Auto-notify for any command that runs longer than a configurable threshold (default: 10s)
• Sound alerts with customizable success/failure sounds (system sounds or custom file paths)
• Text-to-speech announcements (optional)
• External notifications via Slack, Discord, Telegram, Email, WhatsApp, or generic webhooks
• AI CLI integration - Claude Code, Codex CLI, Gemini CLI, Copilot CLI, Cursor (hook-based), plus Aider (wrapper)
• Smart focus detection - suppresses notifications when you're already looking at the terminal
• Glob-based exclusions - skip commands like npm*, ssh, vim, etc.
• Notification control - mute, toggle layers (sound/desktop/voice/channels), schedule quiet hours
• Shell completions for bash and zsh
• Zero dependencies - uses only built-in system tools (curl/wget optional for external channels)

Quick Start

# Clone and install
git clone https://github.com/nareshnavinash/shelldone.git
cd shelldone
./install.sh

# Verify your setup
shelldone status

# Send a test notification
shelldone test-notify

# Wrap any command
alert make build

After installation, commands running longer than 10 seconds automatically trigger notifications - no wrapper needed.

Installation

From Source (recommended)

git clone https://github.com/nareshnavinash/shelldone.git
cd shelldone
./install.sh

The install script detects your platform, makes scripts executable, adds shell integration to your rc files, and sets up hooks for all detected AI CLIs.

Make Install

make install                     # installs to /usr/local
make install PREFIX=~/.local     # installs to ~/.local

Homebrew (macOS/Linux)

brew tap nareshnavinash/tap
brew install shelldone

Debian/Ubuntu

# Add the GPG key and repository
curl -fsSL https://nareshnavinash.github.io/shelldone/KEY.gpg \
  | sudo gpg --dearmor -o /usr/share/keyrings/shelldone-archive-keyring.gpg
echo "deb [signed-by=/usr/share/keyrings/shelldone-archive-keyring.gpg] https://nareshnavinash.github.io/shelldone stable main" \
  | sudo tee /etc/apt/sources.list.d/shelldone.list
sudo apt update && sudo apt install shelldone

Scoop (Windows)

scoop bucket add shelldone https://github.com/nareshnavinash/scoop-bucket
scoop install shelldone

Chocolatey (Windows)

choco install shelldone

Manual Setup

Add to your .zshrc or .bashrc:

eval "$(shelldone init zsh)"    # for zsh
eval "$(shelldone init bash)"   # for bash

Or auto-configure everything (rc files + AI CLI hooks):

shelldone setup

Usage

alert <command> - Explicit Notifications

Wrap any command to get notified when it completes:

alert make build
alert npm test
alert ./deploy.sh production

The notification shows the command name, exit status icon, elapsed time, and exit code. The original exit code is preserved.

Automatic Notifications

After shell integration, any command running longer than the threshold (default: 10 seconds) triggers a notification automatically. No alert wrapper needed.

make build-all    # takes 5 minutes -> notification fires
ls                # instant -> no notification
vim file.txt      # excluded by default -> no notification

AI CLI Integration

shelldone can notify you when AI coding assistants finish their turn via native hook systems:

shelldone setup ai-hooks          # install hooks for all detected AI CLIs
shelldone setup claude-hook       # or install individually
shelldone toggle claude off       # toggle per AI CLI

Supports Claude Code, Codex CLI, Gemini CLI, Copilot CLI, and Cursor. Aider uses the alert wrapper: alert aider "fix the bug".

Notification Control

shelldone mute 30m               # mute for 30 minutes
shelldone unmute                  # resume
shelldone toggle sound off        # disable sound, keep desktop popups
shelldone toggle external off     # disable all external channels
shelldone schedule 22:00-08:00    # set quiet hours

Supported layers: desktop, sound, voice, slack, discord, telegram, email, whatsapp, webhook, external (group), claude, codex, gemini, copilot, cursor.

Configuration

All settings are environment variables. Set them before the eval line in your shell config:

export SHELLDONE_THRESHOLD=60
export SHELLDONE_SOUND_SUCCESS=Ping
export SHELLDONE_VOICE=true
eval "$(shelldone init zsh)"

Variable	Default	Description
SHELLDONE_ENABLED	true	Master on/off switch
SHELLDONE_AUTO	true	Auto-notify on/off
SHELLDONE_THRESHOLD	10	Seconds before auto-notify triggers
SHELLDONE_SOUND_SUCCESS	Glass / complete / Asterisk	Success sound (macOS / Linux / Windows)
SHELLDONE_SOUND_FAILURE	Sosumi / dialog-error / Hand	Failure sound (macOS / Linux / Windows)
SHELLDONE_VOICE	(off)	Set to true for TTS
SHELLDONE_FOCUS_DETECT	true	Suppress when terminal is focused
SHELLDONE_EXCLUDE	vim nvim vi nano less ...	Space-separated commands/globs to skip
SHELLDONE_QUIET_HOURS	(off)	Daily quiet hours (e.g., 22:00-08:00)

Full reference with all variables: docs/configuration.md

External Notifications

Send alerts to Slack, Discord, Telegram, Email, WhatsApp, or any webhook. External notifications fire even when the terminal is focused.

export SHELLDONE_SLACK_WEBHOOK="https://hooks.slack.com/services/T.../B.../xxx"
shelldone webhook test slack     # verify it works

Setup guides for all 6 channels: docs/external-channels.md

Commands Reference

Command	Description
shelldone init [bash|zsh]	Output shell init code (use with eval)
shelldone setup [all|ai-hooks|<ai>-hook]	Auto-configure rc files and/or AI CLI hooks
shelldone uninstall	Remove all shell integration and AI CLI hooks
shelldone status	Show diagnostic info: platform, tools, config, integration
shelldone test-notify	Send a test notification to all configured channels
shelldone sounds	List available system sounds for your platform
shelldone exclude [list|add|remove]	Manage auto-notify exclusion list
shelldone webhook [status|test <channel>]	Manage and test external notification channels
shelldone mute [duration]	Mute all notifications (e.g., 30m, 2h, 1h30m)
shelldone unmute	Resume notifications
shelldone toggle [layer [on|off]]	Toggle notification layers (sound, desktop, voice, channels)
shelldone schedule [HH:MM-HH:MM|off]	Set or clear daily quiet hours
shelldone test	Run the full verification test suite (452 tests)
shelldone version [--verbose]	Show version (add --verbose for platform details)
shelldone help	Show usage help

Detailed flowcharts for every command: docs/commands.md

Platform Support

Feature	macOS	Linux	WSL	Windows (Git Bash)
Desktop notifications	osascript	notify-send	BurntToast / WinRT	BurntToast / WinRT
Sound	afplay	paplay / aplay / mpv	powershell.exe	powershell.exe
TTS	say	espeak / spd-say	powershell.exe	powershell.exe
Focus detection	AppleScript	xdotool	--	--
Auto-notify	zsh + bash	zsh + bash	zsh + bash	bash
External notifications	All channels	All channels	All channels	All channels

macOS: No additional dependencies (osascript, afplay, say are built-in). Linux: libnotify-bin for desktop, pulseaudio-utils/alsa-utils for sound, espeak for TTS, xdotool for focus. WSL/Windows: BurntToast PowerShell module (recommended) or wsl-notify-send. External channels: curl or wget for HTTPS channels.

Uninstalling

shelldone uninstall     # interactive confirmation
./uninstall.sh          # or run the uninstall script
make uninstall          # or via make

Troubleshooting

Run shelldone status for quick diagnosis. For debug output: SHELLDONE_DEBUG=true alert echo hello.

Full troubleshooting guide: docs/troubleshooting.md

Testing

shelldone includes 452 tests covering unit, integration, and end-to-end scenarios.

bash test.sh          # from project root
shelldone test        # via the CLI

Alternatives

Feature	shelldone	undistract-me	noti	done (fish)
Auto-notify	Yes	Yes	Partial	Yes
macOS + Linux + WSL + Windows	Yes	No	Yes	No
External channels (6)	Yes	No	Partial	No
Zero dependencies	Yes	Yes	No (Go)	Yes
AI CLI integration (5 tools)	Yes	No	No	No
Sound + TTS	Yes	No	Partial	No
Mute / schedule / toggle	Yes	No	No	No

Contributing

1. Fork the repository
2. Create a feature branch: git checkout -b feature/my-feature
3. Make your changes
4. Run the test suite: bash test.sh (all 452 tests must pass)
5. Run ShellCheck: shellcheck bin/shelldone lib/*.sh hooks/*.sh
6. Commit and push
7. Open a pull request

See CONTRIBUTING.md for detailed guidelines.

License

MIT License. Copyright (c) 2026 Naresh Sekar. See LICENSE for details.