Event callbacks #
Callbacks are off by default. Set an argument array in TOML, then reload the configuration. The first argument must be an absolute executable path. An empty array disables that callback. Parcel does not add a shell or expand arguments.
[callbacks]
exec-on-window-opened = ["/Users/you/bin/window-opened"]
exec-on-window-closed = []
exec-on-focus-changed = []
exec-on-layout-changed = []
exec-on-space-changed = []
Callbacks describe committed changes to managed windows and native Spaces. The first committed startup batch, synthetic config-reload changes, unchanged commands, and shutdown do not fire callbacks. Real window events queued around a reload still fire using the active callback configuration. Windows discovered in later batches are reported when they become managed. A batch emits its final state, not transient changes within the batch.
The environment contains only PATH, HOME, LANG, PARCEL_EVENT, and,
where available, PARCEL_WINDOW_ID, PARCEL_APP_PID, PARCEL_BUNDLE_ID,
PARCEL_WINDOW_TITLE, PARCEL_DISPLAY_ID, PARCEL_SPACE_ID, and PARCEL_LAYOUT.
The three base values come from Parcel's launch environment. When absent, they
use /usr/bin:/bin:/usr/sbin:/sbin, the current user's home directory, and
en_US.UTF-8, respectively. Other launch variables, including old PARCEL_*
values, are not inherited. Closed-window callbacks use the window's last known
values. Focus clearing has no window ID.
PARCEL_WINDOW_TITLE is untrusted data. Quote it when passing it as an argument;
never turn it into shell source with sh -c or eval.
Jobs run one at a time, away from the main thread, with room for 32 waiting jobs. Each job has its own process group and a 30-second deadline. Timeout and shutdown kill the whole group, including forked children. Background children also stop when their callback's direct process exits. Do not detach work into another process group or session, or change process credentials: callbacks are not a sandbox and cannot contain that work. Cleanup failures are surfaced without waiting indefinitely for a process Parcel cannot signal. Shutdown discards all waiting jobs. A successful config reload discards waiting jobs whose event was removed, disabled, or given different arguments; unchanged jobs retain their order, and the running job finishes.
Spawn failures, nonzero exits, and timeouts reach the app's notice surface.
Queue overflow drops the newest jobs and reports a count, coalesced over one
second rather than one notice per job. Standard input is /dev/null; unrelated
file descriptors are closed. Output never shares Parcel's stdout or stderr.
Each stream keeps only its last 16 KiB, with discarded-byte counts in the
callbacks OSLog category. Captured text is private in the log. Failure notices
include at most the last 1 KiB of stderr, which may contain script output or
window titles.
Use at most 64 arguments, 4096 UTF-8 bytes per argument, and 16384 bytes total. NUL characters are rejected. Empty non-executable arguments are allowed.