cairn docs

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

  1. Go to cairnstacks.app and click download for mac. The same build is also on GitHub Releases if you’d rather get it there.
  2. Open the downloaded Cairn.dmg and drag Cairn into Applications.
  3. Launch Cairn. It lives in your menu bar; there’s no dock icon.
  4. 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

  1. Open the apps you want in a layout and arrange them roughly how you like them.
  2. Click the Cairn menu bar icon, then Snapshot to New Stack.
  3. Your layout saves as a new stack and the Cairn window opens with it ready to edit. Give it a name if you want.
  4. 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.5 always 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

  1. Quit Cairn from the menu bar.
  2. Drag Cairn.app from Applications to the Trash.
  3. Optional: delete its saved stacks and preferences at ~/Library/Application Support/Cairn/.
  4. 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

About This Site

Cairn’s website at cairnstacks.app isn’t a conventional static marketing page. It presents the app through an interactive, scroll-driven experience, with a flying helper character you can actually ask questions.

The scroll journey

Scrolling, swiping, arrow keys, Page Up/Down, Home/End: any of these move you through three stages, each rendered as a full-bleed looping video.

  1. Intro. The landing stage, with the Cairn wordmark and a “download for mac” button front and center.
  2. A middle stage, reached by scrolling further.
  3. The cairn. The final stage, where an actual stacked cairn renders on canvas. Each stone glows and lifts slightly on hover, and each one is its own clickable link.

The transitions between stages crossfade between real video clips rather than scrubbing a single timeline, so the motion stays smooth no matter how fast or slow you scroll. The whole thing also respects prefers-reduced-motion: if you’ve asked your system for less motion, stage changes happen instantly with no camera movement at all.

The stones

The finished cairn is built from four stones, and each one leads somewhere different:

  • Top. Opens the documentation (this page).
  • Second. Links to the GitHub source.
  • Third. Shows what’s new.
  • Bottom. Opens a “buy me a coffee” support panel, right there in place.

Hover or focus a stone and a short label pops up telling you what it does before you commit to clicking.

The helper

A small flying character travels with you through the scroll journey and doubles as the site’s main way of answering questions, for anyone who’d rather ask than read. It greets you with a chat bubble once you reach it, keeps that bubble open while you ask questions, and repositions itself at each stage so it’s never in the way of the stones or whatever else is on screen.

Ask it anything about Cairn: how to install it, what it costs, which platforms it runs on, whether it handles multiple monitors, how updates work. Common questions get an instant answer that’s already written out. Anything else goes to a small assistant that only knows about Cairn, and it’ll point you back to this page or the GitHub README rather than guess at something it doesn’t actually know.

Pages for everyone else

The scroll-and-helper experience is how the site is meant to be used, but it’s not the only option. This documentation page exists for anyone who’d rather read straight through than explore the interactive version.