# Amethyst: an xmonad-style tiling window manager for macOS

> Amethyst is an MIT-licensed tiling window manager for macOS, written in Swift and installed with a Homebrew cask. It is for keyboard-first Mac users who want automatic window arrangement, and it is the wrong tool for anyone who cannot live with macOS accessibility permissions and Mission Control quirks.

**ianyh/Amethyst** — Automatic tiling window manager for macOS à la xmonad.

- Repository: https://github.com/ianyh/Amethyst
- Website: https://ianyh.com/amethyst/
- Stars: 16,274 · Forks: 534
- Language: Swift
- License: MIT
- Published: 2026-09-21 · Updated: 2026-09-21 · Language: en
- Canonical page: https://hysenlabs.com/projects/ianyh-amethyst

## The problem Amethyst solves on a Mac

macOS has no built-in tiling. Windows overlap, and arranging them is a manual drag-and-resize exercise that has to be repeated every time a window opens or closes. Amethyst takes over that job: it arranges windows automatically into panes and lets you move focus, swap windows and change layout from the keyboard. The README describes it as a tiling window manager 'along the lines of xmonad', and the default key bindings are explicitly 'mostly a mapping to xmonad key combinations', so the intended audience is people who already think in terms of a main pane, a stack and modifier-driven navigation. If you are comfortable with macOS itself but not with dragging windows, Amethyst is aimed at you. It is not a launcher, not a window-preview tool and not a replacement for Mission Control; it only controls how windows are laid out on a screen.

## How the tiling, layouts and modifier system fit together

Amethyst arranges windows into layouts, and the README documents the set: Tall, Tall-Right, Wide, Two Pane, Two Pane Right and 3Column-Left among them, plus fullscreen, column, row, floating, widescreen-tall and bsp. Tall is the default. It gives one main pane on the left and a second pane on the right; a single window fills the main pane at full screen height, and everything else goes into the other pane, which splits into rows when it holds more than one window. Tall-Right is the same with the panes swapped, and Wide is Tall rotated so the main pane runs across the top and the secondary pane splits into columns. Two Pane is different in kind: the main window is pinned and the remaining windows share the other pane one at a time, with the keyboard used to swap which one is visible, and it flips between horizontal and vertical tiling depending on screen orientation.

Control is built on four modifier combinations. mod1 is option + shift and mod2 is ctrl + option + shift; mod3 and mod4 are not defined by default. The documented bindings cover the mechanics you would expect: mod1 + space cycles layout forward, mod1 + h and mod1 + l shrink and expand the main pane, mod1 + , and mod1 + . change the main pane count, and mod1 + j and mod1 + k move focus. Windows can be thrown to numbered spaces with mod2 plus a digit, and mod1 + z forces windows to be reevaluated, which is the documented escape hatch when a window has been placed oddly. Layouts can be enabled or disabled to control whether they appear in the cycle sequence at all, so a long list of layouts does not have to mean a long cycle.

## Installing Amethyst and arranging windows for the first time

The README gives two routes: a direct download from the releases page, or the Homebrew cask. The cask is the one-liner most people will use.

```bash
brew install --cask amethyst
```

After installation, Amethyst has to be granted access to the accessibility APIs. The README points to the Privacy & Security tab, under Privacy then Accessibility. Until that permission is granted, the app cannot move other applications' windows, so this step is not optional.

The README then gives a second setup step that is easy to skip and unpleasant to debug later. macOS enables 'Automatically rearrange Spaces based on most recent use' by default, which causes Spaces to swap places and makes keyboard navigation between them unpredictable. The README recommends turning it off in Mission Control, and gives the terminal equivalent:

```bash
defaults write com.apple.dock workspaces-auto-swoosh -bool NO
killall Dock
```

With both steps done, the first real use is to open a handful of windows and press mod1 + space to cycle layouts. The README lists mod1 + i as the binding that displays the current layout, which is the quickest way to confirm that Amethyst is running and responding rather than silently blocked by a missing permission. From there, mod1 + a selects the tall layout, mod1 + t toggles float for the focused window, and mod2 + t toggles global tiling.

## Where Amethyst gets in the way

The accessibility requirement is the first real constraint, and it is structural rather than cosmetic. Amethyst has to be trusted with control of other applications' windows; if that permission is revoked or not granted, tiling simply does not happen. The README treats this as a prerequisite rather than a troubleshooting step.

