A macOS command line tool that switches native Spaces and moves, resizes and focuses windows, with SIP left on.
| macOS 14+ | SIP | Status |
|---|---|---|
| Supported | Leave it enabled | Beta |
Config keys, CLI flags and behaviour are settled. If a release breaks an existing config or script, its CHANGELOG entry links to a pull request that says what breaks and how to migrate.
Install · What mimi does · Configuration · Compare · Docs
Screen.Recording.2026-06-09.at.1.59.38.PM.mov
Every window and space move in mimi is a shell command, so you can bind it to a hotkey or call it from a script.
mimi action space 2 # jump to space 2
mimi action move_window_to_space next --follow # move the window and follow it
mimi action resize_window left-half --cycle # half, two thirds, a third
mimi action focus_window --left # focus by direction- Native Spaces. mimi switches the Mission Control spaces you already have by sending the same dock swipe as the trackpad. It moves a window to another space with no animation.
- No SIP changes. mimi needs only the Accessibility permission and loads no scripting addition into the Dock.
- The daemon is optional. Every action runs directly from the CLI. Start the daemon for hooks, borders or tiling. While it runs, the CLI sends actions over its socket.
- Tiling is a program you write. mimi ships no built-in layout. The daemon runs your program when windows change, passes it the windows as JSON, and applies the frames it prints.
- Read and change the desktop.
mimi actionchanges it,mimi queryprints it as JSON, and hooks run your shell commands on app, window and space events. - Bad config fails early.
mimi config validaterejects unknown hook keys and invalid filters. A reload with errors keeps the previous config running.
brew tap y3owk1n/tap
brew install --cask y3owk1n/tap/mimiNix (nix-darwin, home-manager)
Add github:y3owk1n/mimi as a flake input, apply mimi.overlays.default, import mimi.darwinModules.default or mimi.homeManagerModules.default, then:
services.mimi.enable = true;
services.mimi.config = ''
[systray]
enabled = true
'';pkgs.mimi uses the release zip and pkgs.mimi-source builds from source. Both packages install shell completions, and both modules add a launchd agent. Full examples are in the Installation Guide.
oku
oku add -g github:y3owk1n/mimi --service--service starts the daemon at login. --from-source builds the release tag, and github:y3owk1n/mimi#mimi-main builds the newest commit of main. Details are in the Installation Guide.
Prebuilt binaries
Download from GitHub Releases:
| Architecture | File |
|---|---|
| Apple Silicon | mimi-darwin-arm64.zip |
| Intel | mimi-darwin-amd64.zip |
Each archive has a .sha256 checksum file. Releases after 0.20.3 also carry a
build provenance attestation, which shows the archive came from this
repository's release workflow:
gh attestation verify mimi-darwin-arm64.zip --repo y3owk1n/mimiFrom source
Needs Go, the Xcode Command Line Tools and just.
git clone https://github.com/y3owk1n/mimi.git && cd mimi
just bundle # builds build/Mimi.appGrant Accessibility in System Settings > Privacy & Security > Accessibility. That is all the CLI needs.
mimi action space next # works right away, no daemon
mimi config init # write ~/.config/mimi/config.toml
mimi services install # run the daemon at login, for hooks, borders and tiling
mimi status # daemon state and permissions
mimi doctor # every troubleshooting check, with the fix under a failure
mimi hooks fire on_app_activate --app Safari # run a hook by hand and see what matchedThe repo ships three skills for coding agents such as Claude Code, Codex, and Cursor. mimi-ask answers what mimi can do and which command does it, mimi-setup-config writes and applies the config file, and mimi-setup-layout gets tiling working. They read the help and docs of the installed version, so a Homebrew install needs no checkout.
npx skills add y3owk1n/mimi --skill mimi-ask --skill mimi-setup-config --skill mimi-setup-layoutActions and queries work without the daemon. Everything else needs it.
| Layer | Needs the daemon | What you get | Configured in |
|---|---|---|---|
| Actions | No | Switch spaces, move windows across spaces and displays, resize, focus | CLI flags |
| Queries | No | The active space, windows and displays as JSON | CLI flags |
| Hooks | Yes | Your shell command on 21 app, window, space and system events, with filters | [hooks] |
| Menu bar | Yes | The active space number, a reload item and the last reload outcome | [systray] |
| Borders | Yes | An outline around each window, coloured by focus | [border] |
| Tiling | Yes | Your layout program, run when windows change, with optional animation | [tiling] |
# Spaces
mimi action space <n|next|prev> [--same-display]
mimi action move_window_to_space <n|next|prev> [--follow] [--same-display] [--number <id>]
mimi action move_window_to_display <n|next|prev> [--number <id>]
# Focus
mimi action focus_window [--backward | --same-app | --left | --right | --up | --down | --number <id>]
mimi action focus_app Safari # switches to the app's space first
mimi action focus_display next # the window in front on the next display
# Size and place
mimi action resize_window <preset> [--cycle] [--number <id>] # halves, quadrants, thirds, two thirds, center, fill
mimi action resize_window center --width-percent 80 --height-percent 90
mimi action resize_window --width 1024 --height 768 --anchor br
mimi action resize_window --dx -50 --dw 100 # move and grow from where it is
my-layout | jq .frames | mimi action apply_frames # apply a layout's frames
# Close, minimize, full screen
mimi action close_window | minimize_window | fullscreen_window [--number <id>]
mimi action unminimize_window --number <id> # ids from: mimi query minimized
# Read the desktop
mimi query space | spaces | window | windows | minimized | displays | marginsresize_window honours the macOS tiled-window margins setting, so hand-placed and tiled windows line up. Every flag and preset is in the CLI Reference.
Config is one TOML file at ~/.config/mimi/config.toml. Saving it reloads a running daemon, and so does mimi config reload.
Bind to hotkeys. Every action is a plain shell command, so any hotkey tool works: skhd, Raycast Script Commands, Alfred, Karabiner, Hammerspoon, BetterTouchTool.
# ~/.skhdrc
alt - n : mimi action space next
alt - p : mimi action space prev
shift + alt - n : mimi action move_window_to_space next --follow
shift + alt - h : mimi action resize_window left-half --cycle
shift + alt - l : mimi action resize_window right-half --cycle
alt - h : mimi action focus_window --left
alt - l : mimi action focus_window --rightHooks. Filter a hook by app name or bundle ID glob, window title regex, space number, or display number. A leading ! negates a filter. mimi passes event details as environment variables, and a crafted window title cannot run as code.
[hooks]
on_workspace_changed = [
{ run = "sketchybar --trigger space_change INDEX=$mimi_SPACE_INDEX" },
{ run = "sketchybar --trigger work_mode", space = 2 },
]
on_app_launch = [
{ run = "echo launched $mimi_APP_NAME >> ~/apps.log", app = "!Finder", async = true },
]Borders. The daemon draws an outline around each window, like JankyBorders, in one colour for the focused window and another for the rest.
[border]
enabled = true
width = 4
active_color = "#e2e2e3" # #rrggbb or #aarrggbb, alpha first
inactive_color = "#414141"Tiling. Copy the example layouts and set layout to one of them. The mimi-setup-layout skill fetches them for an install without a checkout.
cp -r examples/tiling ~/.config/mimi/tiling[tiling]
enabled = true
layout = "~/.config/mimi/tiling/bsp.py"
relayout_on_drag = true # drag an edge to resize a split, drop on a window to swap
[tiling.animation]
enabled = trueSix layouts ship as starting points, all Python with the standard library only: monocle, columns, master-stack, a Hyprland-style dwindle bsp, a yabai-style stacked, and a niri-style scrollable strip. Each layout defines its own commands, and you bind them like any other action.
mimi-strip-small.mov
mimi-bsp-small.mov
mimi tiling preview | jq # print the frames without applying them
mimi tiling cmd swap left # your layout decides what swap means
mimi tiling cmd togglemax # temporary maximise, in every shipped layout but monocleConfiguration Reference · CLI Reference · Tiling Guide
| Tool | Approach | Spaces | Needs SIP changes | Open source |
|---|---|---|---|---|
| mimi | Commands, hooks, borders, and a layout you write | Native | No | Yes |
| yabai | BSP, stack and float tiling with a query CLI | Native | For space control | Yes |
| AeroSpace | i3-style tree tiling | Its own workspaces | No | Yes |
| Amethyst | xmonad-style automatic layouts | Native | No | Yes |
| Rectangle | Snap to presets with shortcuts | Not managed | No | Yes |
| Hammerspoon | General macOS automation in Lua | Native, hs.spaces |
No | Yes |
mimi fits if you want to keep native Spaces and control them from the keyboard, or you want to write your tiling layout as a program.
mimi action ... -> daemon socket if running, else in-process -> Accessibility + SkyLight
daemon -> app, window and space observers -> event bus -> your hooks
-> borders
-> your layout program -> frames -> Accessibility
-> menu bar
Space switching sends a synthetic dock swipe through CGEvent. Window-to-space moves, focus_app, focus_display, move_window_to_display, focus_window --number across spaces, and borders use private SkyLight calls. Resizing, moving and focusing within a space use public Accessibility. The private paths are timing-sensitive and can break on a macOS update. Architecture
| Using mimi | |
|---|---|
| Installation | Homebrew, Nix, oku, source, permissions, completions |
| CLI Reference | Every command, flag and preset |
| Configuration Reference | Settings, hooks, environment variables, borders |
| Tiling Guide | From first run to writing a layout from scratch |
| Layout Contract | Every field a layout reads and prints |
| Troubleshooting | Common issues and fixes |
| Working on mimi | |
|---|---|
| Contributing | How to propose and land a change |
| Development Guide | Toolchain, building, testing |
| Architecture | Execution paths and native bridges |
mimi is written in Go, with Objective-C in internal/native, internal/systray and internal/permissions. oku sync && oku allow provisions the toolchain.
just fmt && just lint && just test && just build # the pre-commit gateReport bugs through the issue form. Contributing Guide
One person builds mimi in their spare time. If you use it, you can sponsor it.
neru adds keyboard hints, grids and vim-style scrolling for clicking and scrolling inside apps. mimi's window and space code started in neru.
MIT. See LICENSE.
Install and switch to the next space:
brew install --cask y3owk1n/tap/mimi && mimi action space nextMade with ❤️ by y3owk1n