Skip to main content
Create and manage cmux notifications. These are designed for AI coding agents to communicate progress, errors, and important events.

​
notify

Send a notification to a workspace or surface. 
cmux notify --title <text> [--subtitle <text>] [--body <text>] [--workspace <id>] [--surface <id>]
Flags:
​
--title
string
Notification title (default: “Notification”)
​
--subtitle
string
Notification subtitle (default: empty)
​
--body
string
Notification body text (default: empty)
​
--workspace
string
Target workspace (defaults to $CMUX_WORKSPACE_ID)
​
--surface
string
Target surface (defaults to $CMUX_SURFACE_ID)
Examples: 
cmux notify --title "Build Complete"
Output: 
OK
Note: If both --workspace and --surface are omitted, the notification targets the current workspace/surface from environment variables. The workspace ID is resolved to its UUID for routing.

​
list-notifications

List all notifications in the app. 
cmux list-notifications [--json]
Flags:
​
--json
boolean
Output results in JSON format
Output (text): 
<id>:<notification_id>|<workspace_id>|<surface_id>|<read|unread>|<title>|<subtitle>|<body>
Example text output: 
1:notif-abc|workspace:1|surface:2|unread|Build Failed|Error in main.swift|Line 42: Syntax error
2:notif-def|workspace:1|none|read|Tests Passed|All tests|42 tests completed
Output (JSON with —json): 
[
  {
    "id": "notif-abc",
    "workspace_id": "workspace:1",
    "surface_id": "surface:2",
    "is_read": false,
    "title": "Build Failed",
    "subtitle": "Error in main.swift",
    "body": "Line 42: Syntax error"
  },
  {
    "id": "notif-def",
    "workspace_id": "workspace:1",
    "surface_id": null,
    "is_read": true,
    "title": "Tests Passed",
    "subtitle": "All tests",
    "body": "42 tests completed"
  }
]
Note: When there are no notifications, the text output is: 
No notifications

​
clear-notifications

Clear all notifications from the app. 
cmux clear-notifications
Output: 
OK

​
Jump to Unread

While there’s no dedicated CLI command for jumping to unread notifications, you can query unread notifications using list-notifications --json and filter the results: 
# Get unread notifications (requires jq)
cmux list-notifications --json | jq '.[] | select(.is_read == false)'
Example: 
# Count unread notifications
cmux list-notifications --json | jq '[.[] | select(.is_read == false)] | length'

​
Use Cases

Notifications are designed for AI coding agent workflows:

​
Build/Test Results

cmux notify --title "Build Complete" --subtitle "✓ All tests passed" --body "Build #123 finished in 42s"

​
Error Reporting

cmux notify --title "Compilation Error" --subtitle "main.swift:42" --body "Expected ';' after expression"

​
Long-Running Tasks

# Start notification
cmux notify --title "Processing" --subtitle "Analyzing codebase" --body "This may take a few minutes..."

# Completion notification
cmux notify --title "Analysis Complete" --subtitle "Found 12 issues" --body "Review results in workspace:3"

​
Git Operations

cmux notify --title "Push Complete" --subtitle "origin/main" --body "3 commits pushed successfully"

​
File Watching

cmux notify --title "File Changed" --subtitle "src/app.ts" --body "Hot reload triggered"

​
Notification Lifecycle

  1. Creation: Notifications are created with notify and linked to a workspace (and optionally a surface)
  2. Display: They appear in the cmux notification center and may trigger UI indicators
  3. Reading: Users can mark notifications as read by interacting with them
  4. Persistence: Notifications persist across app restarts
  5. Clearing: Use clear-notifications to remove all notifications

​
Environment Variables

The notify command uses these environment variables for context when flags are omitted:
​
CMUX_WORKSPACE_ID
string
Current workspace ID (set automatically in terminal sessions)
​
CMUX_SURFACE_ID
string
Current surface ID (set automatically in terminal sessions)

​
Global Flags

These flags can be used with notification commands:
​
--socket
string
Path to the cmux socket (default: /tmp/cmux.sock or $CMUX_SOCKET_PATH)
​
--password
string
Socket authentication password (or use $CMUX_SOCKET_PASSWORD)
​
--json
boolean
Output results in JSON format (for list-notifications)