Claude Code integration

Get real-time notifications from Claude Code sessions in cmux

Integrate Claude Code with cmux to receive visual notifications when Claude needs your input. When a coding session is waiting for you, the workspace tab lights up with a blue notification ring.

How it works

Claude Code can trigger hooks at key lifecycle events:

• session-start: When a new coding session begins
• notification: When Claude needs your attention (waiting for input, approval, etc.)
• stop: When the session ends

The cmux claude-hook command connects these events to cmux’s notification system, workspace status indicators, and session tracking.

Setup

1. Verify cmux CLI is available

   The cmux CLI is installed automatically with the cmux app. Check that it’s accessible:

   which cmux
   cmux --version
   

   If the command isn’t found, add cmux to your PATH:

   export PATH="/Applications/cmux.app/Contents/MacOS:$PATH"
   
2. Configure Claude Code hooks

   Create or edit ~/.claude/hooks.json to wire Claude lifecycle events to cmux:

   {
     "session-start": "cmux claude-hook session-start",
     "notification": "cmux claude-hook notification",
     "stop": "cmux claude-hook stop"
   }
   

   Claude Code will pipe event metadata as JSON to stdin when calling these hooks.

3. Start a Claude Code session

   Launch Claude Code from inside cmux:

   claude
   

   When Claude needs input, you’ll see:

   • A blue notification ring around the workspace tab
   • The sidebar badge updates with pending notifications
   • Status indicator shows “Needs input” with a bell icon

Session tracking

cmux tracks Claude Code sessions using the ClaudeHookSessionStore mechanism. This associates each Claude session ID with a specific cmux workspace and surface.

How session tracking works

1. When session-start fires, cmux stores the mapping:

   session_id → workspace_id + surface_id + cwd
   

2. On subsequent notification events, cmux looks up the session ID and routes notifications to the correct workspace/surface — even if you’ve switched tabs or windows.

3. When stop fires, cmux removes the session from the store and clears the status indicator.

Session state is persisted to ~/.cmuxterm/claude-hook-sessions.json and pruned after 7 days of inactivity.

You can override session routing with explicit flags:

cmux claude-hook notification --workspace 2 --surface 1

Command reference

session-start

Triggered when a Claude Code session begins. Sets the workspace status to “Running” with a bolt icon.

cmux claude-hook session-start [--workspace <id>] [--surface <id>]

Reads from stdin:

{
  "session_id": "abc123",
  "cwd": "/path/to/project"
}

notification

Triggered when Claude needs attention. Creates a notification and updates the workspace status to “Needs input” with a bell icon.

cmux claude-hook notification [--workspace <id>] [--surface <id>]

Reads from stdin:

{
  "session_id": "abc123",
  "notification": {
    "title": "Waiting for input",
    "body": "Claude is waiting for your response"
  }
}

stop

Triggered when a Claude Code session ends. Clears the workspace status indicator and removes the session from the store.

cmux claude-hook stop [--workspace <id>] [--surface <id>]

Reads from stdin:

{
  "session_id": "abc123"
}

Advanced usage

Multiple workspaces

If you run Claude Code in multiple workspaces, cmux automatically routes notifications to the correct workspace based on session ID.

Custom hook scripts

You can wrap the cmux claude-hook command in a custom script for logging or additional automation:

~/.claude/my-hook.sh

#!/bin/bash
log_event() {
  echo "[$(date)] $1" >> ~/.claude/hook.log
}

log_event "Claude hook: $1"
cmux claude-hook "$@"

Then update hooks.json:

{
  "notification": "~/.claude/my-hook.sh notification"
}

Environment variables

• CMUX_SOCKET_PATH: Override the default socket path (default: /tmp/cmux.sock)
• CMUX_WORKSPACE_ID: Pre-set the target workspace ID
• CMUX_SURFACE_ID: Pre-set the target surface ID
• CMUX_CLAUDE_HOOK_STATE_PATH: Override session store location (default: ~/.cmuxterm/claude-hook-sessions.json)

Troubleshooting

Notifications not appearing

Check that cmux is running and the socket is accessible:

ls -l /tmp/cmux.sock

Test the connection manually:

cmux ping

If the socket doesn’t exist, launch cmux and try again.

Notifications appear in wrong workspace

The session store may have stale mappings. Clear it:

rm ~/.cmuxterm/claude-hook-sessions.json

Or explicitly target a workspace:

export CMUX_WORKSPACE_ID=workspace:1

Hooks not firing

Verify your hooks.json syntax:

cat ~/.claude/hooks.json | jq .

Check Claude Code hook execution with a test script:

echo '{"session_id":"test"}' | cmux claude-hook notification

Related commands

• cmux notify - Send custom notifications to any workspace
• cmux list-notifications - View all pending notifications
• CLI Reference - Complete command reference