command-notify

Desktop notifications for Command Code: know when the agent needs you or finishes a run while you work in another application.

Beta — 1.0.0-beta.1. This mod depends on Command Code's experimental Mods API, which may change and break compatibility. The current compatibility target is Command Code 1.58.x. macOS has prior desktop verification; native Windows and Linux delivery still need feedback from people using those desktops. This is not a claim that all three platforms have been verified.

Install

Requires Command Code and Node.js 22.6 or newer. Install the mod through Command Code's package manager, which also installs its notification dependency. There is no separate build or custom installer. The commands below work after the beta is published to npm.

macOS

cmd mods add -g command-notify@beta
cmd

The package includes terminal-notifier through its node-notifier dependency. If alerter is already installed it takes priority; otherwise the bundled helper is used, with macOS's osascript as a final fallback. No Homebrew package is required for the default installation. Allow the notification sender in System Settings → Notifications, and check Focus settings if banners are hidden.

Windows (native x64/x86)

In PowerShell:

cmdc mods add -g command-notify@beta
cmdc

Windows uses cmdc, because cmd is the Windows command shell. See Command Code on Windows. The matching SnoreToast helper ships through node-notifier; no PowerShell notification script or separate helper download is required. Enable notifications for its sender in Windows Settings and check Do not disturb.

Windows ARM64 and Windows toasts from WSL are not supported by this beta. The helper's default application identity must work on the desktop; that behavior still needs real Windows verification. Leave windowsAppId at null unless you already have a registered application identity. The mod does not register a custom identity or create a branded Start Menu shortcut.

Linux (native desktop)

Install notify-send if it is missing, using your distribution's package manager:

# Debian / Ubuntu
sudo apt install libnotify-bin

# Fedora
sudo dnf install libnotify

# Arch Linux
sudo pacman -S libnotify

Then, from a terminal inside your desktop session:

cmd mods add -g command-notify@beta
cmd

A working desktop notification service is required. X11 and Wayland environments are supported by the delivery path, but actual desktop behavior remains unverified. SSH, containers, and WSL are outside this beta's supported scope; notifications are not forwarded to another machine or to the Windows host.

Installation scope and updates

-g installs for your user across projects. Omit it to install only for the current Git project; project mods load after the workspace is trusted. Restart any existing Command Code session after installation.

To refresh the beta source:

cmd mods update

On Windows use cmdc mods update. This command updates/reconciles configured mod sources, not just this mod. To pin this release instead, install [email protected] in place of command-notify@beta.

Use it

Chat normally in Command Code, then switch to another application. There is no separate notification test step. The first session that creates the settings file shows a non-blocking notice with its location.

A notification is titled Command Code and identifies the session by its title, or the project folder name before a title exists. Linux includes that context in the body because its helper has no subtitle field.

| Event | What to expect | |---|---| | Agent asks a question | Needs your input in interactive sessions. | | Agent requests permission | Needs approval: <tool>, with risk information when supplied. | | Run finishes | Finished with a short result excerpt when available. | | Turn limit or mod stop hook ends a run | Stopped at the turn cap or Stopped early (mod). | | Run fails | Failed: <message>. | | Interruption | An interruption notification when the host's event path reports one; duplicate outcomes are suppressed. |

Question and permission alerts rely on events from the interactive Command Code UI. Headless runs can report outcomes, but do not expose the same prompt events. Background sub-agent completions are not separately announced. Pending alerts are removed or replaced where the backend supports it; completion alerts are left in the desktop's control. Bodies are shortened to about 150 characters. Notifications can contain project names, result excerpts, tool names, and error text; your OS may show those on the lock screen.

Delivery, sounds, expiry, and visibility depend on OS permissions, Focus/Do not disturb, desktop policy, and the selected helper. A successfully started helper cannot prove a banner appeared. Notification failures should produce a concise notice in Command Code, with the settings path and a recovery step, without interrupting the agent's work. Repeated identical problems are reported once per loaded mod instance.

Settings

Settings are per user, even when the mod is installed for one project:

| Platform | File | |---|---| | macOS / Linux | ~/.commandcode/notify.json | | Windows | %USERPROFILE%\.commandcode\notify.json ($HOME\.commandcode\notify.json in PowerShell) |