The second constraint is the Spaces behaviour described above. The README calls the auto-rearrange setting 'enabled by default' and warns that it 'will cause your Spaces to swap places based on use', which makes keyboard navigation unpredictable. That is a macOS default fighting the tool, and the fix is a global system setting plus a Dock restart, not an Amethyst preference.

The third is platform support. The README states that Amethyst is now only supported on macOS 10.15 or later, so older systems are out. And the project's own escape hatch, mod1 + z to force windows to be reevaluated, is an admission that window placement does not always land correctly on the first try. If your work depends on deliberately overlapping windows, free-form positioning, or apps that fight any external window control, a tiling manager is the wrong layer to add. The README also directs readers to a troubleshooting document for common issues, which is where the project expects these cases to be handled.

## Amethyst against macOS's own window tools

The obvious alternative is not another tiling manager but macOS itself: Mission Control, Spaces and full-screen apps. The difference in approach is manual versus automatic. Mission Control and Spaces let you organise windows by hand and switch between groups; nothing rearranges a pane when a window opens or closes. Amethyst recomputes the layout continuously, so the arrangement is a function of how many windows exist and which layout is selected, not of where you last dragged something. That is the whole trade: you give up direct control of window geometry in exchange for never having to place a window again. A second difference is input. macOS window management is pointer-first; Amethyst is keyboard-first, with the modifier combinations above doing the work. If you like the pointer and dislike modifier chords, the built-in tools are the better fit, and Amethyst will feel like it is taking something away.

## Maintenance, releases and the MIT licence

The repository is not archived, and the last push to the development branch was on 2026-08-19. The most recent release listed is v0.24.3 from 2026-04-02, following v0.24.2 on 2026-03-01 and v0.24.1 on 2025-12-06. Those dates describe a project that is still receiving commits and tagged releases, but the README does not document an upgrade procedure, and it does not document rollback. The practical upgrade path for a Homebrew cask install is the cask itself, and the README describes nothing beyond that. Because the default branch is development, building from source means building from that branch rather than from a release tag, which is worth knowing before you do it.

The licence is MIT, which permits use, modification and redistribution provided the copyright notice and permission notice are included. That is a permissive arrangement, and it matters here because Amethyst modifies the behaviour of other applications' windows. This is a description of the licence text, not legal advice; if you plan to redistribute a modified build, read LICENSE.md in the repository and take your own advice.

## Conclusion

Adopt Amethyst if you work primarily from the keyboard and want xmonad-style automatic tiling without leaving macOS; skip it if you rely on manually placed, overlapping windows or cannot grant accessibility control to a third-party app. Before committing, verify that the Accessibility permission is granted, that 'Automatically rearrange Spaces based on most recent use' is disabled, and that your macOS version is 10.15 or later. The last push to the development branch was on 2026-08-19, and the newest release in the repository is v0.24.3 from 2026-04-02.

## FAQ

### How do I install Amethyst on macOS?

The README gives two options: download directly from the releases page, or install the Homebrew cask with brew install --cask amethyst. After that, grant Amethyst accessibility permission under Privacy & Security, Privacy, Accessibility.

### Which macOS versions does Amethyst support?

The README states that Amethyst is now only supported on macOS 10.15 or later.

### Why does Amethyst need accessibility permission?

The README says Amethyst must be given permission to use the accessibility APIs, found under Privacy & Security, Privacy, Accessibility. Without it the app cannot manage other applications' windows.

### Why does keyboard navigation between Spaces behave unpredictably with Amethyst?

The README attributes this to 'Automatically rearrange Spaces based on most recent use', which is enabled by default and causes Spaces to swap places based on use. It recommends disabling that setting in Mission Control, or running defaults write com.apple.dock workspaces-auto-swoosh -bool NO followed by killall Dock.

### What are Amethyst's default keyboard shortcuts?

Amethyst uses mod1 (option + shift) and mod2 (ctrl + option + shift), with mod3 and mod4 undefined by default. Documented bindings include mod1 + space to cycle layout forward, mod1 + h and mod1 + l to shrink and expand the main pane, and mod1 + i to display the current layout.

## Sources

- [ianyh/Amethyst on GitHub](https://github.com/ianyh/Amethyst)
- [License: MIT](https://github.com/ianyh/Amethyst/blob/development/LICENSE)
- [Project website](https://ianyh.com/amethyst/)
- [README](https://github.com/ianyh/Amethyst/blob/development/README.md)
- [Releases](https://github.com/ianyh/Amethyst/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/ianyh-amethyst