Cairn Window Manager Documentation
Overview
Cairn is a Mac window manager that lives in your menu bar. It remembers how you like your windows arranged and puts them back that way with one click. If you switch between different work contexts, say coding in the morning and writing in the afternoon, you probably open roughly the same apps in roughly the same spots each time. Cairn saves that arrangement as a stack and restores it from the menu bar, so you’re not dragging six windows back into place by hand every time you switch.
Requirements
- macOS 12 (Monterey) or later
- Apple Silicon and Intel Macs both work
- Accessibility permission, requested on first launch (see Privacy & Permissions)
Cairn is Mac only. There’s no Windows or Linux build.
Installing
- Go to cairnstacks.app and click download for mac. The same build is also on GitHub Releases if you’d rather get it there.
- Open the downloaded
Cairn.dmgand drag Cairn into Applications. - Launch Cairn. It lives in your menu bar; there’s no dock icon.
- Grant Accessibility access when prompted. Cairn can’t capture or apply layouts without it.
Once it’s installed, Cairn checks for and installs updates on its own through Sparkle, unless you turn that off in Settings (see Features below). When an update is ready to install, the menu bar item swaps Check for Updates for Restart to Update.
Quick Start
- Open the apps you want in a layout and arrange them roughly how you like them.
- Click the Cairn menu bar icon, then Snapshot to New Stack.
- Your layout saves as a new stack and the Cairn window opens with it ready to edit. Give it a name if you want.
- Next time, click the Cairn icon and pick that stack from the list to put every window back exactly where it was.
Core Concepts
- Stack
- A named layout: which apps, where their windows sit, and how many displays the layout uses.
- Fractional coordinates
-
A window’s position and size are stored as fractions of the screen, from 0 to 1 on each axis, instead
of fixed pixels. A window at
x: 0.5, width: 0.5always means “the right half of the screen,” whether that screen is a 13" laptop or a 32" external display. It’s the reason a stack built on one monitor still looks right on a completely different one. - Screens
- A stack targets one or two displays. Each window in a two-display stack is pinned to a specific display, and the editor shows both as separate canvases side by side.
Features
The menu bar
Click the Cairn icon and you’ll see Open Cairn, every saved stack listed by name below it, Snapshot to New Stack, Settings, update controls, and Quit. Picking a stack from the list applies it immediately. There’s no number-key shortcut for individual stacks anymore; you just click the one you want.
The Cairn window
Choosing Open Cairn (or clicking a stack to apply it) brings up Cairn’s main window: a sidebar listing every stack on the left, and an editor for whichever one is selected on the right. This is where you build and arrange stacks.
Creating a stack
- Snapshot your current windows into a new stack. Cairn scans every standard window of every running app, figures out which screen each one mostly sits on, and records its position as a fraction of that screen.
- Start blank instead, using the plus button in the sidebar, then add apps by hand from a file picker. New apps land in a loose cascade near the center of the canvas so they don’t all pile on top of each other.
Editing a stack
Select a stack in the sidebar to open it in the editor. Each window in the stack appears as a tile carrying its real app icon and name, on a canvas for each display the stack uses.
- Move a tile by dragging it.
- Resize by dragging any edge or corner.
- Snap. Each canvas runs on a 12×8 grid. Dragging a tile snaps its edges to grid lines and to neighboring tiles, so two windows can line up flush without you eyeballing it. Hold Shift if you want to place something freely for one move.
- Quick presets in the inspector panel: left half, right half, top half, bottom half, full screen, centered.
- Exact geometry fields (X, Y, width, height, all as percentages) when you want something precise.
- Remove a window by selecting its tile, then clicking the small x on the tile, clicking Remove Window in the inspector, or pressing Delete.
- Switch display count. Moving a stack from one display to two adds a second canvas. Moving back to one drops anything you’d placed on the second display.
- Rename a stack by editing its name at the top of the editor.
- Duplicate or delete a stack from its right-click menu in the sidebar.
Applying a stack
Hit Apply in the editor, or pick the stack from the menu bar. Either launches any app in the stack that isn’t already running, waits for its windows to show up, and moves everything into its recorded position. The How It Works section below covers the mechanics if you’re curious.
Re-capturing a layout
Rearranged your windows and want the stack to catch up? Open it in the editor and hit Snapshot again. This replaces every window in that stack with a fresh scan of what’s currently open, so it’s a clean overwrite, not a merge with what was there before.
Settings
Open Settings from the menu bar, or press ⌘, while you’re viewing your stacks. It’s split into three sections:
- Shortcut. Record a custom global keyboard shortcut for Snapshot to New Stack, so you can save your current layout from any app without reaching for the menu bar. Nothing is set by default; you choose your own here.
- Updates. A single toggle for whether Cairn checks for and installs new versions automatically in the background. Switch it off and Cairn won’t check on its own; use Check for Updates in the menu bar whenever you want to look for a new version yourself.
- Support. A direct link to support the project financially, if Cairn’s been useful to you.
Keyboard Shortcuts
| Shortcut | Action |
|---|---|
| ⌘, | Open Settings, while viewing your stacks |
| Esc | Back to your stacks, while in Settings |
| Your own, set in Settings | Snapshot current windows into a new stack, from anywhere |
| Shift held while dragging | Skip grid snapping for that move |
| Delete or Backspace | Remove the selected window tile |
| Esc | Deselect the current window tile, while editing a stack |
Applying a specific stack doesn’t have a shortcut of its own; you pick it by name from the menu bar.
How It Works
macOS’s accessibility API is the only way to move another app’s windows around, and it doesn’t always cooperate. Some apps enforce their own minimum size and push back on a resize request outright. Cairn deals with this by setting a window’s frame, checking what actually happened to it, and adjusting its next request if the app resisted, repeating that loop until the window settles into place.
The same process launches apps that aren’t running yet, waits for their windows to actually appear, and opens extra windows for anything that needs more than one in a stack. None of this locks up the interface. Placement runs in the background, so Cairn stays responsive while it talks a stubborn window into the right spot.
Privacy & Permissions
Cairn asks for Accessibility access because that’s the only way any macOS app can read or move another app’s windows. It’s the one permission Cairn needs, and it’s used for exactly that: reading window positions when you snapshot a stack, setting them when you apply one.
Cairn doesn’t collect analytics, doesn’t send your window layouts or app usage anywhere, and has no network access beyond checking for updates. Everything it knows about your stacks sits in a single file on your Mac (see Your Data below).
You can review or revoke Cairn’s Accessibility access any time in System Settings → Privacy & Security → Accessibility.
Your Data
Stacks live in a single JSON file at:
~/Library/Application Support/Cairn/stacks.json
If that file ever turns up unreadable, say a bad edit, a crash mid-write, or disk corruption, Cairn
won’t overwrite or quietly drop it. It renames the broken file next to itself with a
.corrupt suffix and starts over with an empty stack list, so whatever was there is still
sitting on disk if you need to recover it by hand.
Uninstalling
- Quit Cairn from the menu bar.
- Drag
Cairn.appfrom Applications to the Trash. -
Optional: delete its saved stacks and preferences at
~/Library/Application Support/Cairn/. - Optional: remove Cairn’s entry from System Settings → Privacy & Security → Accessibility.
FAQ
Is Cairn free?
Yes. Cairn is free and open source under the MIT license. Source on GitHub.
Does Cairn work with multiple monitors?
Yes. A stack can span a main display and a secondary one, and since positions are stored as fractions of the screen, a layout saved on one monitor still makes sense on another.
How is Cairn different from Rectangle, Magnet or a tiling window manager?
Rectangle and Magnet move and resize windows into set positions, such as halves, thirds and corners, with keyboard shortcuts or by dragging a window to a screen edge. Rectangle can also tile the windows on a display into rows or columns, but neither saves an arrangement to restore later; the paid Rectangle Pro adds saved layouts. Tiling window managers like yabai, AeroSpace and Amethyst tile windows automatically as they open and close, and are mostly driven from the keyboard. Cairn is free and works on whole arrangements: set your windows up once, save them as a stack, and put every app back into that layout with one click, launching any that aren’t running. It doesn’t rearrange new windows as they open.
Is there a Windows or Linux version?
No, Cairn is Mac only.
How do I get new versions?
Updates happen through Sparkle. By default Cairn checks and installs them automatically in the background; you can turn that off in Settings and use Check for Updates in the menu bar instead whenever you want.
Troubleshooting
Cairn asks for Accessibility permission every time I open it.
Check System Settings → Privacy & Security → Accessibility and make sure Cairn is listed and switched on. After reinstalling Cairn, macOS sometimes wants the old entry removed before it’ll accept a fresh one.
A window didn’t move, or ended up the wrong size.
Some apps are stubborn about their minimum window size and will resist placement even after several retries. Try resizing the window close to the target by hand first, then re-apply the stack.
My stacks disappeared.
Look in ~/Library/Application Support/Cairn/ for a file ending in .corrupt.
If it’s there, Cairn found that the real stacks.json was unreadable and kept the old copy
under that name instead of just losing it.
Support
- Contact: hello@cairnstacks.app
- Bugs and feature requests: open an issue on GitHub
- Source code: github.com/lukesj28/cairn
- Support the project: the Support Cairn link in the app’s Settings, or the coffee-cup link on the website