Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/manaflow-ai/cmux/llms.txt

Use this file to discover all available pages before exploring further.

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)

Build docs developers (and LLMs) love

Get started for freeTalk to us