Notification Commands

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:

string

Notification title (default: “Notification”)

string

Notification subtitle (default: empty)

string

Notification body text (default: empty)

string

Target workspace (defaults to $CMUX_WORKSPACE_ID)

string

Target surface (defaults to $CMUX_SURFACE_ID)

Examples:

cmux notify --title "Build Complete"

cmux notify --title "Tests Passed" --subtitle "All 42 tests" --body "Build #123 completed successfully"

cmux notify --title "Deployment Ready" --workspace workspace:2

cmux notify --title "Task Complete" --surface surface:3 --body "File processing finished"

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:

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

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

Environment Variables

The notify command uses these environment variables for context when flags are omitted:

string

Current workspace ID (set automatically in terminal sessions)

string

Current surface ID (set automatically in terminal sessions)

Global Flags

These flags can be used with notification commands:

string

Path to the cmux socket (default: /tmp/cmux.sock or $CMUX_SOCKET_PATH)

string

Socket authentication password (or use $CMUX_SOCKET_PASSWORD)

boolean

Output results in JSON format (for list-notifications)

​notify

​list-notifications

​clear-notifications

​Jump to Unread

​Use Cases

​Build/Test Results

​Error Reporting

​Long-Running Tasks

​Git Operations

​File Watching

​Notification Lifecycle

​Environment Variables

​Global Flags

notify

list-notifications

clear-notifications

Jump to Unread

Use Cases

Build/Test Results

Error Reporting

Long-Running Tasks

Git Operations

File Watching

Notification Lifecycle

Environment Variables

Global Flags