Troubleshooting and known limits

macOS says JimiOS “Not Opened” or can’t be checked

That’s expected: the beta isn’t notarised by Apple. Click Done, then go to System Settings → Privacy & Security and click Open Anyway next to JimiOS Alpha. You need to do this once for every new build. The button shows for about an hour after you try to open the app; if it’s gone, open the app again first.

Accessibility is on but nothing tiles

This usually happens after an update, because macOS ties the permission to the exact build.

1. Quit JimiOS if it’s running.
2. Open System Settings → Privacy & Security → Accessibility.
3. Select JimiOS Alpha and click the minus (−) button to remove it.
4. Open JimiOS again and turn it on when macOS asks.

On the first open of a new build, JimiOS may offer Reset and Ask Again, which does steps 2 and 3 for you.

JimiOS quits straight away

• AeroSpace or yabai is running. Quit it, then open JimiOS. If you use Rectangle, turn off its drag-to-snap. Quit Amethyst too.
• You didn’t allow Accessibility within five minutes. Open JimiOS again and allow it.
• It’s running from the disk image. Drag it to Applications and open it from there.

An app won’t fit, or keeps going to the overflow row

Some apps have a large minimum window size, so their windows can’t shrink to share a screen. JimiOS sends them to the overflow row or the next workspace rather than overlapping anything. Give the app its own workspace, float it with ⌥⇧Space, or add it to float_apps. See Keep a big app from pushing others away.

If an app clearly can go smaller than JimiOS lets it, report it: JimiOS may have learned the wrong minimum size.

A window is missing

See Get a lost window back. After a crash, see Recover after a crash or force quit.

Option-F, Option-R or Option-Shift-arrow don’t work in my app

JimiOS uses them while it’s running. Choose Pause tiling from the menu while you need them, or switch to h/j/k/l keys to free the arrow chords.

Things look wrong after changing macOS settings

Leave Stage Manager, macOS’s own edge tiling (“Drag windows to screen edges to tile”) and “Automatically rearrange Spaces” at your macOS defaults, and tell us how they’re set when you report a bug. JimiOS hasn’t been tested with every combination yet.

Known limits

• Apple silicon and macOS 13 or later only. Intel Macs aren’t supported.
• Two displays are still being tested. Unplug, replug, sleep and wake were rebuilt in 0.1.0 and are tested in code, but haven’t had a full two-display hardware run. If you use two displays, you’re among the first.
• Side-by-side displays only. Displays stacked one above the other, or arranged any other way, are untested. Up and down never cross between displays.
• “Displays have separate Spaces” must be off with more than one display.
• One macOS desktop. JimiOS manages only the desktop (Space) showing when it starts.
• Hidden windows sit off screen. Quitting normally (menu, panic key or uninstall) puts them back. Never force-quit JimiOS.
• The layout is kept until the Mac restarts.
• Settings apply at start. Quit and reopen JimiOS after editing config.json.
• macOS asks again after every update. Open Anyway, and usually Accessibility, need repeating for each build.

The log

JimiOS writes a log to /tmp/jimios-alpha/alpha.log. It lists app names, window numbers and sizes, and may include window titles, so look through it before you send it. It’s cleared when the Mac restarts, so send it before restarting.

To copy it to your Desktop, run this in Terminal:

cp /tmp/jimios-alpha/alpha.log ~/Desktop/jimios-log.txt

Or in Finder choose Go → Go to Folder, type /tmp/jimios-alpha and press Return.

---