Documentation

Transparency v1.0.0. Everything below is true of the shipping build — if something is not built yet, this page says so rather than implying it.

Requirements

This is the part to read before anything else, because one of these is a real commitment to your machine's security posture.

• macOS 14.0 or newer, Apple silicon and Intel.
• yabai, with its scripting addition loaded.macOS has no public API for per-app window opacity. The only mechanism is SkyLight's private SLSSetWindowAlpha, reachable only by injecting into Dock.app. That is what the scripting addition does.
• System Integrity Protection partially disabled, which is what the scripting addition requires. Check with csrutil status: Filesystem Protections, Debugging Restrictions, NVRAM Protections and Boot-arg Restrictions must all read disabled.
• yabai -m config window_opacity on in your yabairc.

Install and configure yabai

Do this first. Transparency is a control surface for yabai — without the scripting addition loaded there is nothing for it to drive, and the app will tell you so rather than appearing to work.

These steps are for Apple silicon on macOS 13 or newer. They change your machine's boot security settings, so read each one before running it.

1. Install yabai

brew install koekeishiya/formulae/yabai
yabai --start-service

2. Partially disable System Integrity Protection

This must be done from recoveryOS — it cannot be done from a running system. Shut down, then hold the power button until Loading startup options appears → Options → Continue → Utilities → Terminal, and run:

csrutil enable --without fs --without debug --without nvram

The warning it prints about an unsupported configuration is expected — that is exactly what you asked for. Reboot.

3. Set the boot argument

Check what is already there first, then write the combined value:

# 1. See what you already have. If this prints nothing, you have none.
nvram boot-args 2>/dev/null

# 2a. If it printed NOTHING:
sudo nvram boot-args="-arm64e_preview_abi"

# 2b. If it printed something, keep it. For example, a machine already carrying
#     "debug=0x146 kext-dev-mode=1" must be set like this — your existing values,
#     not these:
sudo nvram boot-args="-arm64e_preview_abi debug=0x146 kext-dev-mode=1"

Reboot again, then confirm both settings took:

csrutil status      # expect "disabled", or "unknown (Custom Configuration)"
nvram boot-args     # expect -arm64e_preview_abi AND anything you had before

4. Load the scripting addition

The scripting addition needs to run as root. Rather than typing a password every time, yabai is granted one specific passwordless command, pinned to the SHA-256 of the exact binary — so a replaced or tampered yabai does not inherit the permission.

echo "$(whoami) ALL=(root) NOPASSWD: sha256:$(shasum -a 256 $(which yabai) | cut -d " " -f 1) $(which yabai) --load-sa" | sudo tee /private/etc/sudoers.d/yabai

sudo yabai --load-sa
yabai --restart-service

5. Configure yabai so it does not change how you work

yabai defaults to bsp, a tiling layout that takes over the position and size of every window. If you installed yabai purely to get per-app opacity, you almost certainly do not want that — and it is the reason double-clicking a title bar stops filling the screen (see Windowing behaviour).

Put this in your yabairc to keep macOS window behaviour completely native:

# ~/.config/yabai/yabairc

# Keep macOS windowing exactly as it was. yabai still applies opacity;
# it stops moving, resizing and tiling your windows.
yabai -m config layout float

# Required for per-app opacity to apply at all.
yabai -m config window_opacity on

# Reload the scripting addition automatically when the Dock restarts.
yabai -m signal --add event=dock_did_restart action="sudo yabai --load-sa"
sudo yabai --load-sa

Then yabai --restart-service. If you actually do want tiling, use bsp instead — everything in Transparency works identically either way.

Install Transparency

Build from source. One command builds, tests, installs, and registers the login item:

git clone https://github.com/deepakmarathe/transparency-mac.git
cd transparency-mac
sh build.sh install

That puts the app in /Applications, links a transparency CLI onto your PATH, enables launch at login, and starts it. Re-run it any time to upgrade in place.

Other build commands

sh build.sh            # build the bundle here, run the tests
sh build.sh install    # build, install, enable login item, launch
sh build.sh uninstall  # unregister, quit, remove; leaves your yabairc alone
sh build.sh status     # what is installed and running

Using it

Click the menu bar icon. Every running app is listed with a slider. Drag one and the change lands on every open window of that app immediately, then gets written to your yabairc so it survives a restart.

