opencode-notify

The plugin uses different backends depending on your operating system:

• macOS: Uses alerter via the Notification Center. Requirement: You must have alerter installed and available on your PATH (e.g., brew install vjeantet/tap/alerter).
• Windows: Uses Toast notifications via the SnoreToast backend.
• Linux: Uses notify-send.

cmux Integration

If you are running inside cmux (detected via the CMUX_WORKSPACE_ID environment variable), the plugin attempts to route notifications through the cmux notify command:

cmux notify --title "..." --subtitle "..." --body "..."

If cmux is unavailable or the command fails, the plugin automatically falls back to the standard desktop notification paths (e.g., alerter on macOS).

To install the opencode-notify plugin for OpenCode V1, use the ocx add command pointing to the KDCO registry.

Note: This plugin is retired and only supports OpenCode V1. For OpenCode V2, use the native terminal notification and sound settings in cli.json instead.

To install the plugin individually:

ocx add kdco/notify --from https://registry.kdco.dev

To install the full kdco-workspace bundle (which includes notifications along with background agents and planning tools):

ocx add kdco/workspace --from https://registry.kdco.dev

The kdco-primitives module provides utility functions to ensure shell commands are safely escaped before execution, preventing injection attacks or syntax errors across different operating systems and shells.

Available escaping utilities:

• escapeAppleScript: For AppleScript commands.
• escapeBash: For Bash/shell commands.
• escapeBatch: For Windows Batch commands.
• assertShellSafe: A validation utility to ensure a string is safe for shell execution.

To ensure commands are executed safely across different operating systems and terminal environments, use the provided escaping utilities. This prevents shell injection and ensures syntax correctness for specific shells.

Available utilities:

• escapeAppleScript: For macOS AppleScript commands.
• escapeBash: For Bash/Zsh environments.
• escapeBatch: For Windows Batch environments.
• assertShellSafe: To validate that a string is safe for shell execution.

import { escapeBash, assertShellSafe } from "kdco-primitives";

const safeCmd = escapeBash("echo 'hello world'");
assertShellSafe(safeCmd);

The primitives provide tools to detect if the current environment is running within a cmux workflow. This is useful for determining how notifications should be routed or displayed.

Key exports:

• detectCmuxContext: Identifies the current CmuxContext.
• canUseCmuxWorkflow: Boolean check for Cmux compatibility.
• CmuxContext: Type representing the detected context.
• CmuxEnvironment: Type representing the environment type.

import { detectCmuxContext, canUseCmuxWorkflow } from "kdco-primitives";

if (canUseCmuxWorkflow()) {
  const context = detectCmuxContext();
  // Handle cmux-specific logic
}

Use the following utilities to gather context about the current environment:

• getProjectId: Retrieves the unique identifier for the current project.
• getTempDir: Retrieves the appropriate temporary directory path for the current OS.
• isInsideTmux: Detects if the current terminal session is running inside a tmux multiplexer.

To prevent long-running notification or shell tasks from hanging, wrap them in the withTimeout utility. If the operation exceeds the specified duration, it will throw a TimeoutError.

import { withTimeout, TimeoutError } from "kdco-primitives";

try {
  await withTimeout(async () => {
    // Perform notification or shell task
  }, 5000); // 5 second timeout
} catch (e) {
  if (e instanceof TimeoutError) {
    console.error("Task timed out");
  }
}