The mod creates the file with defaults when it first loads. Existing files are preserved. Edit it in any text editor; settings are reread for each notification. Use valid JSON, without comments. Missing fields keep their defaults. An invalid field uses its default and produces a warning; unreadable or malformed JSON uses the last valid settings, or defaults, and is never silently overwritten.

{
  "enabled": true,
  "backend": "auto",
  "questionFallback": "off",
  "questionText": "generic",
  "focusTerminalOnClick": true,
  "suppressWhenTerminalFocused": false,
  "replacePendingNotifications": true,
  "clearOnResolve": true,
  "quietHours": {
    "enabled": false,
    "start": "22:00",
    "end": "08:00",
    "bypassEvents": []
  },
  "debug": false,
  "debugVerbose": false,
  "alerterPath": null,
  "windowsAppId": null,
  "events": {
    "question": {"enabled": true, "sound": "Submarine", "timeout": 0},
    "permission": {"enabled": true, "sound": "Submarine", "timeout": 0},
    "done": {"enabled": true, "sound": "Glass", "timeout": 10},
    "error": {"enabled": true, "sound": "Basso", "timeout": 10}
  }
}

| Setting | Meaning | |---|---| | enabled | Enable or disable all notifications. | | backend | auto (recommended), alerter, terminal-notifier, osascript, notify-send, or snoretoast. An unavailable choice warns and falls back to this platform's automatic order. | | events.<event>.enabled | Enable each of question, permission, done, and error independently. | | events.<event>.sound | macOS sound name or none. Windows maps any name to its default notification sound; Linux sound selection is unsupported. | | events.<event>.timeout | Requested seconds until dismissal. 0 passes no explicit timeout; it does not guarantee a persistent banner. Windows and osascript ignore this setting; Linux/macOS desktop policy may override it. | | questionFallback | off or tool_queued. The latter uses queued ask-tool events if a host version does not deliver question interaction events. It never enables itself. | | questionText | generic (recommended) or heuristic. Heuristic text can associate the wrong question header because host events lack correlation IDs. | | focusTerminalOnClick | Activate a recognized terminal when clicking a terminal-notifier banner on macOS. Unsupported with other helpers. | | suppressWhenTerminalFocused | macOS only: suppress alerts while a recognized terminal is frontmost. A failed focus lookup allows delivery. | | replacePendingNotifications | Replace earlier pending alerts when supported. Does not replace run outcomes. | | clearOnResolve | Attempt to clear question/permission alerts after resolution or run settlement. Removal is best effort. | | quietHours.enabled | Enable scheduled suppression. | | quietHours.start / end | Local 24-hour HH:MM; start inclusive, end exclusive. Overnight windows work; equal times suppress nothing. | | quietHours.bypassEvents | Event classes allowed through quiet hours, such as ["error"]. Does not bypass global disablement. | | alerterPath | macOS executable path override, or null to search PATH. | | windowsAppId | Already registered Windows application identity, or null for the helper's default. | | debug | Write diagnostic metadata to notify-debug.log beside the settings file. Off by default. | | debugVerbose | With debug, include helper arguments and notification text in that log. Off by default; avoid sharing verbose logs unredacted. |

Change settings from a conversation

These commands save to the same user settings file:

Plain /notify shows the settings file location and available settings commands.

| Command | Effect | |---|---| | /notify on / /notify off | Enable or disable notifications. | | /notify backend auto | Restore automatic backend choice and reset failure tracking. A specific backend name is also accepted. | | /notify sound done none | Silence completion alerts; substitute another event or sound name. | | /notify timeout done 10 | Request a ten-second completion banner; off passes no timeout. | | /notify quiet-hours on 22:00 08:00 | Enable an overnight quiet window. | | /notify quiet-hours off | Disable quiet hours. |

Invalid command arguments change nothing. Setters refuse to overwrite malformed JSON. A lock prevents simultaneous sessions from overwriting each other's edits; if a write cannot obtain it, a notice explains the failure. Remove a leftover notify.json.lock only after closing all Command Code sessions that may write it.

Session overrides

Command Code's --mod-option flags override the file for that session:

