Alexandre Quemy - Blog - Notification System for Tmux and Claude Code

Introduction
Architecture Overview
Implementation Guide
Conclusion
Configuration Files Appendix

Introduction¶

Like many technical folks these days, I use Claude Code constantly. But here’s the thing - I’m usually running multiple Claude sessions in parallel, either working on different features of the same project or juggling entirely different codebases. And when you’re deep in the zone with 5+ Claude sessions spread across tmux windows and panes, you need to know immediately when one of them needs your attention.

I tried the various web UIs and orchestrators out there - vibe-kanban, claudecodeui, Claudia. They’re nice for getting an overview, but they introduce too much friction when you live in the terminal. Context switching to a web UI just to check on Claude? That’s a workflow killer.

So I built my own notification system. Nothing fancy - just a clean way to get native macOS notifications that, when clicked, take me directly to the right tmux pane. No web UI, no extra chrome, just a notification and a single click to get back to work.

The basic flow: Claude finishes or needs input → triggers a notification → click it → boom, you’re in the right tmux pane. The whole thing runs on n8n for orchestration, Gotify for managing notifications across devices, and some simple webhook scripts for the local integration.

Who This Is For¶

This guide is for intermediate to advanced terminal users who:

Are comfortable with tmux, shell scripts, and Docker
Run multiple Claude Code sessions in parallel
Want native macOS notifications with one-click navigation to specific tmux panes
Prefer terminal-based workflows over web UIs

Prerequisites: macOS (with adaptations for Linux), tmux, Docker, Homebrew
Setup Time: 30-45 minutes

Architecture Overview¶

Component Overview¶

The system consists of six key components:

Claude Hooks - Triggers on Stop/Notification events
n8n - Workflow orchestrator that routes notifications
Gotify - Centralized notification server with multi-client support
Webhook - Local script executor
Terminal Notifier - Native macOS notifications
Ghostty + tmux - Terminal emulator and multiplexer for navigation

Data Flow¶

graph TB A[Claude] -->|Hook| B[n8n] B --> C[Gotify] B --> D[Webhook] C --> E[Clients] D --> F[Notify] F -->|Click| G[tmux] style A fill:#fef3c7,stroke:#f59e0b style G fill:#d1fae5,stroke:#10b981

A Claude Code session in tmux pane (e.g., 1:0.1) completes or needs input
Claude hook triggers and calls the n8n webhook with tmux location data
n8n sends notifications to both Gotify and local webhook server
Gotify notifies all registered clients while webhook triggers terminal-notifier
Clicking the notification calls another webhook that activates the tmux pane

Architecture Decisions

Why not use n8n alone instead of Gotify? While technically possible and probably easier to achieve notifications on specific applications such as Telegram, I wanted to decouple the orchestrator from the notification mechanism. Gotify is my messaging center for many different applications and it is actually hosted on a server that is not the machine where claude-code is started. Gotify also has the concepts of users, applications and clients which offer more flexibility than n8n to manage notifications properly.

Why not use n8n to execute scripts on the host? This would work if n8n was started on the same machine as where claude-code runs which is not my case. My n8n instance is hosted, as Gotify, on a different server and it used for different machines. Separating the orchestrator from the executor is still a good idea regardless and it offers the possibility to extend our notification system to receive notifications from different machines (e.g. a remote server) and execute actions there.

Why build around Claude Code? I want to build around Claude-code and not with Claude-code. As a result, I expect to be able to have Claude-code using the notification system that we will develop here. This is probably the most exciting use-case because it then becomes possible to have several claude-instance communicating with each other (spoiler alert, this is not going to end well!).

Warning

To make it easy for people to try it, I will consider that all components are started on the same machine and I will provide the instructions for macOS. In real life scenarios, you would typically separate n8n and Gotify on dedicated servers.

Quick Install (Experienced Users)¶

For those familiar with the stack, here’s the rapid setup:

# 1. Start services
docker volume create n8n_data && docker run -d --name n8n -p 5678:5678 -v n8n_data:/home/node/.n8n docker.n8n.io/n8nio/n8n
docker volume create gotify_data && docker run -d -p 8456:80 --name=gotify -v gotify_data:/app/data gotify/server

# 2. Install and configure webhook
brew install webhook
curl -L https://raw.githubusercontent.com/yourusername/claude-notifier/main/webhook.plist > ~/Library/LaunchAgents/com.github.adnanh.webhook.plist
launchctl bootstrap gui/$(id -u) ~/Library/LaunchAgents/com.github.adnanh.webhook.plist

