rooms README

The project's README from github.com/saragordic/rooms. As one markdown file: README.md.

Rooms

A little Mac app I made for switching between projects.

Every project is a room: a set of windows and a layout. Press ⌥Space, type the room's name, and your windows come back, laid out neatly. Everything else hides, and nothing is ever closed.

The Rooms switcher over a tidy desk, listing four rooms: Design, Build, Deep Work and Morning

Get it

You can just send this repo to your coding agent and ask it to install Rooms for you:

Install Rooms on my Mac: https://github.com/saragordic/rooms

Or install it yourself with Homebrew:

brew trust saragordic/tap
brew install --cask saragordic/tap/rooms

Then open Rooms from your Applications folder. It lives in the menu bar.

You can also grab the latest ZIP from Releases, unzip it, and drag Rooms.app into Applications. The app isn't notarized by Apple yet, so macOS blocks the first launch of the ZIP version: open System Settings → Privacy & Security → Open Anyway after trying to launch it. Apple's instructions explain this step. (The Homebrew version opens straight away.)

Rooms needs Accessibility access to move windows. Turn it on in System Settings → Privacy & Security → Accessibility when it asks. After an update, macOS may ask again: remove Rooms from that list and add it back.

Make your first room

  1. Open the windows a project needs.
  2. Press ⌥Space, type a name for the room, and press Enter.
  3. Click the windows that belong in it. The number on a card is its place in the layout, and 1 is the main window. Then Create Room.
  4. Press Tab to change the layout. In ⌥Space, select the room and press Tab (⇧Tab goes back): the preview shows each layout that fits your screen, and the room remembers the one you pick.

The windows come to the screen you're on and lay themselves out. From then on, ⌥Space and the room's name (or ⌃⌥1–9) brings it back. Getting Started in the menu shows these steps again.

Around the rooms

Nothing closes

Windows that aren't in the room are hidden, or parked just off-screen when they belong to one of the room's apps. Before a window moves, Rooms writes down where it belongs, and only forgets once the window is back. Show Everything in the menu, quitting Rooms, or opening it again after a crash brings parked windows back; one whose app isn't responding stays recorded and comes back on the next try.

Privacy

Rooms works entirely on your Mac. It makes no network connections of any kind: no accounts, no analytics, no updates checked, nothing sent anywhere.

Your rooms live in ~/Library/Application Support/Rooms/rooms.json, which you can read and edit (Edit Rooms… in the menu). Parked windows are recorded next to it in resting.json, and a log of what Rooms moved stays in ~/Library/Logs/Rooms/rooms.log. These include window titles, so please don't post them unedited in an issue.

A little work in progress

I built this on my Mac and use it all day, but there are still rough edges:

It's built for macOS 14 or later, on Apple Silicon and Intel. I've tested it on Apple Silicon with macOS 26; older macOS versions and Intel Macs haven't had the same hands-on testing.

If something looks wrong, open an issue and tell me your macOS version, Mac model, and whether you're using another screen. Reproduction steps help a lot.

Build it yourself

You'll need Xcode 16 or later (or its Command Line Tools: xcode-select --install).

git clone https://github.com/saragordic/rooms.git
cd rooms
make run

This builds build/Rooms.app and opens it. To keep the Accessibility permission across rebuilds, create a certificate named Rooms Dev in Keychain Access (Certificate Assistant → Create a Certificate → type "Code Signing"); the Makefile uses it when it exists.

Taking it off

Choose Quit Rooms from the menu first: parked windows come back as it quits. Then, if you installed it with Homebrew:

brew uninstall --zap --cask rooms

--zap also removes your rooms and settings. Leave it off to keep them for later.

If you installed it by hand, drag Rooms.app to the Trash, then delete these if you want everything gone:

~/Library/Application Support/Rooms
~/Library/Logs/Rooms
~/Library/Preferences/com.saragordic.rooms.plist

macOS remembers the Accessibility permission separately, so remove Rooms from System Settings → Privacy & Security → Accessibility too.

Contributing

make test      # run the tests for the layout engine
make release   # build the universal Rooms.app and its ZIP

See CONTRIBUTING.md for more details.

License

MIT. See LICENSE.

rooms (saragordic/rooms)

Searching Database…

389 ·GitHub
Rooms
What is this?Rooms is a macOS app for switching between projects: each 'room' is a saved set of windows with a layout, and one shortcut brings them all back arranged neatly while hiding everything else.
Is this a window manager or just a launcher?It's a window manager that also handles window layout and switching: it arranges windows in layouts like Focus, Columns, Grid, or Stack, and parks or hides windows outside the active room instead of closing them.
How do I install and set up Rooms?Install via Homebrew, download the ZIP from Releases and drag Rooms.app into Applications, or ask a coding agent to install it for you. Then open the windows for a project, press ⌥Space, name the room, pick the windows that belong, and press Enter.
Do I need anything special before installing it, like Xcode?Just macOS and Homebrew (or manual ZIP install) to run it; Xcode 16 or its Command Line Tools are only needed if you want to build it yourself from source.
Any rough edges I should know about?Rooms manages browser windows, not individual tabs; some apps won't shrink below a minimum size so Stack may be the only layout that fits; Spaces and full-screen windows aren't managed; and Stage Manager conflicts with it. The ZIP build also isn't notarized, so macOS blocks the first launch until you allow it manually.
Does it work on Intel Macs, or only Apple Silicon?It supports macOS 14+ on both Apple Silicon and Intel, though the author has only done hands-on testing on Apple Silicon with macOS 26, so Intel and older macOS versions are less tested.
Does Rooms send any of my data anywhere?No. Rooms works entirely on your Mac and never makes network connections; room data and logs are stored locally in plain JSON and log files you can read yourself.
How does switching rooms actually work day to day?Press ⌥Space, type or pick the room's name (or use ⌃⌥1-9), and Rooms brings that room's windows to the current screen in the saved layout while hiding or parking everything else.
Can I change how windows are arranged in a room?Yes, press Tab in ⌥Space to cycle through layouts (Focus, Columns, Grid, My Layout, Stack) that fit your screen, or arrange windows by hand and press ⌘S to have Rooms remember that exact arrangement.
What happens to windows that aren't part of the active room?They are never closed, only hidden or parked just off-screen; Show Everything in the menu, quitting Rooms, or reopening it after a crash brings them all back.
Does uninstalling remove all my rooms and settings?If installed via Homebrew, running the uninstall with --zap also removes your rooms and settings; leaving that off, or dragging Rooms.app to the Trash manually, keeps them for later.
What are similar projects?macos-sysdata, tendedero, DockDoor, vorssaint-utils, OpenYoink, pliss, BetterDisplay, boring.notch
Which topics is it in?window-management, menubar-app, menubar, window-manager, menu-bar, xcode, macos-app, homebrew, apple-silicon, swift, offline, utility
Creator
saragordic
Size
0.4 MB
Stars
389
Updated
CommitSep 26Releasev1.0.1Sep 23
Age
24d
Commits · 90 Days