# Claude-notify
A simple, cross-platform notification system to alert you when Claude needs your attention.
## Features
- 🖥️ **Cross-platform support**: Works on macOS, Linux, and Windows
- 🔔 **Native notifications**: Uses system-native notification methods when available
- 🪝 **Claude Code hooks**: Integrates seamlessly with Claude's hook system
- ⚙️ **Configurable**: Customize notification preferences
- 🎯 **Simple CLI**: Easy-to-use command-line interface
- 🔄 **Watch mode**: Continuous monitoring with periodic notifications
- 🚨 **Smart alerts**: Critical notifications for potentially destructive operations
- 📁 **Project identification**: All notifications include project name and path
## Installation
### From Source
```bash
# Clone the repository
git clone https://github.com/yourusername/claude-notify.git
cd claude-notify
# Install dependencies
pip install -r requirements.txt
# Install the package
pip install -e .
```
### Using pip (when published)
```bash
pip install claude-notify
```
## Usage
### Claude Code Hook Integration (Recommended)
Claude-notify can be integrated directly with Claude Code as a hook to notify you when Claude needs attention or performs certain actions.
#### Setting up as a Claude Hook
You can configure claude-notify as a hook in two ways:
**Option 1: Using Claude's `/hooks` command** (Recommended)
```bash
# In Claude Code, simply run:
/hooks
# This will automatically add claude-notify hooks for Notification and Stop events
```
**Option 2: Manual configuration**
Add to your Claude settings file (`~/.claude/settings.json` or `.claude/settings.json` in your project):
```json
{
"hooks": {
"Notification": [
{
"matcher": ".*",
"hooks": [
{
"type": "command",
"command": "claude-notify hook"
}
]
}
],
"Stop": [
{
"matcher": ".*",
"hooks": [
{
"type": "command",
"command": "claude-notify hook"
}
]
}
],
"PreToolUse": [
{
"matcher": "(Bash|Write|Edit|MultiEdit)",
"hooks": [
{
"type": "command",
"command": "claude-notify hook"
}
]
}
]
}
}
```
This configuration will:
- Notify you when Claude finishes responding (Stop event)
- Alert you before Claude uses potentially destructive tools (Bash, Write, Edit, MultiEdit)
- Show the project name in ALL notification titles and full project path in ALL messages
#### Available Hook Events
- **PreToolUse**: Before Claude uses a tool (can be used to review/block actions)
- **PostToolUse**: After a tool completes successfully
- **Notification**: When Claude sends a notification
- **Stop**: When Claude finishes responding
- **SubagentStop**: When a Claude subagent completes
#### Testing Hook Integration
```bash
# Test hook with sample data (includes project path extraction)
claude-notify hook --test # Reads from test.json
# Test project path extraction
python examples/test-project-path.py
# Test with specific event type
echo '{"tool_name": "Bash", "tool_input": {"command": "ls"}}' | claude-notify hook --event-type PreToolUse
# Hook command options:
# --event-type, -e: Override event type detection
# --test, -t: Read from test.json instead of stdin
```
#### Project Path Display
For ALL hook events, claude-notify automatically extracts and displays:
- **Project name** in the notification title (e.g., "Claude Tool Request - my-project", "Claude Response Complete - my-project")
- **Full project path** in the notification message (e.g., "Project: my-project (/home/user/projects/my-project)")
This helps you identify which Claude session/project needs your attention when working on multiple projects, regardless of the event type.
### Manual Usage
#### Send a notification
```bash
# Basic notification
claude-notify send
# Custom notification
claude-notify send --title "Custom Title" --message "Custom message" --urgency critical
# Without sound
claude-notify send --no-sound
```
#### Watch mode
Monitor Claude sessions for activity that requires your attention:
```bash
# Monitor current project (checks every 30 seconds)
claude-notify watch
# Monitor all Claude projects
claude-notify watch --all-projects
# Custom check interval with verbose output
claude-notify watch --interval 10 --verbose
# Monitor specific project
cd /path/to/project && claude-notify watch
```
Watch mode features:
- **Real-time monitoring** of Claude transcript files
- **Smart detection** of when Claude needs your input
- **Project-aware** notifications showing which project needs attention
- **Pattern matching** for questions, waiting states, and errors
- **One-time notifications** per session (won't spam you)
### Configuration
```bash
# Show current configuration
claude-notify config show
# Set configuration values
claude-notify config set timeout 15
claude-notify config set sound false
claude-notify config set urgency critical
# Reset to defaults
claude-notify config reset
```
### System check
Check if your system is properly configured:
```bash
claude-notify check
```
## Configuration Options
Configuration is stored in:
- Linux/macOS: `~/.config/claude-notify/config.yaml`
- Windows: `%APPDATA%\claude-notify\config.yaml`
Available options:
- `timeout`: Notification display duration in seconds (default: 10)
- `sound`: Play notification sound (default: true)
- `urgency`: Notification urgency level - low, normal, critical (default: normal)
- `interval`: Watch mode check interval in seconds (default: 300)
- `title`: Default notification title
- `message`: Default notification message
## Platform-specific Notes
### macOS
- Uses native `osascript` for notifications
- Sound support included
### Linux
- Requires `notify-send` (usually part of `libnotify-bin` package)
- Install with: `sudo apt-get install libnotify-bin` (Debian/Ubuntu)
- Falls back to Python plyer if notify-send is not available
### Windows
- Uses PowerShell for native Windows 10+ toast notifications
- Falls back to Python plyer if PowerShell method fails
## Development
```bash
# Install in development mode
pip install -e .
# Run tests (when implemented)
python -m pytest
```
## License
MIT License - see LICENSE file for details
Raw data
{
"_id": null,
"home_page": "https://github.com/jamez01/claude-notify",
"name": "claude-notify",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.7",
"maintainer_email": null,
"keywords": "claude, ai, notifications, hooks, cross-platform, desktop",
"author": "jamez01",
"author_email": "jamez01 <james@example.com>",
"download_url": "https://files.pythonhosted.org/packages/d9/3d/336bc63cf4a46ad5d496d5cdb530051b2fda29affdd350ef73f1d54eab93/claude_notify-0.1.1.tar.gz",
"platform": null,
"description": "# Claude-notify\n\nA simple, cross-platform notification system to alert you when Claude needs your attention.\n\n## Features\n\n- \ud83d\udda5\ufe0f **Cross-platform support**: Works on macOS, Linux, and Windows\n- \ud83d\udd14 **Native notifications**: Uses system-native notification methods when available\n- \ud83e\ude9d **Claude Code hooks**: Integrates seamlessly with Claude's hook system\n- \u2699\ufe0f **Configurable**: Customize notification preferences\n- \ud83c\udfaf **Simple CLI**: Easy-to-use command-line interface\n- \ud83d\udd04 **Watch mode**: Continuous monitoring with periodic notifications\n- \ud83d\udea8 **Smart alerts**: Critical notifications for potentially destructive operations\n- \ud83d\udcc1 **Project identification**: All notifications include project name and path\n\n## Installation\n\n### From Source\n\n```bash\n# Clone the repository\ngit clone https://github.com/yourusername/claude-notify.git\ncd claude-notify\n\n# Install dependencies\npip install -r requirements.txt\n\n# Install the package\npip install -e .\n```\n\n### Using pip (when published)\n\n```bash\npip install claude-notify\n```\n\n## Usage\n\n### Claude Code Hook Integration (Recommended)\n\nClaude-notify can be integrated directly with Claude Code as a hook to notify you when Claude needs attention or performs certain actions.\n\n#### Setting up as a Claude Hook\n\nYou can configure claude-notify as a hook in two ways:\n\n**Option 1: Using Claude's `/hooks` command** (Recommended)\n```bash\n# In Claude Code, simply run:\n/hooks\n# This will automatically add claude-notify hooks for Notification and Stop events\n```\n\n**Option 2: Manual configuration**\n\nAdd to your Claude settings file (`~/.claude/settings.json` or `.claude/settings.json` in your project):\n\n```json\n{\n \"hooks\": {\n \"Notification\": [\n {\n \"matcher\": \".*\",\n \"hooks\": [\n {\n \"type\": \"command\",\n \"command\": \"claude-notify hook\"\n }\n ]\n }\n ],\n \"Stop\": [\n {\n \"matcher\": \".*\",\n \"hooks\": [\n {\n \"type\": \"command\",\n \"command\": \"claude-notify hook\"\n }\n ]\n }\n ],\n \"PreToolUse\": [\n {\n \"matcher\": \"(Bash|Write|Edit|MultiEdit)\",\n \"hooks\": [\n {\n \"type\": \"command\",\n \"command\": \"claude-notify hook\"\n }\n ]\n }\n ]\n }\n}\n```\n\nThis configuration will:\n- Notify you when Claude finishes responding (Stop event)\n- Alert you before Claude uses potentially destructive tools (Bash, Write, Edit, MultiEdit)\n- Show the project name in ALL notification titles and full project path in ALL messages\n\n#### Available Hook Events\n\n- **PreToolUse**: Before Claude uses a tool (can be used to review/block actions)\n- **PostToolUse**: After a tool completes successfully\n- **Notification**: When Claude sends a notification\n- **Stop**: When Claude finishes responding\n- **SubagentStop**: When a Claude subagent completes\n\n#### Testing Hook Integration\n\n```bash\n# Test hook with sample data (includes project path extraction)\nclaude-notify hook --test # Reads from test.json\n\n# Test project path extraction\npython examples/test-project-path.py\n\n# Test with specific event type\necho '{\"tool_name\": \"Bash\", \"tool_input\": {\"command\": \"ls\"}}' | claude-notify hook --event-type PreToolUse\n\n# Hook command options:\n# --event-type, -e: Override event type detection\n# --test, -t: Read from test.json instead of stdin\n```\n\n#### Project Path Display\n\nFor ALL hook events, claude-notify automatically extracts and displays:\n- **Project name** in the notification title (e.g., \"Claude Tool Request - my-project\", \"Claude Response Complete - my-project\")\n- **Full project path** in the notification message (e.g., \"Project: my-project (/home/user/projects/my-project)\")\n\nThis helps you identify which Claude session/project needs your attention when working on multiple projects, regardless of the event type.\n\n### Manual Usage\n\n#### Send a notification\n\n```bash\n# Basic notification\nclaude-notify send\n\n# Custom notification\nclaude-notify send --title \"Custom Title\" --message \"Custom message\" --urgency critical\n\n# Without sound\nclaude-notify send --no-sound\n```\n\n#### Watch mode\n\nMonitor Claude sessions for activity that requires your attention:\n\n```bash\n# Monitor current project (checks every 30 seconds)\nclaude-notify watch\n\n# Monitor all Claude projects\nclaude-notify watch --all-projects\n\n# Custom check interval with verbose output\nclaude-notify watch --interval 10 --verbose\n\n# Monitor specific project\ncd /path/to/project && claude-notify watch\n```\n\nWatch mode features:\n- **Real-time monitoring** of Claude transcript files\n- **Smart detection** of when Claude needs your input\n- **Project-aware** notifications showing which project needs attention\n- **Pattern matching** for questions, waiting states, and errors\n- **One-time notifications** per session (won't spam you)\n\n### Configuration\n\n```bash\n# Show current configuration\nclaude-notify config show\n\n# Set configuration values\nclaude-notify config set timeout 15\nclaude-notify config set sound false\nclaude-notify config set urgency critical\n\n# Reset to defaults\nclaude-notify config reset\n```\n\n### System check\n\nCheck if your system is properly configured:\n\n```bash\nclaude-notify check\n```\n\n## Configuration Options\n\nConfiguration is stored in:\n- Linux/macOS: `~/.config/claude-notify/config.yaml`\n- Windows: `%APPDATA%\\claude-notify\\config.yaml`\n\nAvailable options:\n- `timeout`: Notification display duration in seconds (default: 10)\n- `sound`: Play notification sound (default: true)\n- `urgency`: Notification urgency level - low, normal, critical (default: normal)\n- `interval`: Watch mode check interval in seconds (default: 300)\n- `title`: Default notification title\n- `message`: Default notification message\n\n## Platform-specific Notes\n\n### macOS\n- Uses native `osascript` for notifications\n- Sound support included\n\n### Linux\n- Requires `notify-send` (usually part of `libnotify-bin` package)\n- Install with: `sudo apt-get install libnotify-bin` (Debian/Ubuntu)\n- Falls back to Python plyer if notify-send is not available\n\n### Windows\n- Uses PowerShell for native Windows 10+ toast notifications\n- Falls back to Python plyer if PowerShell method fails\n\n## Development\n\n```bash\n# Install in development mode\npip install -e .\n\n# Run tests (when implemented)\npython -m pytest\n```\n\n## License\n\nMIT License - see LICENSE file for details\n\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Cross-platform notification system for Claude Code hooks with intelligent project detection",
"version": "0.1.1",
"project_urls": {
"Homepage": "https://github.com/jamez01/claude-notify",
"Issues": "https://github.com/jamez01/claude-notify/issues",
"Repository": "https://github.com/jamez01/claude-notify.git"
},
"split_keywords": [
"claude",
" ai",
" notifications",
" hooks",
" cross-platform",
" desktop"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "28a38d37c60508484de107c6448af8ee2113e00428bca645336f2694a0513ebf",
"md5": "738361bb518866da3a1f6dd6f7d035f8",
"sha256": "a12e08b0cbd2a073b157533842cfcdaa8a9789f7e31fd673c18616a82234646c"
},
"downloads": -1,
"filename": "claude_notify-0.1.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "738361bb518866da3a1f6dd6f7d035f8",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.7",
"size": 16451,
"upload_time": "2025-07-08T15:56:02",
"upload_time_iso_8601": "2025-07-08T15:56:02.553335Z",
"url": "https://files.pythonhosted.org/packages/28/a3/8d37c60508484de107c6448af8ee2113e00428bca645336f2694a0513ebf/claude_notify-0.1.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "d93d336bc63cf4a46ad5d496d5cdb530051b2fda29affdd350ef73f1d54eab93",
"md5": "b9cd974fde6e3d9a2b04183d1c81441c",
"sha256": "8cf045c0cfa01188392c234869d4b04006f66c16f3f6a8fc07d6f9d21dd29414"
},
"downloads": -1,
"filename": "claude_notify-0.1.1.tar.gz",
"has_sig": false,
"md5_digest": "b9cd974fde6e3d9a2b04183d1c81441c",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.7",
"size": 23317,
"upload_time": "2025-07-08T15:56:03",
"upload_time_iso_8601": "2025-07-08T15:56:03.789874Z",
"url": "https://files.pythonhosted.org/packages/d9/3d/336bc63cf4a46ad5d496d5cdb530051b2fda29affdd350ef73f1d54eab93/claude_notify-0.1.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-07-08 15:56:03",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "jamez01",
"github_project": "claude-notify",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"requirements": [
{
"name": "plyer",
"specs": [
[
">=",
"2.1"
]
]
},
{
"name": "click",
"specs": [
[
">=",
"8.1.0"
]
]
},
{
"name": "pyyaml",
"specs": [
[
">=",
"6.0"
]
]
}
],
"lcname": "claude-notify"
}
JSON
