CtrlK
BlogDocsLog inGet started
Tessl Logo

tmux-init

Set up tmux notification system for Claude Code sessions

68

Quality

58%

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

SecuritybySnyk

Passed

No known issues

Optimize this skill with Tessl

npx tessl skill review --optimize ./plugins/claude-code-dev/skills/tmux-init/SKILL.md
SKILL.md
Quality
Evals
Security

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

/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

UNINSTALL=false
STATUS=false

for arg in "$@"; do
    case "$arg" in
        --uninstall) UNINSTALL=true ;;
        --status) STATUS=true ;;
    esac
done

If --status: Check Installation Status

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

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:

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:

# 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:

    launchctl list | grep claude.webhook
  2. Check webhook logs:

    tail -f ~/Library/Logs/claude-webhook/webhook.log
  3. Test webhook manually:

    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:

    echo $WS_TMUX_LOCATION
  2. Test navigation command:

    forge tmux go "session:0.0"

Webhook won't start

  1. Check if port 9000 is in use:

    lsof -i :9000
  2. Try restarting:

    launchctl unload ~/Library/LaunchAgents/com.claude.webhook.plist
    launchctl load ~/Library/LaunchAgents/com.claude.webhook.plist
Repository
jpoutrin/product-forge
Last updated
Created

Is this your skill?

If you maintain this skill, you can claim it as your own. Once claimed, you can manage eval scenarios, bundle related skills, attach documentation or rules, and ensure cross-agent compatibility.