Amethyst

Automatic tiling window manager for macOS à la xmonad.

14,622

486

14,622

372

View on GitHub

Top Related Projects

yabai

23,088

A tiling window manager for macOS based on binary space partitioning

phoenix

4,361

A lightweight macOS window and app manager scriptable with JavaScript

ShiftIt

5,530

Managing windows size and position in OSX

Rectangle

25,585

Move and resize windows on macOS with keyboard shortcuts and snap areas

Quick Overview

Amethyst is an open-source tiling window manager for macOS. It automatically organizes windows into predefined layouts, allowing users to efficiently manage their workspace without manual resizing or repositioning. Amethyst aims to bring the tiling window management experience, popular in Linux environments, to macOS users.

Pros

Increases productivity by automating window management
Supports multiple layouts and easy switching between them
Customizable through a preferences pane and configuration file
Integrates well with macOS, including support for multiple displays and spaces

Cons

Learning curve for users new to tiling window managers
May conflict with some macOS native window management features
Limited compatibility with certain applications that have non-standard window behaviors
Occasional performance issues, especially with a large number of windows

Getting Started

Install Amethyst using Homebrew:
```
brew install --cask amethyst
```
Launch Amethyst from your Applications folder.
Grant necessary permissions when prompted (Accessibility and Screen Recording).
Use the default keyboard shortcuts to manage windows:
- Option + Shift + Space: Cycle through layouts
- Option + Shift + Enter: Make focused window main window
- Option + Shift + H/L: Shrink/expand main pane
Customize layouts and shortcuts in Amethyst's preferences pane or by editing the configuration file at ~/.amethyst.yml.

Competitor Comparisons

yabai

23,088

A tiling window manager for macOS based on binary space partitioning

Pros of yabai

More powerful and customizable window management
Supports advanced features like window stacking and gaps
Offers scripting capabilities for complex workflows

Cons of yabai

Steeper learning curve and more complex configuration
Requires disabling System Integrity Protection (SIP) for full functionality
May have compatibility issues with some macOS versions

Code Comparison

Amethyst configuration (in ~/.amethyst.yml):

layouts:
  - tall
  - wide
  - fullscreen
mod1:
  - option
  - shift

yabai configuration (in ~/.yabairc):

yabai -m config layout bsp
yabai -m config top_padding 10
yabai -m config window_gap 10
yabai -m rule --add app="^System Preferences$" manage=off

Amethyst uses a YAML configuration file for basic settings, while yabai uses a shell script for more detailed configuration. yabai's approach allows for more complex rules and customizations, but may be less intuitive for beginners.

Both tools aim to enhance window management on macOS, but yabai offers more advanced features at the cost of increased complexity. Amethyst is generally easier to set up and use, making it a good choice for users who want a simpler tiling window manager. yabai is better suited for power users who need extensive customization options and are comfortable with more technical configurations.

phoenix

4,361

A lightweight macOS window and app manager scriptable with JavaScript

Pros of Phoenix

Written in Swift, potentially offering better performance and native macOS integration
More actively maintained with recent updates and contributions
Supports additional features like window snapping and custom layouts

Cons of Phoenix

Smaller community and fewer contributors compared to Amethyst
Less extensive documentation and fewer user guides available
May have a steeper learning curve due to its JavaScript-based configuration

Code Comparison

Amethyst (Swift):

override func layoutScreens() {
    screens.forEach { screen in
        guard let layout = self.layout(for: screen) else {
            return
        }
        layout.apply(screen, windows: windows(on: screen))
    }
}

Phoenix (JavaScript):

Phoenix.set({
  openAtLogin: true
});

const layout = new Layout('main', (window) => {
  window.setFrame({
    x: window.screen().flippedVisibleFrame().x,
    y: window.screen().flippedVisibleFrame().y,
    width: window.screen().flippedVisibleFrame().width,
    height: window.screen().flippedVisibleFrame().height
  });
});

Both projects aim to provide window management for macOS, but they differ in implementation and configuration approaches. Amethyst uses a more traditional tiling window manager style, while Phoenix offers a more flexible, script-based approach to window management.

ShiftIt

5,530

Managing windows size and position in OSX

Pros of ShiftIt

Simpler and more lightweight, focusing solely on window management
Offers more granular control over window positioning and sizing
Easier to set up and use for users who don't need full tiling functionality

Cons of ShiftIt

Less automated window management compared to Amethyst's tiling approach
Limited to manual window adjustments rather than automatic layout management
Lacks advanced features like multiple desktop layouts and space management

Code Comparison

Amethyst (Swift):

override func layoutScreens(_ screens: [NSScreen]) {
    for screen in screens {
        guard let layout = self.layoutsByScreenID[screen.screenID()] else {
            continue
        }
        layout.reflowScreen(screen)
    }
}

ShiftIt (Objective-C):

- (void)moveWindowRect:(NSRect)newFrame {
    [self.window setFrame:newFrame display:YES animate:YES];
    [self.window makeKeyAndOrderFront:self];
}

