Features

Layouts

What it does. A layout decides where a new window goes. Each workspace keeps its own layout.

Dwindle right (default). A new window splits the focused tile in half: side by side when the tile is wider than tall, stacked when it’s taller. It takes the half your pointer is in, at 50/50. When a window closes, the tile that takes its space re-works its splits to suit its new shape.
Dwindle left. The mirror of dwindle: the new window takes the left or top half.
Master. One main window on the left at 55 % of the width. The others stack on the right at equal heights, and a new window joins the bottom of the stack. Master replaced the old Balanced layout in this build.

How to use it. Press ⌥R to move this workspace to the next layout. A message names the layout it picked. If a layout would push a window off the workspace and another layout fits every window, ⌥R skips it and the message says what it skipped. To start every workspace in a different layout, set layout in the settings file.

Two more layouts, spiral and focused, exist in the settings file only. ⌥R goes from either to dwindle right.

Workspaces

What it does. You get nine workspaces. Each display shows one workspace at a time, and a workspace shows on one display at most. JimiOS hides the other workspaces by moving their windows just off the edge of the screen.

How to use it.

⌥1 to ⌥9 show a workspace. “Workspace N” flashes up each time a display shows a different workspace.
⌥⇧1 to ⌥⇧9 send the focused window to a workspace.
At the left or right edge, ⌃⌥← and ⌃⌥→ step to the previous or next workspace. There’s no wrap from 9 to 1; a message tells you when you reach the end.
⌘Tab or a Dock click on a window in another workspace takes you to that workspace. Set on_focus_parked to "bring_here" to bring the window to you instead.
The menu bar shows the workspace and tile count, for example J1 · 3. With two displays it shows both, for example J1 · [J2]; the brackets mark the display with the focus.

Focus and moving windows

What it does. Focus keys pick the window to the left, right, above or below. Move keys swap the focused window with its neighbour in that direction.

How to use it.

⌃⌥ arrows move the focus; ⌃⌥⇧ arrows (or ⌥⇧ arrows) move the window.
At the left or right edge of a display’s tiles, focus and moves cross to the display beside it. At the outer edge they go to the previous or next workspace.
Up and down never cross between displays.
On a key press, a thin outline shows where the window is going until it gets there. Turn it off with outline_cue.

Floating and tiling back

What it does. A floating window sits above the tiles and keeps the size and place you give it. These float automatically:

dialogs, panels and other non-standard windows;
windows of 1Password, System Settings, Calculator, Archive Utility, Installer, Tailscale and iPhone Mirroring;
a window with a fixed size, or one that can’t grow as big as its tile. It floats in the middle of the screen.

How to use it.

Press ⌥⇧Space to float the focused window. Press it again to tile it.
Hold ⌥ while you drag a window by its title bar to float it where you drop it.
To always float or always tile an app, add its bundle ID to float_apps or tile_apps in the settings file.

Floating windows belong to the workspace of the display they’re on.

Full-screen fill

What it does. ⌥F makes the focused window, tiled or floating, fill the whole tiling area on top of the others. It stays inside the current macOS desktop; it isn’t macOS’s own full screen.

How to use it. Press ⌥F. Press ⌥F again to put the window back in its tile. A fill isn’t kept when JimiOS restarts.

macOS’s own full screen (the green button) also works. When the window comes out of full screen, it goes back to its old tile.

Flip split

What it does. ⌥T turns the split holding the focused window from side by side to stacked, or back.

How to use it. Press ⌥T. If that split can’t flip because the windows wouldn’t fit, JimiOS flips the nearest split above it that can, and says which. If none can, the message gives the numbers, for example “can’t stack open-threads and Grok Bot: each would get 305 high; open-threads needs 480”.

Rotate

What it does. ⌥⇧R moves every window on the workspace one tile clockwise. Tiles resize to fit the windows that land in them.

How to use it. Press ⌥⇧R. Repeat until the windows are where you want them.

Reset splits

What it does. ⌥⇧0 puts every split on the workspace back to 50 %, and undoes any ⌥T flips. Where a 50 % split wouldn’t fit a window’s minimum size, JimiOS keeps the split as it is.

