OpenCode integration

Configure OpenCode to send notifications through cmux

Integrate OpenCode with cmux to receive visual notifications when the agent needs your attention. Similar to Claude Code integration, OpenCode can trigger notifications that appear as blue rings on workspace tabs.

How it works

OpenCode uses a hook system to notify external tools when certain events occur. cmux provides a notify command that OpenCode hooks can call to create notifications.

Setup

1. Verify cmux CLI is available

   The cmux CLI is installed with the app. Verify it’s in your PATH:

   which cmux
   cmux --version
   

   If not found, add cmux to your PATH:

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

   OpenCode supports custom hooks in its configuration. Add a notification hook that calls cmux:

   Create ~/.opencode/hooks.sh:

   #!/bin/bash
   # OpenCode → cmux notification bridge
   
   case "$1" in
     agent-waiting)
       cmux notify \
         --title "OpenCode" \
         --subtitle "Waiting for input" \
         --body "$2"
       ;;
     agent-complete)
       cmux notify \
         --title "OpenCode" \
         --subtitle "Task complete" \
         --body "$2"
       ;;
     agent-error)
       cmux notify \
         --title "OpenCode" \
         --subtitle "Error" \
         --body "$2"
       ;;
   esac
   

   Make it executable:

   chmod +x ~/.opencode/hooks.sh
   
3. Configure OpenCode to use the hook

   Edit your OpenCode config (typically ~/.opencode/config.json):

   {
     "hooks": {
       "onAgentWaiting": "~/.opencode/hooks.sh agent-waiting",
       "onComplete": "~/.opencode/hooks.sh agent-complete",
       "onError": "~/.opencode/hooks.sh agent-error"
     }
   }
   
4. Test the integration

   Run an OpenCode command and verify that notifications appear in cmux:

   opencode "add a hello world function"
   

   You should see a notification in the cmux sidebar when OpenCode is waiting.

Using the notify command

The cmux notify command sends a notification to the current workspace (or a specific workspace if targeted).

Basic usage

cmux notify --title "Agent" --subtitle "Status" --body "Message text"

Options

• --title: Notification title (default: “Notification”)
• --subtitle: Short summary text
• --body: Full notification message
• --workspace <id>: Target a specific workspace by ID or index
• --surface <id>: Target a specific surface/tab within the workspace

If --workspace and --surface are omitted, cmux routes the notification to the workspace where the command was executed (via CMUX_WORKSPACE_ID and CMUX_SURFACE_ID environment variables).

Examples

Current workspace

# Send to the current workspace
cmux notify --title "Build" --subtitle "Success" --body "Build completed in 2.3s"

Environment variables

cmux automatically sets these variables in each terminal session:

• CMUX_WORKSPACE_ID: The current workspace ID
• CMUX_SURFACE_ID: The current surface (tab) ID
• CMUX_SOCKET_PATH: Path to the cmux control socket

You can use these in your hook scripts to ensure notifications route to the correct workspace.

Advanced integration

Progress indicators

For long-running operations, you can combine notifications with progress indicators:

# Start operation
cmux set-progress 0.0 --label "Building"

# Update progress
cmux set-progress 0.5 --label "Testing"

# Complete
cmux set-progress 1.0 --label "Done"
cmux clear-progress

# Notify on completion
cmux notify --title "Build" --body "Build complete"

Status badges

Add persistent status badges to workspace tabs:

# Show "Running" status
cmux set-status agent_status "Running" --icon "bolt.fill" --color "#4C8DFF"

# Clear status when done
cmux clear-status agent_status

Custom notification scripts

Create reusable notification scripts for common events:

~/bin/notify-success

#!/bin/bash
cmux notify \
  --title "${1:-Success}" \
  --subtitle "$(date +'%H:%M:%S')" \
  --body "${2:-Operation completed}"

~/bin/notify-error

#!/bin/bash
cmux notify \
  --title "${1:-Error}" \
  --subtitle "$(date +'%H:%M:%S')" \
  --body "${2:-Operation failed}"

Use in your workflows:

my-long-task && notify-success "Build" "Build succeeded" || notify-error "Build" "Build failed"

Viewing notifications

Use the cmux keyboard shortcuts to navigate notifications:

• Cmd+I: Open the notifications panel
• Cmd+Shift+U: Jump to the latest unread notification

Or use the CLI:

# List all notifications
cmux list-notifications

# List as JSON
cmux list-notifications --json

# Clear all notifications
cmux clear-notifications

Troubleshooting

Notifications not appearing

Verify the socket connection:

cmux ping

Check the socket path:

echo $CMUX_SOCKET_PATH
ls -l $CMUX_SOCKET_PATH

If the socket doesn’t exist, cmux may not be running.

Permission denied

The socket file must be owned by your user. Check:

ls -l /tmp/cmux.sock

If it’s owned by another user, quit cmux and restart it.

Wrong workspace receiving notifications

Verify the environment variables are set:

echo $CMUX_WORKSPACE_ID
echo $CMUX_SURFACE_ID

You can override them explicitly:

export CMUX_WORKSPACE_ID=workspace:2
cmux notify --title "Test" --body "Message"

Related commands

• cmux notify - Send notifications to workspaces
• cmux list-notifications - View pending notifications
• CLI Reference - Complete command reference including status and progress commands