A scrolling window manager for macOS.
macOS 26+ · Alpha
Get started · Configuration · Contributing
demo.mp4
Defi arranges your windows in columns on a horizontal strip. Open another window and the strip grows. Move to a window beyond the edge of your screen and the desktop scrolls to bring it into view.
Inspired by Niri, built for native macOS windows. Click a window, select it in the Dock, or use Command-Tab as usual.
- Automatic tiling: Open a window and Defi places it in the layout. Close one and the remaining windows reflow automatically.
- Scrolling columns: Arrange windows on a horizontal strip, stack them vertically, and adjust column widths.
- Dynamic workspaces: Always have an empty workspace ready, and keep named workspaces for recurring tasks.
- Independent monitors: Each display has its own workspaces and layout.
- Overview: Browse workspaces, select windows, and drag them between workspaces, with optional window previews.
- Window borders: Highlight the focused window, with configurable colors, width, and optional inactive borders.
- Keyboard controls & cheatsheet: Customize shortcuts and hold your modifier key to see available commands.
- Mouse reordering: Rearrange tiled windows by dragging them.
- Floating windows & app rules: Keep selected apps floating and route them to named workspaces.
- Native macOS interaction: Keep using window clicks, the Dock, and Command-Tab.
- Live configuration: Customize gaps, animations, shortcuts, and rules in TOML; changes reload automatically.
- CLI & SketchyBar integration: Control Defi from scripts and expose workspace state in your bar.
Configuration and commands · SketchyBar integration
Defi supports Apple Silicon Macs running macOS 26 or newer. Install with Homebrew:
brew install --cask qeude/tap/defi
open /Applications/Defi.appThe app is signed with a self-signed certificate and is not notarized. The Cask removes its quarantine attribute to allow it to open; only install if you trust this source.
For manual installation, download the ZIP and follow the instructions in the release notes. You can also build from source.
The alpha is experimental. Behavior and configuration may change before the first stable release.
On first launch, Defi requests Accessibility access. Grant it in System Settings; Defi starts managing windows automatically, without a restart. Defi needs this permission to focus and arrange windows. Screen Recording is only needed if you enable window previews in Overview.
Enable Launch at Login in the menu bar if you want Defi to start with macOS.
Built-in shortcuts use Option. Hold Option on its own to show the shortcut guide, or start with these:
| Action | Shortcut |
|---|---|
| Focus a column | Option + ← / → |
| Switch workspace | Option + ↑ / ↓ |
| Focus a window in a stack | Option + J / K |
| Move a column left or right | Option + Shift + ← / → |
| Move a column to another workspace | Option + Shift + ↑ / ↓ |
| Cycle column width | Option + − / = |
| Toggle full column width | Option + F |
| Open Overview | Option + O |
I recommend mapping a key such as Caps Lock to a Hyper key to avoid
conflicts with macOS and application shortcuts. Set
default_key_modifier to match
your combination.
Defi works without a config file. Add overrides to
~/.config/defi/config.toml for gaps, shortcuts, named workspaces, and app rules.
Existing config files are preserved when you rebuild or update Defi. Defi creates the config directory if needed, but no config file. Changes reload automatically when you save, including your first config. The example configuration is the maintainer's setup; copy only the parts you want.
Command-line control
The CLI is bundled with the app. For a source installation:
~/Applications/Defi.app/Contents/MacOS/defi status
~/Applications/Defi.app/Contents/MacOS/defi focus-column right
~/Applications/Defi.app/Contents/MacOS/defi workspace devThe last command requires a named workspace called dev.
Use /Applications/Defi.app instead if that is where you installed Defi.
See the command reference for the full list.
Uninstall completely
For a Homebrew installation, use brew uninstall --cask --zap defi.
This also removes your configuration and saved state.
For a manual or source installation, run the CLI from your installed app:
~/Applications/Defi.app/Contents/MacOS/defi uninstall --purgeUse /Applications/Defi.app instead for an app installed there.
This removes the app containing the invoked CLI, plus Defi's shared
configuration, saved workspace state, logs, login item, and privacy permissions.
Other Defi app bundles are preserved, but they share the removed user data.
If shortcuts do not respond, check Accessibility permission for the installed
Defi app; newly granted access is detected automatically. Check
default_key_modifier in your config:
custom Hyper bindings require a matching keyboard remap. Temporarily quit
other window managers to rule out conflicting shortcuts or window moves.
To stop Defi, choose Quit Defi in the menu bar. If the menu is unavailable,
run ~/Applications/Defi.app/Contents/MacOS/defi quit, or quit defi-daemon
through Activity Monitor. Adjust the app path for an installation in
/Applications.
For a bug report, include your Defi and macOS versions, affected apps, monitor
setup, and steps to reproduce. The bundled CLI's status and trace commands
can help explain what happened. Review their output, config snippets, and
recordings before posting: they may expose window titles, paths, workspace
names, or other private information. Share only the relevant, redacted parts.
Defi manages its own virtual workspaces, not native macOS Spaces. Apps can impose window size constraints or expose limited Accessibility support, so please report app-specific behavior. Screen Recording is optional; Overview window previews are off by default. There is no automatic update checker yet.
Bug reports and focused pull requests are welcome. See Contributing for setup and checks, or open an issue to report a problem or propose an improvement.