How to use it. Press ⌥⇧0, or choose Reset splits to 50 % from the menu.

The overflow row

What it does. Each workspace can have one overflow row directly below the screen. It holds windows that don’t fit on screen at their app’s minimum size. It’s spill-over, not extra working space: there’s only ever one row, and the windows in it sit side by side.

While the row is hidden, a strip of it peeks up from the bottom edge (at least 8 pt). When you show it, the row moves up into the bottom of the screen. The tiles above shrink to make room if they can. If they can’t, the layout moves up, and the top tiles move aside while the row shows. Hiding the row puts every window back exactly where it was.

How to use it.

Show the row: press ⌃⌥↓ at the bottom edge, hold ⌃⌥ and scroll down, click the strip, or ⌘Tab to a window in the row.
Hide the row: press ⌃⌥↑ from the row (or at the top edge while it shows), or hold ⌃⌥ and scroll up.
While the row shows, focus keys and move keys go between the row and the tiles like any tile, and you can drag windows in and out.
When room appears on screen (a window closes or shrinks), windows in the row move back up automatically, oldest first.

In h/j/k/l mode, use ⌥J and ⌥K instead of ⌃⌥↓ and ⌃⌥↑.

When a window doesn’t fit

macOS can’t draw a window smaller than its app’s minimum size, so sometimes a window won’t fit. JimiOS never overlaps windows to make it fit, never floats a window you expected to tile, and never moves other windows off the workspace to make room. It tries these steps in order:

Re-measure. If a remembered minimum size looks wrong, JimiOS checks it once with the app.
Split. It splits the focused tile, adjusting the splits if that helps.
Overflow row. It puts the window in the overflow row, if the row still has room.
Rearrange. It tries other arrangements of the workspace’s windows.
Next workspace right. It sends the window to the next workspace up where it fits. An empty workspace always fits.

A message on the screen the window left says where it went, for example “Xcode → overflow below (doesn’t fit on screen) · ctrl-alt-down to show” or “Xcode → workspace 3 (doesn’t fit on 2)”. On workspace 9 there’s no workspace to the right, so the overflow row is the last stop. If that row is full too, the window floats in the middle of the screen.

The same order applies when you tile a floating window back, when an app’s minimum size grows, and when you move a window somewhere it doesn’t fit.

Minimum sizes and re-measuring

What it does. JimiOS learns each app’s minimum and maximum window size, for each display, and plans layouts around them. It saves them in min-sizes.json in ~/Library/Application Support/JimiOS Alpha.

A remembered size can be wrong, for example one learned on another display or on an earlier day. When such a size blocks a resize or a new window, JimiOS asks the app once (per app, per direction, per day) and saves the answer, whether it’s lower or higher.

If you see a window that keeps too large a minimum, that is the case to report.

A tile is never smaller than 200 pt on either side unless you change min_tile. Above that, the apps’ own minimum sizes decide.

Gaps and the focus border

What it does. Tiles sit 8 pt apart and 8 pt from the screen edges. JimiOS draws a 3 pt rounded border just outside the focused window, in the gap, so it never touches a neighbour. The border follows each window’s own corner radius. It hides while you drag or resize a window by hand, while JimiOS is paused and while you’re on another macOS desktop.

When the focused window closes, the focus and the border move to the window that took its space. They don’t move if that would take focus from a dialog, another app or another desktop.

How to use it.

Press ⌥B to step through the border’s lighting modes: Spark glow, Hyprland default, Cyberpunk, Sunset, Toxic, Ultraviolet, Inferno, Ice, Rainbow and Off. JimiOS remembers your choice. Each press shows the mode’s name and number, for example “Sunset (4/10)”.
Change the gaps with gaps_in (each side of a tile, so twice that between tiles) and gaps_out (to the screen edge). The border narrows to fit if gaps_in is below 3 pt, and isn’t drawn at all if gaps_in is 0. There’s no setting for the border’s width.

Multiple displays and screen_workspaces

What it does. Every display is tiled. All displays share workspaces 1 to 9. JimiOS orders displays left to right, so ⌃⌥← and ⌃⌥→ cross to a display wholly to the left or right. The pointer moves to the display that gets the focus.

