Inspect and apply macOS display layouts with MagicDisplay.
MagicDisplay is macOS-only and links private macOS display frameworks. No installer package is currently published. Build from source on macOS with Xcode command line tools:
cd src make # Run the built binary from the repository src/magicdisplay list
magicdisplay list
This prints the current display information and the raw profile command needed to reproduce it.
You can apply a complete layout from a single command line, matching the displayplacer argument model:
magicdisplay "id:<screenId> res:<width>x<height> hz:<num> color_depth:<num> scaling:<on/off> origin:(<x>,<y>) degree:<0/90/180/270>"
Disable a display:
magicdisplay "id:<screenId> enabled:false"
Run magicdisplay --help for the full command reference.
Profiles are named snapshots of the full state of every connected display: resolution, refresh rate, color depth, scaling, position, rotation, mirroring, and enabled state.
Save the current display setup (use --force only when intentionally replacing an existing profile):
magicdisplay profile save home magicdisplay profile save home --force
List saved profiles and inspect one:
magicdisplay profile list magicdisplay profile show home
Preview a profile without changing any displays, then apply it:
magicdisplay profile apply home --dry-run magicdisplay profile apply home
Delete a profile that is no longer needed:
magicdisplay profile delete old-office
If profile apply reports that a saved display no longer resolves because macOS reassigned its persistent screen id (a dock, cable, or GPU switch), fix the profile in one command instead of hand-editing UUIDs:
magicdisplay profile remap home
profile remap rewrites each stored display's persistent, serial, and contextual ids to the currently connected displays using the same fallback matching as apply. It is all-or-nothing: if any stored display is missing or ambiguous, the profile file is left unchanged and you get a clear error.
.mdprofile file in the MagicDisplay profiles directory. The default location is ~/.config/magicdisplay/profiles/; when XDG_CONFIG_HOME is set, MagicDisplay uses $XDG_CONFIG_HOME/magicdisplay/profiles/ instead. Each profile is a separate text file that can be reviewed, copied, shared, or version-controlled.
A retained layout defines a preferred relative position for external displays against an anchor display, and works for monitors MagicDisplay has never seen before.
Save a preferred relative layout:
magicdisplay layout set position:above
Saving an explicit position or anchor confirms the retained layout. Check the stable readiness signal and current values with magicdisplay layout show; Configured: no means the displayed defaults have not yet been confirmed.
Confirm a saved profile as the automation target:
magicdisplay layout set profile:home
When a topology change is detected, a confirmed profile restores its full display state: resolution, refresh rate, color depth, scaling, position, rotation, mirroring, and enabled state. No confirmed profile uses the existing relative-position layout. If the confirmed profile is unresolved or ambiguous, restoration fails all-or-nothing; use magicdisplay profile remap <name> to recover it.
Disable or enable automation notifications:
magicdisplay layout set notifications:off magicdisplay layout set notifications:on
Preview the layout MagicDisplay would apply to the currently connected displays, or preview against a fixture file without touching real display settings:
magicdisplay layout preview magicdisplay layout preview --fixture fixtures/office-monitor.txt
Apply the saved layout:
magicdisplay layout apply
The default anchor is the built-in laptop display. To return to that default explicitly:
magicdisplay layout set anchor:builtin
To disable automatic layout application in config (the running agent re-reads this on each poll cycle, so no reinstall is needed):
magicdisplay layout set automation:off
Enabling automation, installing the agent, or starting it is rejected until a layout has been explicitly confirmed. Manual magicdisplay layout apply remains available regardless of readiness or automation state.
Install and start the macOS LaunchAgent:
magicdisplay agent install
Manage the agent:
magicdisplay agent status magicdisplay agent stop magicdisplay agent start magicdisplay agent uninstall
The agent polls display topology every 3 seconds, waits 3 seconds after a topology change, applies the retained layout, and retries failed applies twice. Logs are written to ~/Library/Logs/magicdisplay-agent.log.
Notifications are enabled by default. The agent notifies when it arranges a display, when a detected display already matches the layout, and when MagicDisplay cannot arrange displays after retries.
Agent lifecycle commands are safe to repeat:
magicdisplay agent install requires a confirmed layout, then rewrites the user LaunchAgent plist, enables automation in MagicDisplay config, and starts the agent.magicdisplay agent start requires a confirmed layout, then enables automation and asks launchctl to kickstart the user agent.magicdisplay agent stop disables automation and asks launchctl to boot out the user agent.magicdisplay agent status reports the user agent state through launchctl print.magicdisplay agent uninstall stops the agent and removes the user LaunchAgent plist.Single-instance behavior is delegated to the macOS user LaunchAgent label com.magicdisplay.agent. The failure model is bounded: after a topology change, the agent waits for the debounce interval, applies the retained layout, retries failed applies twice, writes output to the agent log, and sends a failure notification when notifications are enabled.
A menu bar app scaffold lives in app/. On macOS, build it from that directory:
cd app make
MagicDisplay is inspired by and currently includes code derived from jakehilborn/displayplacer, licensed under MIT. See the repository's NOTICE.md and LICENSE.displayplacer.