Shell & Process Runtime (zsh)
Runtimes & APIsShell & Process Runtime (zsh)

Shell & Process Runtime (zsh)

Shell execution via /bin/zsh, environment variables, watchdog termination, and JSON protocol.

ShellProcessRunner & Isolation

Shell actions execute through ShellProcessRunner.swift:

  • Process Group Isolation: Runs under its own process group (setpgid).
  • Two-Stage Watchdog (30s): Fires after 30 seconds, sending SIGTERM to the process group, followed by SIGKILL after 1 second if unresponsive.
  • Non-Blocking Pipe I/O: Drains stdout and stderr asynchronously using GCD readability handlers.

Environment Variables

VariableDescription
$OPENCLIP_TEXTFull selected text string.
$OPENCLIP_MATCHEDRegex-matched substring.
$OPENCLIP_BUNDLE_IDFrontmost app bundle identifier (e.g. com.apple.Safari).
$OPENCLIP_CAPTURE_1 ... NPositional regex capture groups.
$OPENCLIP_ACTION_IDUnique identifier of the executing action.

Shell JSON Output Protocol

If your script outputs JSON on stdout, OpenClip maps it directly into native application effects:

JSON Output Schema
{
  "type": "paste",              // "paste" | "copy" | "openURL" | "notify" | "keyPress" | "toast"
  "text": "Transformed text",
  "message": "Operation completed",
  "style": "success",
  "keepVisible": false           // "toast" only: keep the popup open (default false)
}