Local-first Discord notifications for Claude Code sessions - stay informed about your coding progress

Get real-time Discord notifications when Claude completes tasks, needs input, or makes progress on your projects. Simple local installation by default, with optional global setup for advanced multi-project workflows.

• 🏠 Local-first architecture - Self-contained installation per project
• 🌐 Global option available - Multi-project setup for advanced users
• 🎯 Project-scoped notifications - Each project controls its own Discord integration
• 🔔 Smart notification types - Input needed, work in progress, session complete
• 🧵 Thread support - Organize notifications by session with Discord threads
• ⚡ Easy control - Simple slash commands for setup and management
• 🛡️ Non-destructive setup - Preserves existing Claude Code configuration
• 🔧 Configurable webhooks - No hardcoded URLs, bring your own webhook
• 🐍 Python-enhanced commands - Unified architecture with consistent error handling (v0.4.0)

Perfect for single projects - everything installs to your current project with automatic setup:

cd your-project
curl -fsSL https://raw.githubusercontent.com/jubalm/claude-code-discord/main/install.sh | bash

New in v0.4.0: Python-enhanced slash commands with unified architecture, improved error handling, and consistent user experience!

Also in v0.3.2: Automatic hook registration! Discord hooks are now automatically registered in .claude/settings.json during local installation.

For managing multiple projects with shared Discord integration:

curl -fsSL https://raw.githubusercontent.com/jubalm/claude-code-discord/main/install.sh | bash -s -- --global

git clone https://github.com/jubalm/claude-code-discord.git
cd claude-code-discord
chmod +x install.sh
./install.sh              # Local installation
./install.sh --global     # Global installation

• Claude Code installed (global installation only)
• Python 3 (universally available)
• curl or wget for installation
• Discord webhook URL

1. Go to your Discord server settings
2. Navigate to Integrations → Webhooks
3. Click New Webhook or use an existing one
4. Copy the webhook URL

After installation, configure Discord integration:

# Setup Discord integration
/user:discord:setup https://discord.com/api/webhooks/YOUR_WEBHOOK_URL

# Enable notifications
/user:discord:start

# Check installation type
/user:discord:status

You'll automatically receive Discord notifications when:

• 🔔 Claude needs input (blue notifications)
• ⚡ Claude makes progress (gold notifications after tool usage)
• ✅ Claude completes session (green notifications)

Python-Enhanced Slash Commands (v0.4.0) - Now with unified architecture, improved error handling, and consistent user experience:

• Comprehensive error handling - User-friendly messages for all edge cases
• Consistent formatting - Uniform output across all commands
• Better validation - Robust webhook URL and argument validation
• Installation detection - Automatic local vs global installation detection
• Safe configuration - Backup creation and selective updates

Local Installation: Each project is completely independent:

# Project A - local installation
cd /path/to/project-a
curl -fsSL .../install.sh | bash
/user:discord:setup https://discord.com/api/webhooks/DEV_WEBHOOK

# Project B - separate local installation
cd /path/to/project-b  
curl -fsSL .../install.sh | bash
/user:discord:setup https://discord.com/api/webhooks/TEST_WEBHOOK TOKEN THREAD_ID

Global Installation: Shared setup across projects:

# One-time global install
curl -fsSL .../install.sh | bash -s -- --global

# Then configure each project
cd project-a && /user:discord:setup DEV_WEBHOOK
cd project-b && /user:discord:setup TEST_WEBHOOK TOKEN THREAD_ID

For better organization, you can use Discord threads:

# Create a thread in Discord, copy its ID
/user:discord:start 1234567890123456789

# Or setup with thread from the beginning
/user:discord:setup YOUR_WEBHOOK_URL YOUR_AUTH_TOKEN 1234567890123456789

Local Installation (Recommended):

# Commit Discord integration for team sharing
git add .claude/hooks/ .claude/commands/ .claude/settings.json
git commit -m "Add Discord notifications for team"

# .gitignore - exclude personal webhooks
echo ".claude/discord-state.json" >> .gitignore
echo ".claude/settings.json.backup*" >> .gitignore

# Team members just need to configure their webhook
/user:discord:setup https://discord.com/api/webhooks/THEIR_WEBHOOK
/user:discord:start

Global Installation:

# Team lead sets up global installation
curl -fsSL .../install.sh | bash -s -- --global

# Commit project hooks only
git add .claude/settings.json
git commit -m "Add Discord hooks config"

# Each team member configures their webhook per project
/user:discord:setup THEIR_WEBHOOK
/user:discord:start

1. Check if Discord integration is active:

   /user:discord:status

2. Verify configuration files exist:

   ls -la .claude/
   # Should show: discord-state.json, settings.json

3. Test webhook manually:

   curl -X POST "YOUR_WEBHOOK_URL" \
     -H "Content-Type: application/json" \
     -d '{"content": "Test notification"}'

4. Check Claude Code logs:

   tail -f ~/.claude/discord-notifications.log

1. Check installation type and verify scripts:

   /user:discord:status  # Shows Local or Global installation
   
   # For local installation
   ls -la .claude/hooks/*discord*.py
   
   # For global installation  
   ls -la ~/.claude/hooks/*discord*.py

2. Test script manually:

   # Local
   echo '{}' | .claude/hooks/stop-discord.py
   
   # Global
   echo '{}' | ~/.claude/hooks/stop-discord.py

3. Fix permissions if needed:

   chmod +x .claude/hooks/*discord*.py      # Local
   chmod +x ~/.claude/hooks/*discord*.py   # Global

1. Verify commands based on installation type:

   # Local
   ls .claude/commands/discord/
   
   # Global
   ls ~/.claude/commands/discord/

2. Restart Claude Code to reload commands

3. Check installation type:

   /user:discord:status

Remove Discord integration from current project:

curl -fsSL https://raw.githubusercontent.com/jubalm/claude-code-discord/main/uninstall.sh | bash

# Or use slash command
/user:discord:remove

Remove global Discord integration (affects all projects):

curl -fsSL https://raw.githubusercontent.com/jubalm/claude-code-discord/main/uninstall.sh | bash -s -- --global

# Local installation
rm -rf .claude/hooks/*discord*.py .claude/commands/discord/
rm -f .claude/discord-state.json

# Global installation  
rm -f ~/.claude/hooks/*discord*.py
rm -rf ~/.claude/commands/discord

1. Fork the repository
2. Create a feature branch: git checkout -b feature-name
3. Make your changes
4. Test thoroughly
5. Submit a pull request

MIT License - see LICENSE file for details.

• Claude Code Documentation
• Discord Webhooks Guide
• Project Documentation

Happy coding with Discord notifications! 🚀