Skip to content
EN
Download

Signals

A signal runs a shell command when something happens: a window opens, the space changes, an app starts. A bar such as SketchyBar redraws its spaces this way.

Edit signals on Settings › Signals: under New Signal, choose the Event, type the Command, optionally limit it to an app or a window title, and click Add Signal. Your Signals lists the signals you have. In the file each signal is a [[signal]] entry:

[[signal]]
event = "space_changed"
action = "sketchybar --trigger space_change"

The command runs through your login shell, detached; its output is not kept.

Event When
window_created, window_destroyed A window opens or closes
window_focused A window gets the focus
window_moved, window_resized A window moves or changes size, also when the layout places it
window_minimized, window_deminimized A window goes into the Dock or comes back
space_changed Another space is shown
space_created, space_destroyed A space is added or removed
display_added, display_removed A display is connected or removed
display_changed Another display has the focus
app_launched, app_terminated An app starts or quits
app_activated An app comes to the front
app_hidden, app_shown An app is hidden or shown again
mission_control_entered, mission_control_left Mission Control opens or closes
system_woke The Mac wakes from sleep

Each change is reported once. The windows and spaces that exist when TilingBud starts are not events.

For window and app events, a signal can be limited as a window rule is: app (a name or a program path), except_apps, and title or except_title as regular expressions on the window title. Other events ignore them. label gives the signal a name, shown in Settings and in query --signals.

[[signal]]
event = "window_focused"
app = "iTerm2"
except_title = "^vim"
action = "~/bin/terminal-focused.sh"
label = "terminal"

The command gets the event’s values as environment variables, each only where the event has it:

Variable Value
TILINGBUD_EVENT The event’s name
TILINGBUD_WINDOW_ID The window’s id
TILINGBUD_PROCESS_ID The app’s process id
TILINGBUD_SPACE_INDEX The space’s number over all displays (index in query --spaces)
TILINGBUD_SPACE_ID The space’s id
TILINGBUD_RECENT_SPACE_INDEX The space shown before, for space_changed
TILINGBUD_DISPLAY_INDEX The display’s number
TILINGBUD_DISPLAY_ID The display’s UUID
[[signal]]
event = "space_changed"
action = "sketchybar --trigger space_change SPACE=$TILINGBUD_SPACE_INDEX"

A tool can keep tilingbud subscribe running and read one JSON line per event. Nothing is started per event and no [[signal]] entry is needed:

Terminal window
tilingbud subscribe space_changed window_focused | while read -r line; do
echo "$line" | jq .space_index
done

Without event names it reports every event. tilingbud subscribe nope fails and lists the event names. See the command line for the fields of each line.

  • A bar redraws its spaces on space_changed.
  • A script sets a chat status when a certain space opens, from space_changed and TILINGBUD_SPACE_INDEX.
  • A layout script runs when a display is plugged in, on display_added.

Every key is in the reference.