The code snippets highlight the different approaches:

Amethyst focuses on automatic layout management across multiple screens
ShiftIt provides direct control over individual window positioning

Both projects aim to improve window management on macOS, but Amethyst offers a more comprehensive tiling window manager solution, while ShiftIt provides simpler, manual window control for users who prefer direct manipulation.

Rectangle

25,585

Move and resize windows on macOS with keyboard shortcuts and snap areas

Pros of Rectangle

Simpler and more lightweight, focusing primarily on window management
Offers a more intuitive user interface for beginners
Provides customizable keyboard shortcuts for each window action

Cons of Rectangle

Lacks advanced tiling window management features
Does not support automatic window layouts or workspace management
Limited in terms of advanced customization options

Code Comparison

Rectangle (Swift):

func moveWindowToCenter() {
    if let screen = NSScreen.main {
        let visibleFrame = screen.visibleFrame
        let newFrame = NSRect(x: visibleFrame.midX - frame.width / 2,
                              y: visibleFrame.midY - frame.height / 2,
                              width: frame.width,
                              height: frame.height)
        setFrame(newFrame, display: true)
    }
}

Amethyst (Swift):

func layoutWindows(_ windows: [SIWindow], on screen: NSScreen) {
    let frameAssignments = layout.frameAssignments(windows, on: screen)
    for (window, assignment) in zip(windows, frameAssignments) {
        window.setFrame(assignment.frame, withThreshold: 0)
    }
}

Both projects aim to improve window management on macOS, but they take different approaches. Rectangle focuses on simple, user-friendly window actions, while Amethyst provides more advanced tiling window management features. The code comparison shows that Rectangle deals with individual window actions, whereas Amethyst handles layout assignments for multiple windows simultaneously.

Convert designs to code with AI

Introducing Visual Copilot: A new AI model to turn Figma designs to high quality code using your components.

Try Visual Copilot

README

Amethyst

Tiling window manager for macOS along the lines of xmonad.

Windows

If you want to learn more about tiling window managers and the features of Amethyst there are some great community resources on YouTube.

Boost your MacOS PRODUCTIVITY with Amethyst | Tiling Window Manager

Getting Amethyst

Amethyst is available for direct download on the releases page or using homebrew cask.

brew install --cask amethyst

Note: that Amethyst now is only supported on macOS 10.15+.

Using Amethyst

Amethyst must be given permissions to use the accessibility APIs in the Privacy & Security tab, Privacy -> Accessibilty.

Give Accessibility permission to Amethyst under Privicay and Security.

Important note: You will probably want to disable Automatically rearrange Spaces based on most recent use (found under Mission Control in System Preferences). This setting is enabled by default, and will cause your Spaces to swap places based on use. This makes keyboard navigation between Spaces unpredictable.

Troubleshooting

See Troubleshooting for some common issues.

Configuration

Keyboard Shortcuts

Amethyst uses two modifier combinations (mod1 and mod2) and can optionally use another two (mod3 and mod4).

Default Shortcut	Description
`mod1`	`option + shift`
`mod2`	`ctrl + option + shift`
`mod3`	not defined by default
`mod4`	not defined by default

And defines the following commands, mostly a mapping to xmonad key combinations.

Default Shortcut	Description
`mod1 + space`	Cycle layout forward
`mod2 + space`	Cycle layout backwards
`mod1 + h`	Shrink the main pane
`mod1 + l`	Expand the main pane
`mod1 + ,`	Increase main pane count
`mod1 + .`	Decrease main pane count
`mod1 + j`	Move focus counter clockwise
`mod1 + k`	Move focus clockwise
`mod1 + p`	Move focus to counter clockwise screen
`mod1 + n`	Move focus to clockwise screen
`mod2 + h`	Swap focused window to counter clockwise screen
`mod2 + l`	Swap focused window to clockwise screen
`mod2 + j`	Swap focused window counter clockwise
`mod2 + k`	Swap focused window clockwise
`mod1 + enter`	Swap focused window with main window
`mod1 + z`	Force windows to be reevaluated
`mod2 + z`	Relaunch Amethyst
`mod2 + left`	Throw focused window to space left
`mod2 + right`	Throw focused window to space right
`mod2 + 1`	Throw focused window to space 1
`mod2 + 2`	Throw focused window to space 2
`mod2 + 3`	Throw focused window to space 3
`mod2 + 4`	Throw focused window to space 4
`mod2 + 5`	Throw focused window to space 5
`mod2 + 6`	Throw focused window to space 6
`mod2 + 7`	Throw focused window to space 7
`mod2 + 8`	Throw focused window to space 8
`mod2 + 9`	Throw focused window to space 9
`mod2 + 0`	Throw focused window to space 10
`none`	Throw focused window to space 11
`none`	Throw focused window to space 12
`mod1 + w`	Focus Screen 1
`mod2 + w`	Throw focused window to screen 1
`mod1 + e`	Focus Screen 2
`mod2 + e`	Throw focused window to screen 2
`mod1 + r`	Focus Screen 3
`mod2 + r`	Throw focused window to screen 3
`mod1 + q`	Focus Screen 4
`mod2 + q`	Throw focused window to screen 4
`mod1 + g`	Focus Screen 5
`mod2 + g`	Throw focused window to screen 5
`mod1 + t`	Toggle float for focused window
`mod1 + i`	Display current layout
`mod2 + t`	Toggle global tiling
`mod1 + a`	Select tall layout
`none`	Select tall-right layout
`mod1 + s`	Select wide layout
`none`	Select middle-wide layout
`mod1 + d`	Select fullscreen layout
`mod1 + f`	Select column layout
`none`	Select row layout
`none`	Select floating layout
`none`	Select widescreen-tall layout
`none`	Select bsp layout