With screen_workspaces you can give workspaces to a named display. For example, {"BenQ": [2]} puts workspace 2 on the display whose name contains “BenQ”. While that display is connected, workspace 2 shows only there, and every other workspace stays on the built-in display. ⌥2 then takes the focus to the BenQ; ⌥1 brings it back to the laptop.

How to use it.

Turn off System Settings → Desktop & Dock → Mission Control → “Displays have separate Spaces”, then log out and back in.
Arrange the displays side by side in System Settings → Displays.
Optionally, add screen_workspaces to the settings file (see Give a workspace to your external display).

Without screen_workspaces, ⌥⇧N with N set to the workspace on the other display swaps the two displays’ workspaces. With it, that swap is turned off and the message says “already on workspace N”.

In this beta: multiple displays were rebuilt in 0.1.0 and haven’t had a full two-display test yet. Displays stacked one above the other are untested. See Known limits.

Sleep, wake and unplugging

What it does. Sleep, wake, locking the screen, unplugging or plugging in a display, and changing a resolution or arrangement never move a window to another workspace. JimiOS waits until macOS has finished (2 seconds after the last display change, 3 seconds after a wake or unlock), then lays everything out once.

Unplug. The display’s workspaces move to the remaining display exactly as they were. On a smaller screen, what doesn’t fit goes to that workspace’s overflow row.
Plug back in. Each workspace goes back to its display, matched by the display’s ID, with its windows in the same order.
A window that disappears briefly (for example, when an app quits and reopens within a minute) goes back into its own tile.

How to use it. Nothing to do. If the timing doesn’t suit your displays, the advanced settings display_settle_ms and wake_grace_ms change it.

Messages and the move tone

What it does. Short messages appear in the middle of the screen with the focus:

“Workspace N” each time a display shows a different workspace;
the layout name after ⌥R;
why a move stopped, for example “already on workspace 1”;
why a resize stopped, for example “Spark Desktop can’t get shorter than 700”;
when a window floats or fills the screen, with the key that undoes it.

These show for about 1.6 seconds.

When a window has to move to the overflow row or another workspace, you hear one quiet tone. A message stays on the screen it left, saying where it went. Several windows moving at once make one message. A window that comes back gets its own message, for example “Spark ← back from workspace 3”.

How to use it. Press Escape or click the message to close it; that Escape doesn’t reach your app. It fades by itself after a minute. Turn messages off with workspace_toast and flow_toast.

Pause tiling

What it does. Stops JimiOS tiling without quitting. The keys it uses (such as ⌥F and ⌥R) type normally again.

How to use it. Click J1 in the menu bar and choose Pause tiling. Choose Resume tiling to start again.

What it does. Starts JimiOS when you log in.

How to use it. Tick “Open JimiOS when I log in” in the welcome box, or choose Open at Login from the menu. A tick shows when it’s on; choose it again to turn it off.

Restore after a restart

What it does. JimiOS saves your layout as you work. When you quit and reopen JimiOS (or update it) in the same login session, each window goes back to its workspace and tile, with its split sizes and the overflow row. The layout must be less than 24 hours old.

The layout is kept until the Mac restarts, not after. A restart, or logging out, starts fresh.

How to use it. Nothing to do. To always start fresh, set restore_layout_on_start to false.

Hiding the Dock

What it does. With hide_dock set to true, JimiOS hides the Dock while it runs: the Dock takes no space and never pops up. JimiOS puts your own Dock settings back when it quits, including after a crash.

With hide_dock off (the default), the Dock keeps its space. Tiles are shortened to sit above the overflow row’s strip only while a workspace has an overflow row.

How to use it. See Hide the Dock.

Performance mode

What it does. Turns off some macOS animations, Stage Manager, macOS’s own edge tiling and Space rearranging while JimiOS runs, then puts them back when it quits. It’s off by default. Please leave it off during the beta, so reports reflect your normal macOS settings.

The menu shows Performance mode: off or on.

Click J1 in the menu bar for:

Pause tiling / Resume tiling
Reset splits to 50 % (alt-shift-0)
Keyboard shortcuts (alt-/)
Performance mode: off (a status line)
Open at Login
Uninstall JimiOS…
Quit JimiOS Alpha (restores windows)