# 3. Setup tmux environment
echo 'if [ -n "$TMUX" ] && [ -z "$WS_TMUX_LOCATION" ]; then
  export WS_TMUX_LOCATION=$(tmux display-message -p "#{session_name}:#{window_index}.#{pane_index}")
  export WS_TMUX_SESSION_NAME=$(tmux display-message -p "#{session_name}")
  export WS_TMUX_WINDOW_NAME=$(tmux display-message -p "#{window_name}")
fi' >> ~/.zshrc

# 4. Deploy scripts and configs
mkdir -p ~/bin
curl -L https://raw.githubusercontent.com/yourusername/claude-notifier/main/scripts.tar.gz | tar -xz -C ~/bin/
curl -L https://raw.githubusercontent.com/yourusername/claude-notifier/main/.hooks.json > ~/.hooks.json

# 5. Configure Claude hooks (add to ~/.claude/settings.json)
# 6. Import n8n workflow and add Gotify token

Next steps: Configure services via web UIs and test with a Claude Code session

Implementation Guide¶

First, let’s prepare the services that will form the backbone of our notification system. Each service plays a specific role in the notification pipeline, and we’ll set them up in the order of their dependencies.

Service Setup¶

n8n Setup¶

n8n is our workflow orchestrator that will receive webhook calls from Claude Code and route them to the appropriate notification channels.

Create Docker volume:
1
docker volume create n8n_data

Start n8n container:

docker run --name n8n -p 5678:5678 -v n8n_data:/home/node/.n8n docker.n8n.io/n8nio/n8n

Verify installation: Visit http://localhost:5678 and create your account

Troubleshooting▶

Gotify Setup¶

Gotify serves as our centralized notification server. It provides a clean API for sending notifications and supports multiple clients (browser, mobile apps, etc.).

Create Docker volume:
1
docker volume create gotify_data

Start Gotify container:

1	`docker run -p 8456:80 --name=gotify -v gotify_data:/app/data gotify/server`

Verify installation: Visit http://localhost:8456 (default username/password: admin/admin)

Troubleshooting▶

If Gotify fails, check Docker logs:

1	`docker logs gotify`

Common issues: - Port 8456 already in use: Change to another port with -p 8457:80 - Permission errors: Ensure Docker has write access to the volume

Webhook Setup¶

The webhook server runs locally and executes scripts when triggered. This is what allows us to show system notifications and activate tmux panes when you click on them.

Install webhook:
1
brew install webhook
Create LaunchAgent configuration: Create ~/Library/LaunchAgents/com.github.adnanh.webhook.plist (adjust paths to match your username):

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN"
  "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
  <key>Label</key>           <string>com.github.adnanh.webhook</string>
  <key>ProgramArguments</key>
  <array>
    <string>/opt/homebrew/bin/webhook</string>
    <string>-hooks</string>
    <string>/Users/aquemy/.hooks.json</string>
    <string>-port</string>
    <string>9000</string>
    <string>-hotreload</string>
    <string>-logfile</string>
    <string>/Users/aquemy/.webhook_log.txt</string>
  </array>
  <key>RunAtLoad</key>       <true/>
  <key>KeepAlive</key>       <true/>
  <key>StandardOutPath</key>  <string>/opt/homebrew/var/log/webhook.log</string>
  <key>StandardErrorPath</key><string>/opt/homebrew/var/log/webhook.log</string>
</dict>
</plist>

Start webhook service:

launchctl bootstrap gui/$(id -u) ~/Library/LaunchAgents/com.github.adnanh.webhook.plist

Verify webhook is running:

Check ~/.webhook_log.txt for:

[webhook] 2025/08/04 15:15:07 version 2.8.2 starting
[webhook] 2025/08/04 15:15:07 setting up os signal watcher
[webhook] 2025/08/04 15:15:07 attempting to load hooks from /Users/aquemy/.hooks.json
[webhook] 2025/08/04 15:15:07 os signal watcher ready

Troubleshooting▶

Linux Alternative

On Linux, use systemd instead of launchctl. Create /etc/systemd/system/webhook.service

Tmux Configuration¶

For the notification system to work, Claude Code needs to know which tmux pane it’s running in. We’ll set up environment variables that capture this information automatically when a new pane is created.

Add environment variables to .zshrc:

# Automatically set these variables for new processes in tmux
if [ -n "$TMUX" ] && [ -z "$WS_TMUX_LOCATION" ]; then
  export WS_TMUX_LOCATION=$(tmux display-message -p '#{session_name}:#{window_index}.#{pane_index}')
  export WS_TMUX_SESSION_NAME=$(tmux display-message -p '#{session_name}')
  export WS_TMUX_WINDOW_NAME=$(tmux display-message -p '#{window_name}')