Available Layouts

Amethyst allows you to cycle among several different window layouts. Layouts can also be enabled/disabled to control whether they appear in the cycle sequence at all.

Tall

The default layout. This gives you one "main pane" on the left, and one other pane on the right. By default, one window is placed in the main pane (extending the full height of the screen), and all remaining windows are placed in the other pane. If either pane has more than one window, that pane will be evenly split into rows, to show them all. You can use the keyboard shortcuts above to control which window(s), and how many, are in the main pane, as well as the horizontal size of the main pane vs. the other pane.

Tall-Right

Exactly the same as Tall, but the main pane is on the right, with the other pane on the left.

Wide

The rotated version of Tall, where the main pane is on the top (extending the full width of the screen), and the other pane is on the bottom. If either pane has more than one window, that pane will split into columns instead of rows.

Two Pane

This layout has two visible panes - the main and the secondary pane. The window in the main pane is pinned, just like in other layouts, and all the remaining windows are placed in the other pane with only one window being visible at a time, which can be swapped (using the keyboard shortcuts). This layout automatically adapts to horizontal/vertical tiling depending on your screen orientation. The main pane is on the left in the horizontal orientation and it's on the top in the vertical orientation.

3Column-Left

A three-column version of Tall, with one main pane on the left (extending the full height of the screen) and two other panes, one in the middle and one on the right. Like Tall, if any pane has more than one window, that pane will be split into rows. You can control how many windows are in the main pane as usual; other windows will be assigned as evenly as possible between the other two panes.

3Column-Middle

Exactly like 3Column-Left, but the main pane is in the middle, with the other panes on either side. (In previous versions of Amethyst, this layout was known as Middle-Wide.)

3Column-Right

Exactly like 3Column-Left, but the main pane is on the right, with the other panes in the middle and on the left.

Widescreen-Tall

This mode is like Tall, but if there are multiple windows in the main pane, the main pane splits into columns rather than rows. The other pane still splits windows into rows, like Tall. This layout gets its name because it probably makes the most sense on very wide screens, with a large main pane consisting of several columns, and all remaining windows stacked into the final column. Other layouts that work well on very wide screens include any that allow for more than two columns (to take advantage of the screen width), such as any of the 3Column-* layouts, or Column.

Fullscreen

In this layout, the currently focused window takes up the entire screen, and the other windows are not visible at all. You can rotate between each of the windows using the "focus the next window" shortcut, as usual.

Column

This layout has one column per window, with each window extending the full height of the screen. The farthest-left window is considered the "main" window in the sense that you can change its size with the "shrink/expand the main pane" shortcuts; the other windows split the remaining space evenly.

Row

The rotated version of Column, where each window takes up an entire row, extending the full width of the screen.

Floating

This mode makes all windows "floating", allowing you to move and resize them as if Amethyst were temporarily deactivated. Unlike the other modes, this will mean that windows can be placed "on top of" each other, obscuring your view of some windows.

Binary Space Partitioning (BSP)

This layout does not have a main pane in the way that other layouts do. When adding windows, any given pane can be split evenly into two panes along whatever axis is longer. This is recursive such that pane A can be split in the middle into pane A on the left and pane B on the right; pane B can then be split into pane B on top and pane C on bottom; pane C can then be split into pane C on the left and pane D on the right; and so on.

Custom (beta)

Custom layouts can be implemented via JavaScript. See Custom Layouts.

Configuration File

Amethyst supports configuration via YAML in the home directory. See Configuration Files.

Contact

If you have questions or feedback your best options are to tweet or to get on gitter.

Contributing

If you'd like to contribute please branch off of the development branch and open pull requests against it rather than master. Otherwise just try to stick to the general style of the code.

Donating

Amethyst is free and always will be. That said, a couple of people have expressed their desire to donate money in appreciation. Given the current political climate I would recommend donating to one of these organizations instead:

And a bunch of technology-oriented ones:

Top Related Projects

Convert designs to code with AI

Introducing Visual Copilot: A new AI model to turn Figma designs to high quality code using your components.

Try Visual Copilot