Skip to content

installation.md

Latest commit

 

History

History
203 lines (142 loc) · 6.13 KB

installation.md

File metadata and controls

203 lines (142 loc) · 6.13 KB
Raw

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)
  • Slack or Discord webhook messages when channels are configured
  • Codex or Claude usage crosses configured thresholds or resets

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 AI Coding Agents

Install code-notify with npm first. Prefer npm over curl or git clone so installs are tracked through the npm package and can be updated with cn update.

npm install -g code-notify
cn on all
cn test
cn status

Expected result: cn test should show a desktop notification, and cn status should show enabled tools.

If npm is unavailable, use the script installer in the platform sections below.

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

npm Install-Time Behavior

The npm package is published with GitHub Actions Trusted Publisher and npm provenance.

postinstall is intentionally narrow:

  • It only runs on global npm installs.
  • On macOS/Linux, it runs a quiet legacy Claude hook repair so older claude-notify paths migrate to Code-Notify.
  • On Windows, it bootstraps the local PowerShell wrapper with -Silent -Force -SkipShellSetup.
  • It does not enable notifications, configure Slack/Discord, or start usage watching.

Set CODE_NOTIFY_SKIP_POSTINSTALL=1 before installing if you want to skip these helpers.

Optional Slack/Discord Delivery

cn channels add slack https://hooks.slack.com/services/...
cn channels add discord https://discord.com/api/webhooks/...
cn channels test all

Webhook URLs are stored locally and are redacted in status output.

Optional Usage Alerts

cn usage setup --watch
cn usage status

Usage alerts currently support Codex and Claude daily (5h) and weekly (7d) windows. Low-usage warnings use normal Code-Notify delivery. Token reset alerts are separate and can use their own voice/sound controls with cn usage reset-alerts .... Reset voice messages identify the window, such as Codex token daily limit reset or Codex token weekly limit reset.

cn usage setup --watch enables usage alerts, sets the default 20% and 10% warning thresholds, enables distinct reset voice/sound, and starts a background watcher on macOS/Linux. cn usage check runs once and exits. Use cn usage watch stop to stop the watcher.

They use existing local login state from ~/.codex/auth.json and ~/.claude/.credentials.json. Code-Notify does not start provider login flows. Background watching starts only when you run cn usage setup --watch or cn usage watch start.

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)
  • ~/.config/code-notify/channels.json - Slack/Discord channel config (if configured)
  • ~/.config/code-notify/usage.json - Usage alert config (if enabled)
  • ~/.config/code-notify/usage-state.json - Usage alert dedupe state (if alerts have fired)

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 channels Configure Slack/Discord delivery
cn usage Configure Codex/Claude usage alerts
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.