fi

Reload shell configuration:
1
source ~/.zshrc

Verify environment variables:

echo $WS_TMUX_LOCATION $WS_TMUX_SESSION_NAME $WS_TMUX_WINDOW_NAME

Expected output (values will vary):

1	`1:0.1 1 node`

Troubleshooting▶

Gotify App Configuration¶

Now we need to create an application in Gotify that will handle our Claude Code notifications. This application will have its own token that we’ll use in n8n.

Create Gotify application:

curl -u admin:admin \
     -F "name=Claude Code" \
     -F "description=Notifications from Claude Code" \
     http://localhost:8456/application

Save the application token: The response includes a token (e.g., "token":"Abis_ERmy-hxAx5"):

{"id":2,"token":"Abis_ERmy-hxAx5","name":"Claude Code","description":"description=Notifications from Claude Code","internal":false,"image":"static/defaultapp.png","defaultPriority":0,"lastUsed":null}

Configure clients:
Visit http://localhost:8456/#/applications
Create browser client for web notifications
Optional: Install mobile app and add client

Important

Save the application token - you’ll need it for the n8n configuration!

Troubleshooting▶

Webhook Scripts¶

We need two scripts to handle the notification flow:

ghostty-notify-wrapper.sh - Generates the macOS notification using terminal-notifier with contextual information from Claude Code
go-tmux.sh - Handles the notification click event and switches to the correct tmux pane

Both scripts will be registered as webhooks. The notification generated by the first script will include a click action that triggers the second script. Since webhook was started with the --hotreload flag, changes to these scripts take effect immediately without restarting the service.

The architecture isolates terminal-specific components (ghostty, terminal-notifier) in these scripts, making it easy to adapt for other terminals or notification systems.

Note

Important: These scripts must use absolute paths for all executables (e.g., /opt/homebrew/bin/terminal-notifier instead of just terminal-notifier) because they run in a limited environment context.

The first script generates the macOS notification. It takes all the contextual information from Claude (tmux location, session name, project, etc.) and creates a clickable notification. The magic happens in the -execute parameter - when you click the notification, it triggers a webhook that calls our second script.

#!/bin/bash
# $1 = tmux_location
# $2 = tmux_session_name
# $3 = tmux_window_name
# $4 = project
# $5 = cwd
# $6 = transcript_path
# $7 = hook_event_name
# $8 = session_id
/opt/homebrew/bin/terminal-notifier \
  -subtitle "🤖 Claude is $([ "$7" = "Stop" ] && echo "done" || echo "waiting")." \
  -title "tmux s:$2 w:$3" \
  -message "Project $4 - Session $8" \
  -execute "/usr/bin/curl -X POST 'http://localhost:9000/hooks/show-ghostty?tmux_location=$1'" \
  -sound default

The second script handles the actual navigation. When you click a notification, this script parses the tmux location, switches to the right window and pane, then brings Ghostty to the foreground. The logging is verbose on purpose - when something goes wrong with tmux navigation, you want to know exactly what happened.

#!/bin/zsh

# Log ALL output
LOG="/tmp/tmux-notifier.log"
exec >> $LOG 2>&1

echo "=== CLICK EVENT: $(date) ==="
echo "PWD: $(pwd)"
echo "SHELL: $SHELL"
echo "PATH: $PATH"
echo "USER: $USER"
echo "LOCATION: $1"

# Source zsh environment
source "$HOME/.zshenv" 2>/dev/null
source "$HOME/.zshrc" 2>/dev/null

export PATH="/usr/local/bin:/opt/homebrew/bin:/usr/bin:/bin:/usr/sbin:/sbin:$HOME/bin"

echo "FINAL PATH: $PATH"

TMUX=$(whence -p tmux || echo "/usr/local/bin/tmux")
echo "TMUX binary: $TMUX"

if [[ ! -x "$TMUX" ]]; then
  echo "ERROR: tmux not found or not executable at $TMUX"
  exit 1
fi

LOCATION="$1"

if [[ -z "$LOCATION" ]]; then
  echo "ERROR: No location provided"
  exit 1
fi

if [[ "$LOCATION" =~ ^([^:]+):([0-9]+)(\.([0-9]+))?$ ]]; then
  SESSION="${match[1]}"
  WINDOW="${match[2]}"
  PANE="${match[4]}"
else
  echo "ERROR: Invalid format: $LOCATION"
  exit 1
