#Notifications

coterm supports desktop notifications, allowing AI agents and scripts to alert you when they need attention.

#Lifecycle

Received: notification appears in panel, desktop alert fires (if not suppressed)
Unread: badge shown on workspace tab
Read: cleared when you view that workspace
Cleared: removed from panel

#Suppression

Desktop alerts are suppressed when:

The coterm window is focused
The specific workspace sending the notification is active
The notification panel is open

#Notification panel

Press ⌘⇧I to open the notification panel. Click a notification to jump to that workspace. Press ⌘⇧U to jump directly to the workspace with the most recent unread notification.

#Custom command

Run a shell command every time a notification is scheduled. Set it in Settings > App > Notification Command. The command runs via /bin/sh -c with these environment variables:

Variable	Description
`COTERM_NOTIFICATION_TITLE`	Notification title (workspace name or app name)
`COTERM_NOTIFICATION_SUBTITLE`	Notification subtitle
`COTERM_NOTIFICATION_BODY`	Notification body text

Examples

# Text-to-speech
say "$COTERM_NOTIFICATION_TITLE"

# Custom sound file
afplay /path/to/sound.aiff

# Log to file
echo "$COTERM_NOTIFICATION_TITLE: $COTERM_NOTIFICATION_BODY" >> ~/notifications.log

The command runs independently of the system sound picker. Set the picker to "None" to use only the custom command, or keep both for a system sound plus a custom action.

#Notification hooks

coterm.json can define notification hooks that receive every notification policy as JSON on stdin. Each hook returns JSON on stdout. Hooks are off by default; coterm only runs them when notifications.hooks contains at least one enabled hook. coterm applies the returned notification text and effects, so hooks can filter banners, keep or skip sidebar history, run sounds, or stop later hooks.

coterm.json

{
  "notifications": {
    "hooks": [
      {
        "id": "quiet-docs",
        "command": "sed 's/"desktop":true/"desktop":false/'",
        "timeoutSeconds": 20
      }
    ]
  }
}

Hook input and output

{
  "version": 1,
  "notification": {
    "workspaceId": "3B3F0D83-...",
    "surfaceId": "7E9C1A02-...",
    "title": "Codex",
    "subtitle": "Waiting",
    "body": "Agent needs input"
  },
  "context": {
    "cwd": "/path/to/project",
    "configPath": "/path/to/project/.coterm/coterm.json",
    "hookId": "quiet-docs",
    "appFocused": false,
    "focusedPanel": false
  },
  "effects": {
    "record": true,
    "markUnread": true,
    "reorderWorkspace": true,
    "desktop": true,
    "sound": true,
    "command": true,
    "paneFlash": true
  }
}

Hooks are inherited from global ~/.config/coterm/coterm.json and project .coterm/coterm.json files from parent directories to the current workspace. Project hooks use the same trust prompt as other project coterm.json commands before they run. Feed approval banners also pass through these hooks; disabling desktop suppresses the native banner while keeping the Feed item available in coterm. Set notifications.hooksMode to replace in a project config to ignore inherited hooks. If a hook fails, times out, or returns invalid JSON, coterm uses the default notification behavior and posts a hook failure alert.

#Sending notifications

#CLI

coterm notify --title "Task Complete" --body "Your build finished"
coterm notify --title "Claude Code" --subtitle "Waiting" --body "Agent needs input"

#OSC 777 (simple)

The RXVT protocol uses a fixed format with title and body:

printf '\e]777;notify;My Title;Message body here\a'

Shell function

notify_osc777() {
    local title="$1"
    local body="$2"
    printf '\e]777;notify;%s;%s\a' "$title" "$body"
}

notify_osc777 "Build Complete" "All tests passed"

#OSC 99 (rich)

The Kitty protocol supports subtitles and notification IDs:

# Format: ESC ] 99 ; <params> ; <payload> ESC \

# Simple notification
printf '\e]99;i=1;e=1;d=0:Hello World\e\\'

# With title, subtitle, and body
printf '\e]99;i=1;e=1;d=0;p=title:Build Complete\e\\'
printf '\e]99;i=1;e=1;d=0;p=subtitle:Project X\e\\'
printf '\e]99;i=1;e=1;d=1;p=body:All tests passed\e\\'

