Run desk setup actions automatically when a monitor connects

Have your desk monitor return to a comfortable, previously tested brightness when BetterDisplay detects it reconnecting. This recipe attaches one fixed, explicitly targeted shell script to the monitor’s Hard reconnect event. It leaves connection, input and display mode decisions to you.

Before you begin

The event editor has no separate Pro requirement. This recipe uses the existing hardware-brightness control, not a new custom control. Confirm its owner remains the intended DDC controller after adding Control Integration. Existing integration definitions can replace feature ownership.

Prepare a paused reconnect event

  1. With the intended monitor connected, open Settings > Displays > [monitor] > Device Control > Add or Remove Controllers…. Choose Add beside Control Integration if it is not already added. Keep existing definitions and feature assignments. This task does not need Configure Integration Controls….
  2. In the monitor’s Control Integration section, open Configure Events…. Choose Add Event… > Select Event… > Hard reconnect. Only hooks not already added appear. If Hard reconnect is already configured, review its existing action before changing it. The procedure below creates a new event on a monitor without that hook.
  3. Leave Action at its initial Do nothing. The new card saves immediately. It stays inactive while Do nothing is selected.

Native Event integration sheet with a new Hard reconnect event paused as Do nothing.

Prepare the new event with Do nothing before selecting an action.

Hard reconnect means a remembered display is rediscovered, marked connected and has its controllers set up. It is not every configuration refresh or the first discovery of an unknown monitor, and it does not guarantee the hardware has finished becoming ready.

Make and test one fixed brightness script

  1. Use the monitor’s own menu and BetterDisplay to establish a comfortable, visible hardware brightness. Do not assume a stale app slider describes the panel’s starting level. Record the tested setting and verify that changing it really changes the intended monitor without changing another display.
  2. Open Settings > Displays > [monitor] > Display Information… > Identifiers and record its actual Tag ID. This is BetterDisplay’s local remembered identity, not a permanent cross-Mac identifier. Keep that tag and -type=Display in every request. Omitting the selector can target multiple devices. Do not substitute a runtime display ID or a different monitor’s tag.
  3. Save the following as a new plain-text desk-brightness.zsh file in a stable folder you own. Replace the executable path if BetterDisplay is installed elsewhere, REPLACE_WITH_TAG_ID with the actual positive numeric tag, and REPLACE_WITH_TESTED_LEVEL with the value you will manually verify on the normalized 0–1 scale. Keep straight quotes and preserve the explicit target in both requests.
#!/bin/zsh
bd='/Applications/BetterDisplay.app/Contents/MacOS/BetterDisplay'
tag='REPLACE_WITH_TAG_ID'
level='REPLACE_WITH_TESTED_LEVEL'

if [[ ! "$tag" =~ '^[1-9][0-9]*$' ||
      ! "$level" =~ '^(0(\.[0-9]+)?|1(\.0+)?)$' || ! -x "$bd" ]]; then
    printf '%s\n' 'Configure the actual executable, Tag ID and tested level first.' >&2
    exit 64
fi

if ! "$bd" get -type=Display -tagID="$tag" -hardwareBrightness >/dev/null; then
    printf '%s\n' 'Target hardware brightness is unavailable; no write requested.' >&2
    exit 1
fi

if "$bd" set -type=Display -tagID="$tag" -hardwareBrightness="$level" -min=0 -max=1; then
    printf '%s\n' 'Desk brightness request accepted.'
else
    printf '%s\n' 'Desk brightness request failed.' >&2
    exit 1
fi

-min=0 -max=1 maps the chosen number across the control’s configured minimum and maximum. For example, 0.4 means 40% of that configured span. It is not a universal monitor percentage or measured luminance. Use it only if that mapped setting has been tested on your monitor. Choose a visible, comfortable value rather than either endpoint by habit. This explicitly requests hardware brightness instead of automatic hardware/software/combined selection.

The initial get succeeds only when this connected target has an available control. It reads the app’s stored value, not fresh DDC readback, and the script discards it. It neither detects actual luminance nor guarantees readiness for the following write. An absent or unavailable target produces a failure and no set request. The script makes at most one probe and one write, with no retries, toggles or connection changes.

  1. With the event still paused, run the saved script once in Terminal using /bin/zsh and its actual absolute quoted path. For example, replace the account/folder placeholders in the next line before using it. Explicitly invoking zsh means the file need not be made executable. Apple explains running commands in Terminal.
/bin/zsh "/Users/YOUR_ACCOUNT/BetterDisplayActions/desk-brightness.zsh"
  1. Read the output and check the physical monitor. A successful CLI request returns exit status zero. A failed request reports an error. Desk brightness request accepted. confirms app handling, not completed hardware change. Verify the real brightness, other monitors and recovery desktop before activating the event. If anything is wrong, leave Do nothing selected and correct the target, range or hardware path first.

