Skip to main content
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

# 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

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.
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.
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"