cmd --mod-option enabled=false
cmd --mod-option sound=none

Use cmdc on Windows. Available flags are enabled=true|false, backend=<name>, sound=<name|none>, timeout=<seconds|off>, and debug=true|false. Sound and timeout flags affect every event class. A settings command tells you when a launch flag still overrides the saved value. Flag names are shared with other mods; prefer the JSON file if another mod uses these names.

Platform differences

| Platform/helper | Sound | Expiry | Clear pending alert | Click to terminal | |---|---|---|---|---| | macOS: alerter | Named or silent | Requested | Best effort | No | | macOS: bundled terminal-notifier | Named or silent | Requested | Best effort | Recognized terminal | | macOS: osascript fallback | Named or silent | OS-controlled | No | No | | Linux: notify-send | No selection | Desktop may ignore | No | No | | Windows: bundled SnoreToast | Default or silent | OS-controlled | Best effort | No |

macOS automatic order is alerter → terminal-notifier → osascript. Linux uses notify-send; Windows uses the helper matching the running Node.js architecture (x64 or ia32). Helpers for other platforms are never executed. Linux notifications escape markup characters; rendering may differ by desktop. Some macOS helpers can remain alive while waiting for interaction. Bounded helper operations can only be stopped while the Command Code session is still running.

Troubleshooting

• Nothing appears: check enabled, the relevant event's enabled, quiet hours, and OS notification permissions/Focus. Continue a normal conversation with Command Code and watch for its failure notice. Silent OS suppression may produce no helper error.
• Linux helper missing: install the libnotify package above and run from a terminal in your logged-in desktop session. A headless environment does not become a desktop merely by installing notify-send.
• Windows silent delivery: check Windows notification settings and the helper's sender identity. Keep windowsAppId: null unless you know the configured identity is registered. Report the OS, Node architecture, Command Code version, and any failure notice; Windows desktop delivery is still awaiting beta verification.
• Helper missing or cannot start: reinstall the mod through Command Code's package manager, check executable permissions/security software, and restart.
• Helper marked unhealthy: correct the reported problem, then restart Command Code or use /notify backend auto. Later notifications skip failing helpers; already submitted notifications are not reposted automatically.
• Invalid settings: repair the JSON file at the path in the notice. Rename it if you want to preserve it while allowing defaults to be recreated next session.
• Question alerts missing after a host update: try questionFallback: "tool_queued" in the settings file. Generic question text is safest. Mods API changes may require a new mod release.
• Need diagnostic detail: temporarily set debug: true, reproduce through normal conversation, and inspect notify-debug.log beside the settings file. Standard diagnostics omit notification bodies but may include local paths and identifiers. Review and redact logs before sharing them.

Uninstall

Close running Command Code sessions, then remove the same source and scope used at installation. For the global beta installation above:

macOS / Linux:

cmd mods remove -g command-notify@beta

Windows PowerShell:

cmdc mods remove -g command-notify@beta

For project installation, omit -g and run inside that project. If you installed an exact version, use that version instead of @beta. Restarting ensures the mod is no longer loaded. Removing a package does not dismiss every existing OS banner.

Settings and diagnostics are intentionally retained so a reinstall preserves preferences. To remove them too, delete only these files after closing sessions:

macOS / Linux:

rm -f "$HOME/.commandcode/notify.json" "$HOME/.commandcode/notify-debug.log" "$HOME/.commandcode/notify.json.lock"

Windows PowerShell:

Remove-Item -LiteralPath "$HOME\.commandcode\notify.json", "$HOME\.commandcode\notify-debug.log", "$HOME\.commandcode\notify.json.lock" -ErrorAction SilentlyContinue

Do not delete the whole .commandcode directory: it contains other Command Code settings. OS notification history is cleared separately in the notification center. Any custom Windows identity you registered manually must also be removed manually.

Privacy and license

The mod itself sends no network requests and needs no API keys. Notification text is handed to local OS helpers. Debug logging is opt-in; verbose logging can store conversation excerpts. Runtime settings and logs live outside this repository.

MIT; see LICENSE. Third-party helpers and dependencies retain their own licenses, supplied with those packages. Maintainers can find publication steps in RELEASING.md in the source repository.