fi

echo "Switching to: session=$SESSION, window=$WINDOW, pane=$PANE"

# Run tmux commands
"$TMUX" select-window -t "$SESSION:$WINDOW"
if [[ $? -ne 0 ]]; then
  echo "ERROR: tmux select-window failed"
else
  echo "OK: select-window succeeded"
fi

if [[ -n "$PANE" ]]; then
  "$TMUX" select-pane -t "$SESSION:$WINDOW.$PANE"
  if [[ $? -ne 0 ]]; then
    echo "WARNING: select-pane failed"
  else
    echo "OK: select-pane succeeded"
  fi
fi

# Try to focus Ghostty
osascript -e 'tell application "Ghostty" to activate'
if [[ $? -eq 0 ]]; then
  echo "OK: osascript ran successfully"
else
  echo "ERROR: osascript failed with code $?"
fi

echo "=== END ==="

Make these scripts executable with:

chmod +x ghostty-notify-wrapper.sh
chmod +x go-tmux.sh

Now we need to configure webhook to know about these scripts. The .hooks.json file defines two webhook endpoints - one for each script. The key thing to understand is how webhook passes data: { "source": "payload", "name": "tmux_location" } means “take the tmux_location field from the POST request body and pass it as a command-line argument to the script”. For the first webhook, { "source": "url", "name": "tmux_location" } means “extract tmux_location from the URL query parameters” - this is how the notification click passes data back.

[
  {
    "id": "show-ghostty",
    "execute-command": "/Users/aquemy/bin/go-tmux.sh",
    "pass-arguments-to-command": [
      { "source": "url", "name": "tmux_location" }
    ]
  },
  {
    "id": "ghostty-notify",
    "execute-command": "/Users/aquemy/bin/ghostty-notify-wrapper.sh",
    "pass-arguments-to-command": [
      { "source": "payload", "name": "tmux_location" },
      { "source": "payload", "name": "tmux_session_name" },
      { "source": "payload", "name": "tmux_window_name" },
      { "source": "payload", "name": "project" },
      { "source": "payload", "name": "cwd" },
      { "source": "payload", "name": "transcript_path" },
      { "source": "payload", "name": "hook_event_name" },
      { "source": "payload", "name": "session_id" }
    ]
  }
]

You can test the script directly with a command like:

./ghostty-notify-wrapper.sh "1:0.1" "Session" "Windows" "My project" "/Users/aquemy" "/Users/aquemy/.claude/projects/-Users-aquemy/291a78f4-8b7e-4c74-9d09-3abd06dc7f56.jsonl" "Stop" "291a78f4-8b7e-4c74-9d09-3abd06dc7f56"

It should generate a notification and if you click on it, it should bring you to 1:0.1 if you have such pane.

Claude Hooks¶

Claude hooks allow us to trigger actions when specific events occur in Claude Code. For our notification system, we’re interested in two events:

Stop: When Claude Code finishes executing and is waiting for the next instruction
Notification: When Claude Code needs user attention (e.g., asking for clarification)

Claude hooks provide a rich payload containing session information, working directory, and event type. We’ll enhance this payload with our tmux location data before forwarding it to n8n.

Understanding the Hook Payload¶

When a hook triggers, Claude Code provides a JSON payload with fields like: - session_id: Unique identifier for the Claude session - cwd: Current working directory - hook_event_name: The event that triggered the hook (Stop, Notification, etc.) - transcript_path: Path to the session transcript

We’ll add our tmux environment variables to this payload using jq:

echo '{"original": "payload"}' | jq --arg tmux_location "$WS_TMUX_LOCATION" --arg tmux_session_name "$WS_TMUX_SESSION_NAME" --arg tmux_window_name "$WS_TMUX_WINDOW_NAME" '. + {tmux_location: $tmux_location, tmux_session_name: $tmux_session_name, tmux_window_name: $tmux_window_name}'

This produces an enhanced payload:

{
  "original": "payload",
  "tmux_location": "0:1.2",
  "tmux_session_name": "Work",
  "tmux_window_name": "window name"
}

Forwarding to n8n¶

We’ll pipe this enhanced payload to curl to send it to our n8n webhook:

jq --arg tmux_location "$TMUX_LOCATION" --arg tmux_session_name "$TMUX_SESSION_NAME" --arg tmux_window_name "$TMUX_WINDOW_NAME" '. + {tmux_location: $tmux_location, tmux_session_name: $tmux_session_name, tmux_window_name: $tmux_window_name}' | curl -X POST -H "Content-Type: application/json" -d @- http://localhost:5679/webhook/claude-code-notification