Sliders floor at 20% by default — a window dragged to invisible is a window you cannot get back. You can change that floor in Settings.

Settings

• Licence status and activation.
• Launch at login, and whether the panel opens on launch (off by default).
• The slider floor.
• Every managed rule, with a delete button per rule.
• yabai status, a restart button, and a link to your yabairc.

Command line

The CLI is free in every tier, forever. The bundle's binary is the CLI: with no arguments it runs as the menu bar app, with any of these it does the job and exits.

--show and --quit talk to the already-running instance over a distributed notification.

Licence and activation

Free covers 3 apps. Pro removes the limit for 3 machines; Studio covers 10. Both are one-time purchases — there is no subscription.

After buying you get a licence key by email. Paste it into Settings, or activate from a script:

transparency --activate TR1.xxxxx.yyyyy
transparency --license

How verification works

Your key is an Ed25519-signed token. The app verifies it on your machine against a public key compiled into the binary — it never contacts a payment provider, and it works with no network at all. If we disappeared tomorrow, every licence sold would keep verifying. A 14-day Pro trial is the same mechanism with a short expiry.

Device limits are advisory: an offline-verifiable token can be copied. We think that is the right trade for a utility at this price, and we would rather say so than pretend otherwise.

How persistence works

The app owns one marked block in your ~/.config/yabai/yabairc and rewrites only that. Everything outside the markers is preserved byte for byte.

# >>> transparency.app managed >>>
yabai -m rule --add app="^Transparency$" manage=off
yabai -m rule --add app="^[Gg][hH][oO][sS][tT][tT][yY]$" opacity=0.77
# <<< transparency.app managed <<<

App names are written as two-case character classes on purpose. yabai matches app= as a case-sensitive regex, and the name it reports for a window is not always the name macOS gives the application — Ghostty reports its real terminal window as ghostty and a helper window of the same process as Ghostty. A single-case rule matches only one of them.

The first line keeps yabai from tiling the app's own settings panel. Without it, yabai treats the panel as a document window and reflows your real windows around it.

More than one thing writes this file: the app, the CLI in another process, and your own editor. A write only overwrites the app names that session actually changed, merging everything else from what is on disk.

Windowing behaviour

Transparency does not manage windows, and installing it does not change how any window is tiled, focused, sized or placed. It writes exactly one kind of rule for your apps — opacity — plus a single manage=off for its own settings panel, so that panel does not get dragged into your layout. The build fails if that ever stops being true.

Double-clicking a title bar stopped filling the screen

This is the one people hit after installing yabai, and it looks like this app caused it. It did not — yabai did, and it is doing its job.

In yabai's default bsplayout, yabai owns the frame of every managed window. macOS still fires your double-click action (System Settings → Desktop & Dock → “Double-click a window's title bar to”), the window briefly changes size, and yabai re-tiles it back immediately. Every tiling window manager behaves this way; it is the trade you accepted for tiling.

Pick whichever matches how you want to work:

# 1. Keep tiling, use yabai's own maximise. Bind it in skhd —
#    this is what most yabai users do:
alt - f : yabai -m window --toggle zoom-fullscreen

# 2. Exempt specific apps from tiling so they behave natively again.
#    Put this in ~/.config/yabai/yabairc, OUTSIDE the transparency.app markers:
yabai -m rule --add app="^(Preview|Photos|QuickTime Player)$" manage=off

# 3. Turn tiling off entirely and keep yabai only for opacity:
yabai -m config layout float

Option 3 is worth knowing about. If you installed yabai only to get per-app opacity, layout float gives you exactly that and nothing else: macOS window behaviour is completely untouched, and Transparency works the same.

Supported versions

Transparency v1.0.0, released 2026-08-04. Support means we test on it and fix what breaks.

Version policy

• A Pro or Studio licence covers every 1.x release.
• We support the current macOS release and the two before it. When a fourth ships, the oldest moves to best effort rather than being dropped without warning.
• yabai's scripting addition is the fragile dependency, not this app. It commonly breaks on macOS point updates and needs reloading — that is a yabai upgrade, not a Transparency one.

Troubleshooting

Uninstall

sh build.sh uninstall

That unregisters the login item, quits the app, and removes the bundle and the CLI symlink. Your yabairc is left alone — the managed block stays, so yabai keeps applying exactly what you set. Delete the block by hand if you want the opacity rules gone too.