Answering questions about mimi
mimi is a macOS window and space tool. It has a CLI for immediate actions,
a daemon that runs shell hooks on app, window, and space events, and a
tiling engine that runs a layout program the user chooses. Every answer
about it should come from the installed version, since commands and keys
change between releases.
What every install has
Check these before anything remote. Homebrew, Nix, and a source build all
ship them.
mimi --help, then mimi <command> --help. The help text lists the
flags and accepted values of the installed version.man mimi, and one page per subcommand such as man mimi-action-resize_window
and man mimi-tiling-cmd. apropos mimi lists them.mimi status for whether the daemon runs and Accessibility is granted.mimi config dump for the config in force, defaults filled in.mimi query space, window, windows, displays, and margins for
the current spaces, windows, and displays as JSON.
For anything the help does not cover, fetch the doc at the installed
version:
tag=$(mimi --version | sed -n '1s/^Mimi version //p')
case $tag in v*) ;; *) tag=main ;; esac
curl -fsSL "https://raw.githubusercontent.com/y3owk1n/mimi/$tag/docs/CLI.md"
The docs are CLI.md for every command and flag, CONFIGURATION.md for
every key and hook, TILING.md for layouts, TROUBLESHOOTING.md when
something does not work, and INSTALLATION.md for install methods and the
launchd service.
What mimi does
| Ask |
Answer with |
| Switch space, move a window to a space or display |
mimi action space, move_window_to_space, move_window_to_display |
| Focus a window by direction, app, or cycle |
mimi action focus_window, focus_app |
| Resize or place a window by preset or size |
mimi action resize_window |
| Apply frames from any program |
mimi action apply_frames |
| Read the desktop as JSON |
mimi query ... |
| Run a command when an app, window, or space changes |
[hooks] in config, see mimi-setup-config |
| Draw a border around the focused window |
[border] in config, see mimi-setup-config |
| Tile windows |
[tiling] plus a layout program, see mimi-setup-layout |
| Show the active space number in the menu bar |
[systray] in config, see mimi-setup-config |
| Run mimi at login |
mimi services install, see mimi-setup-config |
Three things a user often does not know:
- The daemon is optional. Every
mimi action works from the CLI
alone. The daemon adds hooks, borders, tiling, and the menu bar item
with the active space number. While it runs, the CLI sends actions over
its socket, which is faster than starting each one from scratch.
- mimi ships no layout. Tiling means naming a program in config. The
repo has six to copy, and
mimi-setup-layout fetches them without a checkout.
- Accessibility is the only permission mimi asks for. Actions,
window hooks, borders, and tiling all need it.
mimi status says
whether it is granted.
Routing
- Config, hooks, borders, systray, or service work goes to
mimi-setup-config.
- Tiling, layouts, and hotkeys for layout commands go to
mimi-setup-layout.
- A question with a one-command answer gets the command and the help page
that documents it.
- When something does not work, run
mimi status, then fetch the
Troubleshooting doc as above, before guessing at a cause.
- A bug or a missing feature goes to a GitHub issue on
y3owk1n/mimi.
Blank issues are disabled, so use the issue forms.
Do not answer flags or key names from memory. Run --help or read the man
page first.
1---2name: mimi-ask3description: Answer a mimi user's question about what mimi does, which command or config key does a thing, or what to do next, from the man pages and help on their install rather than from memory. Routes setup work to mimi-setup-config and mimi-setup-layout. Use when a mimi user asks what mimi can do, how to do something with it, which command to run, or which skill to use.4---56# Answering questions about mimi78mimi is a macOS window and space tool. It has a CLI for immediate actions,9a daemon that runs shell hooks on app, window, and space events, and a10tiling engine that runs a layout program the user chooses. Every answer11about it should come from the installed version, since commands and keys12change between releases.1314## What every install has1516Check these before anything remote. Homebrew, Nix, and a source build all17ship them.1819- `mimi --help`, then `mimi <command> --help`. The help text lists the20 flags and accepted values of the installed version.21- `man mimi`, and one page per subcommand such as `man mimi-action-resize_window`22 and `man mimi-tiling-cmd`. `apropos mimi` lists them.23- `mimi status` for whether the daemon runs and Accessibility is granted.24- `mimi config dump` for the config in force, defaults filled in.25- `mimi query space`, `window`, `windows`, `displays`, and `margins` for26 the current spaces, windows, and displays as JSON.2728For anything the help does not cover, fetch the doc at the installed29version:3031```bash32tag=$(mimi --version | sed -n '1s/^Mimi version //p')33case $tag in v*) ;; *) tag=main ;; esac34curl -fsSL "https://raw.githubusercontent.com/y3owk1n/mimi/$tag/docs/CLI.md"35```3637The docs are `CLI.md` for every command and flag, `CONFIGURATION.md` for38every key and hook, `TILING.md` for layouts, `TROUBLESHOOTING.md` when39something does not work, and `INSTALLATION.md` for install methods and the40launchd service.4142## What mimi does4344| Ask | Answer with |45| --- | --- |46| Switch space, move a window to a space or display | `mimi action space`, `move_window_to_space`, `move_window_to_display` |47| Focus a window by direction, app, or cycle | `mimi action focus_window`, `focus_app` |48| Resize or place a window by preset or size | `mimi action resize_window` |49| Apply frames from any program | `mimi action apply_frames` |50| Read the desktop as JSON | `mimi query ...` |51| Run a command when an app, window, or space changes | `[hooks]` in config, see `mimi-setup-config` |52| Draw a border around the focused window | `[border]` in config, see `mimi-setup-config` |53| Tile windows | `[tiling]` plus a layout program, see `mimi-setup-layout` |54| Show the active space number in the menu bar | `[systray]` in config, see `mimi-setup-config` |55| Run mimi at login | `mimi services install`, see `mimi-setup-config` |5657Three things a user often does not know:5859- **The daemon is optional.** Every `mimi action` works from the CLI60 alone. The daemon adds hooks, borders, tiling, and the menu bar item61 with the active space number. While it runs, the CLI sends actions over62 its socket, which is faster than starting each one from scratch.63- **mimi ships no layout.** Tiling means naming a program in config. The64 repo has six to copy, and `mimi-setup-layout` fetches them without a checkout.65- **Accessibility is the only permission mimi asks for.** Actions,66 window hooks, borders, and tiling all need it. `mimi status` says67 whether it is granted.6869## Routing7071- Config, hooks, borders, systray, or service work goes to `mimi-setup-config`.72- Tiling, layouts, and hotkeys for layout commands go to `mimi-setup-layout`.73- A question with a one-command answer gets the command and the help page74 that documents it.75- When something does not work, run `mimi status`, then fetch the76 Troubleshooting doc as above, before guessing at a cause.77- A bug or a missing feature goes to a GitHub issue on `y3owk1n/mimi`.78 Blank issues are disabled, so use the issue forms.7980Do not answer flags or key names from memory. Run `--help` or read the man81page first.
y3owk1n