The final hooks to place in ~/.claude/settings.json:

{
  ...
  "hooks": {
    "Notification": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "jq --arg tmux_location \"$WS_TMUX_LOCATION\" --arg tmux_session_name \"$WS_TMUX_SESSION_NAME\" --arg tmux_window_name \"$WS_TMUX_WINDOW_NAME\" '. + {tmux_location: $tmux_location, tmux_session_name: $tmux_session_name, tmux_window_name: $tmux_window_name}' | curl -X POST -H \"Content-Type: application/json\" -d @- http://localhost:5679/webhook/claude-code-notification"
          }
        ]
      }
    ],
    "Stop": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "jq --arg tmux_location \"$WS_TMUX_LOCATION\" --arg tmux_session_name \"$WS_TMUX_SESSION_NAME\" --arg tmux_window_name \"$WS_TMUX_WINDOW_NAME\" '. + {tmux_location: $tmux_location, tmux_session_name: $tmux_session_name, tmux_window_name: $tmux_window_name}' | curl -X POST -H \"Content-Type: application/json\" -d @- http://localhost:5678/webhook-test/claude-code-notification"
          }
        ]
      }
    ]
  }
}

Perfect, we now need to create the n8n workflow!

n8n Workflow¶

Now we’ll create the n8n workflow that orchestrates our notifications. The workflow has a simple but powerful design:

Webhook Trigger: Receives the enhanced payload from Claude hooks
Edit Fields Node: Transforms and enriches the data (e.g., extracting project name from path)
Parallel Notifications: Sends notifications to both Gotify and local webhook simultaneously

This parallel execution ensures that system notifications appear instantly while Gotify handles persistent notifications and multi-device delivery.

Workflow Setup¶

1. Trigger Configuration¶

Create a new workflow and add a Webhook node. This will be the entry point for all Claude Code notifications.

Important settings: - HTTP Method: POST - Path: claude-code-notification (must match the path in your Claude hooks) - Response Mode: “When last node finishes” (ensures proper acknowledgment)

2. Edit Fields Node¶

The Edit Fields node allows us to transform the incoming data. While optional, it’s useful for extracting meaningful information. For example, we extract the project name from the working directory path:

Expression to extract project name:

{{ $json.body.cwd.split('/').last() }}

This takes the working directory path (e.g., /Users/aquemy/projects/my-app) and extracts just the project name (my-app).

3. Gotify Notification¶

The Gotify notification node sends alerts to all registered clients. Since n8n runs in Docker, we need to use the special Docker networking URL.

Configuration details:

Method: POST
URL: http://host.docker.internal:8456/message
Query Parameters: Add token with your Gotify app token
Body Parameters:
title: 🤖 Claude is {{ $if($json.hook_event_name == 'Stop', 'done', 'waiting') }} for project {{ $json.project }}
message: Session: {{ $json.session_id }}\nTMUX: {{ $json.tmux_location }}
priority: 5

The notification appears in multiple places:

Browser notification:

Gotify UI:

4. Webhook System Notification¶

This node triggers our local webhook server to create the macOS system notification:

Configuration:

Method: POST
URL: http://host.docker.internal:9000/hooks/ghostty-notify
Body Parameters: Forward all the relevant fields from the payload

Complete Workflow JSON¶

Complete Workflow JSON▶

Import this JSON directly into n8n to recreate the workflow:

