--- name: tmux-init-20a099009200 description: Set up tmux notification system for Claude Code sessions argument-hint: "[--uninstall] [--status]" allowed-tools: Bash, Read, Write, Edit --- # tmux-init Set up a notification system for Claude Code that sends native macOS notifications when sessions need attention, with click-to-navigate support for tmux panes. ## Usage ```bash /tmux-init # Install notification system /tmux-init --status # Check installation status /tmux-init --uninstall # Remove notification system ``` ## What Gets Installed 1. **Configuration** in `~/bin/`: - `hooks.json` - Webhook routing configuration 2. **Webhook service** (LaunchAgent): - Listens on port 9000 for notification requests - Auto-starts on login 3. **Shell environment** (added to ~/.zshrc): - `WS_TMUX_LOCATION` - Current tmux session:window.pane - `WS_TMUX_SESSION_NAME` - Current session name - `WS_TMUX_WINDOW_NAME` - Current window name 4. **Claude hooks** (added to ~/.claude/settings.json): - `Stop` hook - Calls `forge notify hook` when Claude finishes - `Notification` hook - Calls `forge notify hook` when Claude needs input 5. **Python CLI commands**: - `forge notify hook` - Sends notifications (called by Claude hooks) - `forge tmux go` - Navigates to tmux location (called by webhook on click) ## Prerequisites - macOS - tmux - Homebrew (for installing dependencies) ## Execution Instructions ### Parse Arguments ```bash UNINSTALL=false STATUS=false for arg in "$@"; do case "$arg" in --uninstall) UNINSTALL=true ;; --status) STATUS=true ;; esac done ``` ### If --status: Check Installation Status ```bash echo "=== Claude tmux Notification System Status ===" echo "" # Check dependencies echo "Dependencies:" command -v terminal-notifier &>/dev/null && echo " ✅ terminal-notifier" || echo " ❌ terminal-notifier (missing)" command -v webhook &>/dev/null && echo " ✅ webhook" || echo " ❌ webhook (missing)" command -v jq &>/dev/null && echo " ✅ jq" || echo " ❌ jq (missing)" command -v tmux &>/dev/null && echo " ✅ tmux" || echo " ❌ tmux (missing)" echo "" # Check configuration and CLI commands echo "Configuration:" [ -f "$HOME/bin/hooks.json" ] && echo " ✅ ~/bin/hooks.json" || echo " ❌ ~/bin/hooks.json (missing)" command -v forge &>/dev/null && echo " ✅ forge CLI" || echo " ❌ forge CLI (missing)" forge notify hook --help &>/dev/null && echo " ✅ forge notify hook" || echo " ❌ forge notify hook (missing)" forge tmux go --help &>/dev/null && echo " ✅ forge tmux go" || echo " ❌ forge tmux go (missing)" echo "" # Check LaunchAgent echo "Webhook Service:" PLIST="$HOME/Library/LaunchAgents/com.claude.webhook.plist" if [ -f "$PLIST" ]; then if launchctl list | grep -q "com.claude.webhook"; then echo " ✅ LaunchAgent installed and running" else echo " ⚠️ LaunchAgent installed but not running" fi else echo " ❌ LaunchAgent not installed" fi echo "" # Check webhook port echo "Webhook Port:" if curl -s http://localhost:9000/hooks/claude-notify -o /dev/null -w "%{http_code}" | grep -q "200\|405"; then echo " ✅ Port 9000 responding" else echo " ❌ Port 9000 not responding" fi echo "" # Check shell environment echo "Shell Environment:" if grep -q "WS_TMUX_LOCATION" "$HOME/.zshrc" 2>/dev/null; then echo " ✅ tmux env vars in ~/.zshrc" else echo " ❌ tmux env vars not in ~/.zshrc" fi echo "" # Check Claude hooks via webhook log echo "Claude Hooks (check log for activity):" LOG_FILE="$HOME/Library/Logs/claude-webhook/webhook.log" if [ -f "$LOG_FILE" ]; then RECENT_LINES=$(tail -5 "$LOG_FILE" 2>/dev/null) if [ -n "$RECENT_LINES" ]; then echo " Recent webhook log entries:" echo "$RECENT_LINES" | sed 's/^/ /' else echo " ⚠️ Log file exists but is empty" fi echo "" echo " To verify hooks are working, trigger a Claude stop event" echo " and check: tail -f ~/Library/Logs/claude-webhook/webhook.log" else echo " ⚠️ No log file yet at ~/Library/Logs/claude-webhook/webhook.log" echo " Log will be created when first notification is received" fi ``` Exit after showing status. ### If --uninstall: Remove Installation ```bash echo "=== Uninstalling Claude tmux Notification System ===" echo "" # Stop and remove LaunchAgent PLIST="$HOME/Library/LaunchAgents/com.claude.webhook.plist" if [ -f "$PLIST" ]; then echo "Stopping webhook service..." launchctl unload "$PLIST" 2>/dev/null || true rm -f "$PLIST" echo " ✅ LaunchAgent removed" fi # Remove configuration echo "Removing configuration..." rm -f "$HOME/bin/hooks.json" echo " ✅ Configuration removed" # Note: Don't remove shell env or Claude hooks automatically echo "" echo "Manual cleanup (optional):" echo " - Remove WS_TMUX_* lines from ~/.zshrc" echo " - Remove Stop/Notification hooks from ~/.claude/settings.json" echo "" echo "✅ Uninstallation complete" ``` Exit after uninstalling. ### Install: Full Setup Run the automated installer: ```bash forge webhook init ``` This command will: 1. Install dependencies (terminal-notifier, webhook, jq) 2. Create webhook configuration (~/bin/hooks.json) 3. Set up LaunchAgent for webhook service 4. Configure Claude Code hooks to call `forge notify hook` 5. Set up shell environment (tmux env vars) After installation: ```bash # Check status forge webhook status # Restart your shell source ~/.zshrc # Start a new tmux session and run Claude Code # You'll receive notifications when Claude finishes or needs input ``` ## Troubleshooting ### Notifications not appearing 1. Check if webhook is running: ```bash launchctl list | grep claude.webhook ``` 2. Check webhook logs: ```bash tail -f ~/Library/Logs/claude-webhook/webhook.log ``` 3. Test webhook manually: ```bash curl -X POST -H "Content-Type: application/json" \ -d '{"tmux_location":"test:0.0","hook_event_name":"Stop"}' \ http://localhost:9000/hooks/claude-notify ``` ### Click doesn't navigate to pane 1. Ensure tmux env vars are set: ```bash echo $WS_TMUX_LOCATION ``` 2. Test navigation command: ```bash forge tmux go "session:0.0" ``` ### Webhook won't start 1. Check if port 9000 is in use: ```bash lsof -i :9000 ``` 2. Try restarting: ```bash launchctl unload ~/Library/LaunchAgents/com.claude.webhook.plist launchctl load ~/Library/LaunchAgents/com.claude.webhook.plist ``` --- Source attribution: jpoutrin Original project: https://github.com/jpoutrin/product-forge/blob/0ebe7aea08747cb1c121bc77652d458b9e8ee782/plugins/claude-code-dev/skills/tmux-init/SKILL.md License: MIT License information: https://opensource.org/license/mit Original upstream instructions; downloaded from Mega AI Hub. ## Upstream license notice MIT License Copyright (c) 2025 jpoutrin Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. # Mega AI Hub resource metadata Creator / publisher: jpoutrin Original project: https://github.com/jpoutrin/product-forge/blob/0ebe7aea08747cb1c121bc77652d458b9e8ee782/plugins/claude-code-dev/skills/tmux-init/SKILL.md Attribution basis: Source repository record Fields of work: Development & Engineering, Product Management Roles: Backend Developer, DevOps / SRE, Technical Product Manager Specialties: DevOps Tools: Homebrew, Macos, Tmux Country applicability: Country not specified Classification basis: Source catalog labels Instruction SHA-256: 4560cdc3286292c76194eb2b804fd12a48d5067e92112b923eb5f678c837e93d