Activate and check a controlled reconnect

  1. Open App Menu > Tools > Show Console and turn on Logging. Keep logs private until reviewed for identifiers, paths and command contents. Use the console to inspect the logs. Run the shell script through Terminal or the event action, not the console's integration prompt.
  2. Return to the monitor’s event editor. Change Action to Run shell script and enter the manually tested /bin/zsh "…actual absolute script path…" invocation in Shell script (zsh). Explicitly invoking /bin/zsh runs the saved file with its intended interpreter.
  3. Leave Timeout and Redundancy filter time interval blank for their defaults of 10 seconds and 1 second. You do not need to enter the displayed defaults. Timeout does not kill a shell process or roll back a write. The redundancy filter suppresses recently identical expanded payloads of the same action type across this controller’s controls and events. It does not prevent loops.

Native Hard reconnect event with Run shell script, an explicit zsh invocation, and blank optional timing fields.

The saved action invokes the validated script. Blank timing fields retain their defaults.

  1. All edits are already active. With the recovery desktop visible, perform one controlled physical disconnect/reconnect of the intended desk monitor. Allow it to become a remembered display before reconnecting. Test one monitor and one script at a time. Keep the same cables, controller configuration and picture settings used for the manual test.
  2. Inspect the console for the actual integration script dispatch and its output. Wait for the process and pending hardware requests to finish, then check the monitor’s actual brightness. If it failed, set Action back to Do nothing before investigating. Do not repeatedly reconnect to hide an unexplained failure.

BetterDisplay Console with Logging enabled and genuine script output reporting that the desk brightness request was accepted.

Inspect real script output, then verify the monitor’s brightness separately.

Check the result

Confirm that one remembered-monitor return requests the script and the monitor reaches the same comfortable brightness as the manual test. Confirm that other displays, selected input, modes and the independent desktop remain usable. When a later controlled reconnect repeats the same fixed setting, it should not keep increasing brightness as a relative increment would.

App logs and a zero exit status establish request handling. Check the panel separately. The event runs when BetterDisplay detects the monitor reconnecting. It does not continuously enforce brightness or undo the action automatically.

Choose other events only when needed

Hard disconnect runs when a display leaves active duty and becomes remembered. It does not prove a physical cable was pulled. Soft reconnect runs before BetterDisplay’s own connection attempt after early safety checks, while Soft disconnect follows its disconnect attempt. These timings are poor substitutes for a ready hardware-brightness path.

System sleep addresses currently connected displays. System wake (immediate) runs before the app’s global wake delay. System wake is the later pass after that delay and before subsequent display-configuration work. Neither promises hardware readiness or completion of another action. One operation can lead to several hooks, and actions can run concurrently. Use only Hard reconnect for this setup. See wake recovery for a separate task.

If you later reuse parameters, replacement is literal and case-sensitive. The app replaces built-in tokens first, then predefined parameters, then display parameters. Inserted content is not shell-escaped. This fixed script deliberately avoids interpolating [*:DEVICE_NAME:*] or a runtime [*:DISPLAY_ID:*]. Punctuation in inserted text could change the shell command. Event actions have no VALUE substitution. Refer to event parameters before extending the recipe. Time-of-day scheduling is a separate workflow.

Troubleshooting

Undo the test setup

  1. Set this event’s Action to Do nothing to stop future runs. Let pending scripts and hardware requests finish. Changing the action, removing the event or reaching its timeout does not cancel work already sent.
  2. Set your preferred monitor brightness. Removing the event or controller does not restore hardware settings.
  3. To delete the hook, choose Remove Event on the new Hard reconnect card. It deletes immediately without confirmation. Delete the script file when no retained action uses it. If you no longer need Control Integration, remove its controller after deleting the event. Controller removal retains saved definitions.
  4. Re-enable any automatic rules you paused if you still want them.
  5. Turn Logging off when you finish. Disable CLI access only if no remaining workflow needs it. Turn built-in automatic disconnection back on only if you want that behavior again and an external desktop is usable.

Additional information

This section explains licensing and platform requirements.

Features requiring Pro license

Event configuration, shell actions, CLI access and ordinary supported DDC hardware brightness have no separate Pro requirement. Requested advanced features retain their own requirements. This recipe does not create a Pro custom control or use Pro connection-management queries or operations.

Platform compatibility

BetterDisplay requires macOS 26.3 or later. Event Integration and this shell workflow are available on Apple silicon and Intel Macs. Actual DDC support depends on the monitor, adapter and transport. The monitor must be connected to configure the event, and BetterDisplay must remain running for its CLI requests. No Screen Recording or native-media-key permission is needed for this fixed brightness script.