{
  "name": "Claude Code Notification",
  "nodes": [
    {
      "parameters": {
        "httpMethod": "POST",
        "path": "claude-code-notification",
        "options": {}
      },
      "type": "n8n-nodes-base.webhook",
      "typeVersion": 2,
      "position": [
        -240,
        0
      ],
      "id": "1be841e6-6b9b-4da3-86f9-3b53cf482487",
      "name": "Claude Code Notification Event",
      "webhookId": "be4faefc-31b0-4603-afdc-f4ec5e5e659a"
    },
    {
      "parameters": {
        "method": "POST",
        "url": "http://host.docker.internal:8456/message",
        "sendQuery": true,
        "queryParameters": {
          "parameters": [
            {
              "name": "token",
              "value": "<your token>"
            }
          ]
        },
        "sendBody": true,
        "contentType": "form-urlencoded",
        "bodyParameters": {
          "parameters": [
            {
              "name": "title",
              "value": "=🤖 Claude is {{ $if($json.hook_event_name == 'Stop', 'done', 'waiting') }} for project {{ $json.project }}"
            },
            {
              "name": "message",
              "value": "=Session: {{ $json.session_id }}\nTMUX: {{ $json.tmux_location }}"
            },
            {
              "name": "priority",
              "value": "5"
            }
          ]
        },
        "options": {}
      },
      "type": "n8n-nodes-base.httpRequest",
      "typeVersion": 4.2,
      "position": [
        256,
        -96
      ],
      "id": "6c56d660-1fd9-4d17-8676-b57ddefeaf73",
      "name": "Gotify Notification",
      "notesInFlow": false,
      "onError": "continueRegularOutput"
    },
    {
      "parameters": {
        "method": "POST",
        "url": "http://host.docker.internal:9000/hooks/ghostty-notify",
        "sendBody": true,
        "bodyParameters": {
          "parameters": [
            {
              "name": "tmux_location",
              "value": "={{ $json.tmux_location }}"
            },
            {
              "name": "project",
              "value": "={{ $json.project }}"
            },
            {
              "name": "cwd",
              "value": "={{ $json.cwd }}"
            },
            {
              "name": "transcript_path",
              "value": "={{ $json.transcript_path }}"
            },
            {
              "name": "hook_event_name",
              "value": "={{ $json.hook_event_name }}"
            },
            {
              "name": "session_id",
              "value": "={{ $json.session_id }}"
            },
            {
              "name": "tmux_session_name",
              "value": "={{ $json.tmux_session_name }}"
            },
            {
              "name": "tmux_window_name",
              "value": "={{ $json.tmux_window_name }}"
            }
          ]
        },
        "options": {}
      },
      "type": "n8n-nodes-base.httpRequest",
      "typeVersion": 4.2,
      "position": [
        256,
        112
      ],
      "id": "21a150b8-2df5-43fd-9bcc-d6f40f90cb6a",
      "name": "Webhook System Notification"
    },
    {
      "parameters": {
        "assignments": {
          "assignments": [
            {
              "id": "3e7ba227-14c8-4e54-ad6a-41a79789958f",
              "name": "tmux_location",
              "value": "={{ $json.body.tmux_location }}",
              "type": "string"
            },
            {
              "id": "44f0cddd-a138-471c-99a1-e22d194fc029",
              "name": "session_id",
              "value": "={{ $json.body.session_id }}",
              "type": "string"
            },
            {
              "id": "863d1968-bf50-4e97-b509-ae4e1f39442f",
              "name": "transcript_path",
              "value": "={{ $json.body.transcript_path }}",
              "type": "string"
            },
            {
              "id": "f1405671-5df7-40d3-8fa4-09a18fe83870",
              "name": "cwd",
              "value": "={{ $json.body.cwd }}",
              "type": "string"
            },
            {
              "id": "c8c0d5b3-49b2-4127-8f49-a190b17225b8",
              "name": "hook_event_name",
              "value": "={{ $json.body.hook_event_name }}",
              "type": "string"
            },
            {
              "id": "82dea28b-6f3e-4f1b-8b06-d4f832bad0bc",
              "name": "stop_hook_active",
              "value": "={{ $json.body.stop_hook_active }}",
              "type": "boolean"
            },
            {
              "id": "e428e02d-ae8a-4917-9ff5-6c01fbc7c3a9",
              "name": "project",
              "value": "={{ $json.body.cwd.split('/').last() }}",
              "type": "string"
            },
            {
              "id": "f3057b4a-cfb2-45f6-a844-7f2c65fd7401",
              "name": "tmux_session_name",
              "value": "={{ $json.body.tmux_session_name }}",
              "type": "string"
            },
            {
              "id": "c5ad8c63-6c70-4ac3-9b6a-697e2d5fc6c1",
              "name": "tmux_window_name",
              "value": "={{ $json.body.tmux_window_name }}",
              "type": "string"
            }
          ]
        },
        "options": {}
      },
      "type": "n8n-nodes-base.set",
      "typeVersion": 3.4,
      "position": [
        16,
        0
      ],
      "id": "694be38f-9a17-46a2-a04d-eacbffe74cc7",
      "name": "Edit Fields"
    }
  ],
  "pinData": {},
  "connections": {
    "Claude Code Notification Event": {
      "main": [
        [
          {
            "node": "Edit Fields",
            "type": "main",
            "index": 0
          }
        ]
      ]
    },
    "Webhook System Notification": {
      "main": [
        []
      ]
    },
    "Edit Fields": {
      "main": [
        [
          {
            "node": "Gotify Notification",
            "type": "main",
            "index": 0
          },
          {
            "node": "Webhook System Notification",
            "type": "main",
            "index": 0
          }
        ]
      ]
    }
  },
  "active": true,
  "settings": {
    "executionOrder": "v1"
  },
  "versionId": "61e9c91d-4d09-4cbb-bddd-7d926e6eaaa7",
  "meta": {
    "instanceId": "f19f35bb222ea20af0ecef72c39527c7789858f0d5593e15213f895b711cdaf9"
  },
  "id": "E4dh9ILzuo8Dzr4D",
  "tags": []
}