Feature	OSC 99	OSC 777
Title + body	Yes	Yes
Subtitle	Yes	No
Notification ID	Yes	No
Complexity	Higher	Lower

Use OSC 777 for simple notifications. Use OSC 99 when you need subtitles or notification IDs. Use the CLI (coterm notify) for the easiest integration.

#Claude Code hooks

coterm integrates with Claude Code via hooks to notify you when tasks complete.

#1. Create the hook script

~/.claude/hooks/coterm-notify.sh

#!/bin/bash
# Skip if not in coterm
[ -S /tmp/coterm.sock ] || exit 0

EVENT=$(cat)
EVENT_TYPE=$(echo "$EVENT" | jq -r '.hook_event_name // "unknown"')
TOOL=$(echo "$EVENT" | jq -r '.tool_name // ""')

case "$EVENT_TYPE" in
    "Stop")
        coterm notify --title "Claude Code" --body "Session complete"
        ;;
    "PostToolUse")
        [ "$TOOL" = "Task" ] && coterm notify --title "Claude Code" --body "Agent finished"
        ;;
esac

chmod +x ~/.claude/hooks/coterm-notify.sh

#2. Configure Claude Code

~/.claude/settings.json

{
  "hooks": {
    "Stop": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "~/.claude/hooks/coterm-notify.sh"
          }
        ]
      }
    ],
    "PostToolUse": [
      {
        "matcher": "Task",
        "hooks": [
          {
            "type": "command",
            "command": "~/.claude/hooks/coterm-notify.sh"
          }
        ]
      }
    ]
  }
}

Restart Claude Code to apply the hooks.

#GitHub Copilot CLI

Copilot CLI supports hooks that run shell commands at lifecycle events like prompt submission, agent stop, and errors.

~/.copilot/config.json

{
  "hooks": {
    "userPromptSubmitted": [
      {
        "type": "command",
        "bash": "if command -v coterm &>/dev/null; then coterm set-status copilot_cli Running; fi",
        "timeoutSec": 3
      }
    ],
    "agentStop": [
      {
        "type": "command",
        "bash": "if command -v coterm &>/dev/null; then coterm notify --title 'Copilot CLI' --body 'Done'; coterm set-status copilot_cli Idle; fi",
        "timeoutSec": 5
      }
    ],
    "errorOccurred": [
      {
        "type": "command",
        "bash": "if command -v coterm &>/dev/null; then coterm notify --title 'Copilot CLI' --subtitle 'Error' --body 'An error occurred'; coterm set-status copilot_cli Error; fi",
        "timeoutSec": 5
      }
    ],
    "sessionEnd": [
      {
        "type": "command",
        "bash": "if command -v coterm &>/dev/null; then coterm clear-status copilot_cli; fi",
        "timeoutSec": 3
      }
    ]
  }
}

For repo-level hooks, create a .github/hooks/notify.json file with the same structure:

.github/hooks/notify.json

{
  "version": 1,
  "hooks": {
    "userPromptSubmitted": [ ... ],
    "agentStop": [ ... ]
  }
}

#Integration examples

#Notify after long command

~/.zshrc

# Add to your shell config
notify-after() {
  "$@"
  local exit_code=$?
  if [ $exit_code -eq 0 ]; then
    coterm notify --title "✓ Command Complete" --body "$1"
  else
    coterm notify --title "✗ Command Failed" --body "$1 (exit $exit_code)"
  fi
  return $exit_code
}

# Usage: notify-after npm run build

#Python

python

import sys

def notify(title: str, body: str):
    """Send OSC 777 notification."""
    sys.stdout.write(f'\x1b]777;notify;{title};{body}\x07')
    sys.stdout.flush()

notify("Script Complete", "Processing finished")

#Node.js

node

function notify(title, body) {
  process.stdout.write(`\x1b]777;notify;${title};${body}\x07`);
}

notify('Build Done', 'webpack finished');

#tmux passthrough

If using tmux inside coterm, enable passthrough:

.tmux.conf

set -g allow-passthrough on

printf '\ePtmux;\e\e]777;notify;Title;Body\a\e\\'