A scrolling window manager for macOS.
Get started · Configuration · Contributing
demo.mp4
Defi lays out your windows as columns on a strip that scrolls sideways. Each new window adds a column, and focusing one off screen scrolls it into view. Clicks, the Dock, and Command-Tab work as usual.
Inspired by Niri, built for native macOS windows. Defi is in alpha, so behavior and configuration may still change.
- Scrolling columns: automatic tiling, vertical stacks, adjustable widths.
- Workspaces: each display keeps its own, with an empty one always ready. The Overview shows them all.
- Smooth motion: windows glide on an overlay, then move once underneath.
- App rules: send apps to a workspace, float them, or set their width.
- Keyboard and mouse: custom shortcuts with a cheatsheet, and drag to reorder.
- Scriptable: live TOML config, a CLI, and a SketchyBar integration.
Window borders, gaps, and every other option are in the configuration reference.
brew install --cask qeude/tap/defi
open /Applications/Defi.appNote
Defi is self-signed and not notarized, so only install it if you trust this source. Homebrew and the install script skip the quarantine check; the script verifies the release signature instead.
Other ways to install
Install script
curl -fsSL https://raw.githubusercontent.com/qeude/Defi/main/script/install.sh | shDMG: download it from the latest release and drag Defi to Applications. On first launch, close the warning, click Open Anyway in System Settings › Privacy & Security, and confirm. Later updates skip this step.
From source: see Build and run.
Defi asks for Accessibility on first launch and picks it up without a restart, then asks for Screen Recording.
| Permission | Used to | Without it |
|---|---|---|
| Accessibility (required) | Focus and arrange windows | Defi cannot manage windows |
| Screen Recording | Animate window pictures and show Overview and recent windows previews | Windows move at once; Overview and recent windows cards have no pictures |
Window pictures stay in memory and never leave your Mac. To start Defi with macOS, turn on Launch Defi at login in Settings › General.
Once a day, Defi checks GitHub for a new release. It is Defi's only network request and sends nothing about you. New releases install from a small panel, only if signed by the same release certificate, and keep your workspaces.
Turn the check off in Settings › General, or run it by hand from Settings ›
About or the menu bar. Builds not signed with the release certificate never
check. Homebrew users can keep using brew upgrade --cask defi.
Shortcuts use ⌃⌥ (Control + Option), leaving Option free for typing. Hold them to show the cheatsheet.
| Action | Shortcut |
|---|---|
| Focus a column | ⌃⌥← → or H L |
| Focus a window in a stack | ⌃⌥↑ ↓ or K J |
| Switch workspace | ⌃⌥I U or 1…9 |
| Move a column or window | ⌃⌥⌘ + arrow |
| Move a column to another workspace | ⌃⌥⌘I U |
| Join a window to the next stack, or take it out | ⌃⌥[ ] |
| Cycle column width | ⌃⌥R, or − = |
| Toggle full width | ⌃⌥F |
| Open Overview | ⌃⌥O |
| Focus another display | ⌃⌥⇧ + arrow |
Control + Option focuses, adding Command moves what is focused, and adding Shift reaches other displays or reorders workspaces.
Tip
Prefer one key? Remap Caps Lock to a Hyper key (⌃⌥⌘), then set
mod to "ctrl+alt+cmd" in your config or in
Settings › Input › Mod key.
Hyper already holds Command, so moving takes mod-shift instead of mod-cmd,
and the monitor shortcuts need bindings of your own in [keys].
Defi works without a config file. Add overrides to ~/.config/defi/config.toml;
changes reload on save and updates never touch it. Start from the
configuration reference, or borrow from the
maintainer's setup.
Command line
The defi CLI ships inside the app:
/Applications/Defi.app/Contents/MacOS/defi status
/Applications/Defi.app/Contents/MacOS/defi focus-column right
/Applications/Defi.app/Contents/MacOS/defi workspace dev # needs a workspace named devSource builds, and installs where /Applications is not writable, use
~/Applications instead. See the
command reference.
Uninstall
With Homebrew, brew uninstall --cask --zap defi also removes your config and
saved state. Otherwise, run the CLI of the app to remove:
/Applications/Defi.app/Contents/MacOS/defi uninstall --purgeThis removes that app, plus Defi's config, saved state, logs, login item, and privacy permissions. Other Defi app bundles stay but lose that shared data.
Shortcuts do nothing
- Check that the installed Defi app has Accessibility permission.
- With a Hyper
mod, make sure your keyboard remap sends the same keys. - Quit other window managers to rule out conflicting shortcuts.
An app does not tile well
Some apps limit their window size or support Accessibility poorly. Defi also manages its own virtual workspaces, not native macOS Spaces. Open an issue with the app name and what you expected.
How do I quit Defi without the menu bar?
Run /Applications/Defi.app/Contents/MacOS/defi quit, or quit defi-daemon in
Activity Monitor.
How do I report a bug?
Run defi triage, or choose Start Triage in Settings › General ›
Diagnostics. It collects your machine facts, then starts your own claude or
codex to investigate and draft the issue with you. It asks before it fixes or
posts anything. Without an agent, it prints a prompt you can paste into any
coding agent.
To report by hand, include your Defi and macOS versions, the affected apps, your
monitor setup, and steps to reproduce. defi status and defi trace help.
Their output can show window titles, paths, and workspace names, so share only
the relevant parts, redacted.
Bug reports and focused pull requests are welcome. See Contributing or open an issue.