Skip to content

installation.md

Latest commit

 

History

History
170 lines (119 loc) · 3.87 KB

installation.md

File metadata and controls

170 lines (119 loc) · 3.87 KB

Code-Notify Installation Guide

This guide is designed for both humans and LLM agents. If you're an AI agent, follow the automated steps below.

Quick Overview

Code-Notify adds desktop notifications to Claude Code, Codex, and Gemini CLI. You'll get alerts when:

  • Tasks complete
  • Claude or Gemini needs your input
  • Voice announcements (macOS)

Codex currently exposes completion notifications through its notify hook. Approval and request_permissions prompts do not currently trigger Code-Notify through Codex.

Supported upgrade paths also repair stale claude-notify-style Claude hooks automatically when they are detected.

For LLM Agents

Execute these commands to install code-notify:

# 1. Clone the repository
git clone https://github.com/mylee04/code-notify.git /tmp/code-notify

# 2. Run the installer
chmod +x /tmp/code-notify/scripts/install.sh
/tmp/code-notify/scripts/install.sh

# 3. Reload shell
exec $SHELL

# 4. Enable notifications
cn on

# 5. Test it works
cn test

# 6. Clean up
rm -rf /tmp/code-notify

Verify Installation

After installation, confirm these work:

cn version    # Should show: code-notify version X.X.X
cn status     # Should show: Global notifications: ENABLED
cn test       # Should trigger a desktop notification

Enable Voice (macOS only)

cn voice on   # Follow prompts to select a voice
cn test       # Should hear + see notification

Project-Specific Setup

To enable notifications for a specific project only:

cd /path/to/your/project
cnp on        # Enable for this project
cnp status    # Verify

If Claude Code has not trusted the project yet, cnp on will warn that Claude may ignore project settings until the trust prompt is accepted.

Troubleshooting

If cn command not found:

# Add to PATH
export PATH="$HOME/.local/bin:$PATH"
# Or reload shell
exec $SHELL

If notifications don't appear:

# macOS: Install terminal-notifier for better notifications
brew install terminal-notifier

# Check status
cn status

Configuration Files

After installation, these files are created:

  • ~/.code-notify/ - Main installation directory
  • ~/.claude/settings.json - Hook configuration on the default Claude Code path
  • ~/.config/.claude/settings.json - Hook configuration on some Windows Claude Code setups
  • ~/.claude/notifications/voice-enabled - Voice setting (if enabled)

Uninstallation

# Disable notifications first
cn off

# Remove installation
rm -rf ~/.code-notify
rm -f ~/.local/bin/cn ~/.local/bin/cnp ~/.local/bin/code-notify
rm -rf ~/.claude/notifications

For Humans

macOS (Homebrew) - Recommended

brew tap mylee04/tools
brew install code-notify
cn on

Linux / WSL

curl -sSL https://raw.githubusercontent.com/mylee04/code-notify/main/scripts/install.sh | bash
exec $SHELL
cn on

npm (macOS / Linux / Windows)

npm install -g code-notify
cn on

macOS Embedded Terminals

If clicking a notification opens Terminal.app instead of your editor or IDE terminal, add a click-through mapping:

cn click-through add PhpStorm
cn test

Manual Installation

git clone https://github.com/mylee04/code-notify.git
cd code-notify
./scripts/install.sh

Quick Commands

Command What it does
cn on Enable notifications
cn off Disable notifications
cn test Send test notification
cn status Check current status
cn update Update code-notify
cn update check Check the latest release and show the update command
cn voice on Enable voice (macOS)
cnp on Enable for current project only

That's it! You'll now get notified when Claude Code completes tasks.