{"id":51080750,"url":"https://github.com/y3owk1n/mimi","last_synced_at":"2026-06-23T17:33:11.910Z","repository":{"id":361630453,"uuid":"1254994779","full_name":"y3owk1n/mimi","owner":"y3owk1n","description":"macOS windows and spaces. From the terminal.","archived":false,"fork":false,"pushed_at":"2026-06-15T01:45:01.000Z","size":452,"stargazers_count":13,"open_issues_count":0,"forks_count":1,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-15T03:20:20.408Z","etag":null,"topics":["cli","macos","macos-spaces","workspace"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/y3owk1n.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null},"funding":{"github":"y3owk1n"}},"created_at":"2026-05-31T09:05:03.000Z","updated_at":"2026-06-15T01:45:05.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/y3owk1n/mimi","commit_stats":null,"previous_names":["y3owk1n/mimi"],"tags_count":11,"template":false,"template_full_name":null,"purl":"pkg:github/y3owk1n/mimi","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/y3owk1n%2Fmimi","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/y3owk1n%2Fmimi/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/y3owk1n%2Fmimi/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/y3owk1n%2Fmimi/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/y3owk1n","download_url":"https://codeload.github.com/y3owk1n/mimi/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/y3owk1n%2Fmimi/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34700908,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-23T02:00:07.161Z","response_time":65,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["cli","macos","macos-spaces","workspace"],"created_at":"2026-06-23T17:33:10.208Z","updated_at":"2026-06-23T17:33:11.905Z","avatar_url":"https://github.com/y3owk1n.png","language":"Go","funding_links":["https://github.com/sponsors/y3owk1n"],"categories":[],"sub_categories":[],"readme":"\u003cdiv align=\"center\"\u003e\n\n# mimi\n\n**macOS windows and spaces. From the terminal.**\n\n[![Go Version](https://img.shields.io/github/go-mod/go-version/y3owk1n/mimi?style=flat-square\u0026logo=go)](https://github.com/y3owk1n/mimi)\n[![License](https://img.shields.io/github/license/y3owk1n/mimi?style=flat-square)](LICENSE)\n[![Early Development](https://img.shields.io/badge/status-early%20dev-orange?style=flat-square)](#)\n\n\u003c/div\u003e\n\n---\n\nhttps://github.com/user-attachments/assets/1b21b596-1578-4344-96d3-eaea8a5ab9c0\n\n---\n\nYou already know your way around a terminal. Why are you still reaching for the trackpad just to move a window?\n\n**mimi** gives you one-shot commands to jump spaces, move windows, cycle focus, and resize — bind them to hotkeys, drop them in dotfiles, wire them to shell hooks. No SIP disable. No tiling paradigm to learn. Just commands that do what they say.\n\n```bash\nmimi action space 2                      # jump to space 2\nmimi action move_window_to_space next    # throw window forward\nmimi action resize_window left-half      # tile left\nmimi action focus_window                 # cycle focus\n```\n\n\u003e **Early development** — config format, CLI, and behavior may change between releases.\n\n---\n\n## Install\n\n```bash\nbrew tap y3owk1n/tap\nbrew install --cask y3owk1n/tap/mimi\n```\n\nGrant **Accessibility** in **System Settings → Privacy \u0026 Security → Accessibility**, then start using it immediately. No daemon required.\n\nOther options (Nix flake, build from source) → [Installation Guide](docs/INSTALLATION.md)\n\n---\n\n## What mimi does\n\n| You want to…                     | Command                                                                   |\n| :------------------------------- | :------------------------------------------------------------------------ |\n| Jump to a specific space         | `mimi action space \u003cn\u003e`                                                   |\n| Jump to next / previous space    | `mimi action space next` / `prev`                                         |\n| Move frontmost window to a space | `mimi action move_window_to_space \u003cn\\|next\\|prev\u003e`                        |\n| Cycle focus between windows      | `mimi action focus_window`                                                |\n| Cycle focus backward             | `mimi action focus_window --backward`                                     |\n| Focus window to the left         | `mimi action focus_window --left`                                         |\n| Focus window to the right        | `mimi action focus_window --right`                                        |\n| Focus window above               | `mimi action focus_window --up`                                           |\n| Focus window below               | `mimi action focus_window --down`                                         |\n| Tile window to a preset          | `mimi action resize_window \u003cleft-half\\|right-half\\|center\\|fill\u003e`         |\n| Center at specific size          | `mimi action resize_window center --width-percent 80 --height-percent 90` |\n| Resize to exact pixels           | `mimi action resize_window --width 1024 --height 768`                     |\n| Resize anchored to a corner      | `mimi action resize_window --width 1024 --height 768 --anchor br`         |\n\nFull reference → [CLI Guide](docs/CLI.md)\n\n---\n\n## Bind to hotkeys\n\nEvery action is a plain shell command. Drop it into whatever hotkey tool you already use.\n\n**[skhd](https://github.com/koekeishiya/skhd)** — the natural pairing if you're in the yabai ecosystem:\n\n```bash\n# ~/.skhdrc\nalt - 2         : mimi action space 2\nalt - n         : mimi action space next\nalt - p         : mimi action space prev\nshift + alt - l : mimi action resize_window right-half\nshift + alt - h : mimi action resize_window left-half\nshift + alt - m : mimi action move_window_to_space next\nshift + alt - f : mimi action focus_window\n```\n\n**[Raycast](https://www.raycast.com/)** — create a Script Command pointing to any `mimi action …` line.\n\n**[Alfred](https://www.alfredapp.com/)** — wire up a Shell Script workflow step, same idea.\n\n**Karabiner, Hammerspoon, BetterTouchTool** — if it can run a shell command on a keypress, mimi works with it.\n\n---\n\n## Fits where you are\n\nmimi doesn't tile your layout, enforce window rules, or replace Mission Control. It's not trying to.\n\n[yabai](https://github.com/koekeishiya/yabai) and [AeroSpace](https://github.com/nikitabobko/AeroSpace) are excellent — and a significant commitment. If you've tried them and found it was more than you needed, or if you just want to stay on native macOS Spaces and drive them faster, mimi is for you.\n\n---\n\n## Optional: daemon + hooks\n\nStart the daemon and mimi can react to what's happening on screen — fire a shell command whenever a window focuses, a space changes, or an app launches.\n\n```bash\nmimi config init   # creates ~/.config/mimi/config.toml\nmimi start\nmimi status        # verify everything's running\n```\n\nEdit `~/.config/mimi/config.toml`:\n\n```toml\n[systray]\nenabled = true\nshow_workspace_number = true   # current space number in your menu bar\n\n[hooks]\non_window_focus      = ['echo \"$mimi_APP_NAME — $mimi_WINDOW_TITLE\"']\non_workspace_changed = ['~/.config/sketchybar/plugins/space.sh']\non_app_launch        = ['osascript -e \"display notification \\\"$mimi_APP_NAME launched\\\"\"']\n```\n\nThe `[systray]` block shows the active space number in your menu bar while the daemon runs — no extra setup.\n\n### Available hooks\n\n| Event                  | Hook key                                 | Needs Accessibility |\n| :--------------------- | :--------------------------------------- | :------------------ |\n| App activated          | `on_app_activate`                        | Yes                 |\n| App deactivated        | `on_app_deactivate`                      | Yes                 |\n| App launched           | `on_app_launch`                          | No                  |\n| App quit               | `on_app_quit`                            | No                  |\n| App hidden / unhidden  | `on_app_hide` / `on_app_unhide`          | Yes                 |\n| Window focused         | `on_window_focus`                        | Yes                 |\n| Window title changed   | `on_window_title_change`                 | Yes                 |\n| Window opened / closed | `on_window_created` / `on_window_closed` | Yes                 |\n| Window resized         | `on_window_resize`                       | Yes                 |\n| Active space changed   | `on_workspace_changed`                   | No                  |\n\nHooks support app/title filters, async execution, and per-hook timeouts.\nFull details → [Configuration Guide](docs/CONFIGURATION.md)\n\n### Daemon commands\n\n```bash\nmimi start                  # start the hook daemon\nmimi stop                   # stop it\nmimi status                 # check daemon state and permissions\nmimi config validate        # validate config before reloading\nmimi config reload          # hot-reload config (no restart needed)\nmimi services install       # auto-start at login via launchd\nmimi services uninstall     # remove the launchd agent\n```\n\nAuto-start setup → [Installation Guide — launchd](docs/INSTALLATION.md#auto-start-launchd)\n\n---\n\n## How it works\n\nSpace switching uses a synthetic dock-swipe gesture — the same path Mission Control uses, no hacks. Window-to-space moves use the private SkyLight API for instant, animation-free relocation. Everything else goes through public Accessibility APIs.\n\n```\nCLI actions  →  action handler  →  AX API + SkyLight\n\ndaemon  →  observe events  →  event bus  →  your shell hooks\n                                    ↓\n                             menu bar (optional)\n```\n\n→ [Architecture Guide](docs/ARCHITECTURE.md)\n\n---\n\n## Documentation\n\n| Guide                                      | What's in it                                |\n| :----------------------------------------- | :------------------------------------------ |\n| [Installation](docs/INSTALLATION.md)       | Homebrew, Nix, source, permissions, launchd |\n| [CLI](docs/CLI.md)                         | Every command and flag                      |\n| [Configuration](docs/CONFIGURATION.md)     | Hooks, env vars, systray, all settings      |\n| [Architecture](docs/ARCHITECTURE.md)       | How the pieces fit                          |\n| [Troubleshooting](docs/TROUBLESHOOTING.md) | Common issues and fixes                     |\n| [Contributing](CONTRIBUTING.md)            | PRs and bug reports                         |\n\n---\n\n## Contributing\n\n```bash\njust build \u0026\u0026 just lint \u0026\u0026 just test\n```\n\n→ [Development Guide](docs/DEVELOPMENT.md)\n\n---\n\n## From the same workshop\n\nmimi's window management and space-switching code was part of **[neru](https://github.com/y3owk1n/neru)** — a broader tool for navigating your entire screen without touching the mouse.\n\nWhere mimi is focused on moving and resizing windows, neru covers the rest: labels on every clickable element, recursive grid navigation, vim-style scrolling — the kind of thing Vimium does in a browser, but system-wide.\n\nIf you find yourself still reaching for the mouse _inside_ apps, neru is the natural next step.\n\n```bash\nbrew install --cask y3owk1n/tap/neru\n```\n\n---\n\n## License\n\nMIT — see [LICENSE](LICENSE).\n\n\u003cdiv align=\"center\"\u003e\n\u003cbr/\u003e\n\n**Try it. Two commands and you're running.**\n\n```bash\nbrew install --cask y3owk1n/tap/mimi \u0026\u0026 mimi action space next\n```\n\n\u003cbr/\u003e\nMade with ❤️ by \u003ca href=\"https://github.com/y3owk1n\"\u003ey3owk1n\u003c/a\u003e\n\u003c/div\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fy3owk1n%2Fmimi","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fy3owk1n%2Fmimi","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fy3owk1n%2Fmimi/lists"}