Conclusion¶

That’s it - a simple notification system that keeps me in the flow while juggling multiple Claude sessions. No more wondering which session needs attention or losing track of where I was working. Just a clean notification and a single click to get back to the right tmux pane.

The best part? Each component does one thing well. n8n handles the orchestration, Gotify manages notifications across devices, and simple bash scripts handle the local integration. When something breaks (and it will), it’s easy to debug because each piece is isolated.

What’s Next?¶

I’ve been thinking about a few extensions that might be interesting:

Web UI with tmux controls - Show the full tmux layout with live status of each Claude session. Maybe add touch screen support or macro pad shortcuts for quick navigation.
Claude-to-Claude communication - Since Claude can now trigger notifications, why not let different Claude instances communicate? I tried this already - spoiler: it gets weird fast when they start coordinating.
Home Assistant integration - Visual feedback through smart lights when Claude needs attention. Because why not?
Event database - Track notification patterns to understand when Claude gets stuck most often. Could help optimize prompts.
Beyond tmux - Support for screen, Zellij, or even Windows Terminal.

The notification system is intentionally built to be extended. Want to add Discord notifications? Just add another node in n8n. Prefer Linux? Swap terminal-notifier for notify-send and osascript for xdotool. The architecture stays the same.

If you build something cool with this, let me know. I’m always curious to see how others adapt these tools to their workflow.

Configuration Files Appendix¶

This section consolidates all configuration files for easy reference. You can download these files from the GitHub repository.

Complete .hooks.json¶

Additional Configuration Examples▶

LaunchAgent plist¶

LaunchAgent Configuration▶

Claude Hooks Configuration¶

Claude settings.json Hooks▶

Shell Scripts¶

Notification and Navigation Scripts▶

ghostty-notify-wrapper.sh¶

Save as ~/bin/ghostty-notify-wrapper.sh:

#!/bin/bash
# $1 = tmux_location
# $2 = tmux_session_name
# $3 = tmux_window_name
# $4 = project
# $5 = cwd
# $6 = transcript_path
# $7 = hook_event_name
# $8 = session_id
/opt/homebrew/bin/terminal-notifier \
  -subtitle "🤖 Claude is $([ "$7" = "Stop" ] && echo "done" || echo "waiting")." \
  -title "tmux s:$2 w:$3" \
  -message "Project $4 - Session $8" \
  -execute "/usr/bin/curl -X POST 'http://localhost:9000/hooks/show-ghostty?tmux_location=$1'" \
  -sound default

go-tmux.sh¶

Save as ~/bin/go-tmux.sh:

#!/bin/zsh

# Log ALL output
LOG="/tmp/tmux-notifier.log"
exec >> $LOG 2>&1

echo "=== CLICK EVENT: $(date) ==="
echo "PWD: $(pwd)"
echo "SHELL: $SHELL"
echo "PATH: $PATH"
echo "USER: $USER"
echo "LOCATION: $1"

# Source zsh environment
source "$HOME/.zshenv" 2>/dev/null
source "$HOME/.zshrc" 2>/dev/null

export PATH="/usr/local/bin:/opt/homebrew/bin:/usr/bin:/bin:/usr/sbin:/sbin:$HOME/bin"

echo "FINAL PATH: $PATH"

TMUX=$(whence -p tmux || echo "/usr/local/bin/tmux")
echo "TMUX binary: $TMUX"

if [[ ! -x "$TMUX" ]]; then
  echo "ERROR: tmux not found or not executable at $TMUX"
  exit 1
fi

LOCATION="$1"

if [[ -z "$LOCATION" ]]; then
  echo "ERROR: No location provided"
  exit 1
fi

if [[ "$LOCATION" =~ ^([^:]+):([0-9]+)(\.([0-9]+))?$ ]]; then
  SESSION="${match[1]}"
  WINDOW="${match[2]}"
  PANE="${match[4]}"
else
  echo "ERROR: Invalid format: $LOCATION"
  exit 1
fi

echo "Switching to: session=$SESSION, window=$WINDOW, pane=$PANE"

# Run tmux commands
"$TMUX" select-window -t "$SESSION:$WINDOW"
if [[ $? -ne 0 ]]; then
  echo "ERROR: tmux select-window failed"
else
  echo "OK: select-window succeeded"
fi

if [[ -n "$PANE" ]]; then
  "$TMUX" select-pane -t "$SESSION:$WINDOW.$PANE"
  if [[ $? -ne 0 ]]; then
    echo "WARNING: select-pane failed"
  else
    echo "OK: select-pane succeeded"
  fi
fi

# Try to focus Ghostty
osascript -e 'tell application "Ghostty" to activate'
if [[ $? -eq 0 ]]; then
  echo "OK: osascript ran successfully"
else
  echo "ERROR: osascript failed with code $?"
fi

echo "=== END ==="

n8n Workflow¶

Complete n8n Workflow JSON▶

Import this workflow in n8n:

{
  "name": "Claude Code Notification",
  "nodes": [
    {
      "parameters": {
        "httpMethod": "POST",
        "path": "claude-code-notification",
        "options": {}
      },
      "type": "n8n-nodes-base.webhook",
      "typeVersion": 2,
      "position": [-240, 0],
      "id": "1be841e6-6b9b-4da3-86f9-3b53cf482487",
      "name": "Claude Code Notification Event",
      "webhookId": "be4faefc-31b0-4603-afdc-f4ec5e5e659a"
    },
    {
      "parameters": {
        "method": "POST",
        "url": "http://host.docker.internal:8456/message",
        "sendQuery": true,
        "queryParameters": {
          "parameters": [
            {
              "name": "token",
              "value": "<your token>"
            }
          ]
        },
        "sendBody": true,
        "contentType": "form-urlencoded",
        "bodyParameters": {
          "parameters": [
            {
              "name": "title",
              "value": "=🤖 Claude is {{ $if($json.hook_event_name == 'Stop', 'done', 'waiting') }} for project {{ $json.project }}"
            },
            {
              "name": "message",
              "value": "=Session: {{ $json.session_id }}\nTMUX: {{ $json.tmux_location }}"
            },
            {
              "name": "priority",
              "value": "5"
            }
          ]
        },
        "options": {}
      },
      "type": "n8n-nodes-base.httpRequest",
      "typeVersion": 4.2,
      "position": [256, -96],
      "id": "6c56d660-1fd9-4d17-8676-b57ddefeaf73",
      "name": "Gotify Notification",
      "notesInFlow": false,
      "onError": "continueRegularOutput"
    },
    {
      "parameters": {
        "assignments": {
          "assignments": [
            {
              "id": "3e7ba227-14c8-4e54-ad6a-41a79789958f",
              "name": "tmux_location",
              "value": "={{ $json.body.tmux_location }}",
              "type": "string"
            },
            {
              "id": "e428e02d-ae8a-4917-9ff5-6c01fbc7c3a9",
              "name": "project",
              "value": "={{ $json.body.cwd.split('/').last() }}",
              "type": "string"
            },
            {
              "id": "44f0cddd-a138-471c-99a1-e22d194fc029",
              "name": "session_id",
              "value": "={{ $json.body.session_id }}",
              "type": "string"
            },
            {
              "id": "c8c0d5b3-49b2-4127-8f49-a190b17225b8",
              "name": "hook_event_name",
              "value": "={{ $json.body.hook_event_name }}",
              "type": "string"
            },
            {
              "id": "f3057b4a-cfb2-45f6-a844-7f2c65fd7401",
              "name": "tmux_session_name",
              "value": "={{ $json.body.tmux_session_name }}",
              "type": "string"
            },
            {
              "id": "c5ad8c63-6c70-4ac3-9b6a-697e2d5fc6c1",
              "name": "tmux_window_name",
              "value": "={{ $json.body.tmux_window_name }}",
              "type": "string"
            }
          ]
        },
        "options": {}
      },
      "type": "n8n-nodes-base.set",
      "typeVersion": 3.4,
      "position": [16, 0],
      "id": "694be38f-9a17-46a2-a04d-eacbffe74cc7",
      "name": "Edit Fields"
    }
  ],
  "connections": {
    "Claude Code Notification Event": {
      "main": [[{ "node": "Edit Fields", "type": "main", "index": 0 }]]
    },
    "Edit Fields": {
      "main": [[
        { "node": "Gotify Notification", "type": "main", "index": 0 },
        { "node": "Webhook System Notification", "type": "main", "index": 0 }
      ]]
    }
  },
  "active": true,
  "settings": {
    "executionOrder": "v1"
  }
}