Configuration Files

Amethyst will pick up a config file located at ~/.amethyst.yml or ~/.config/amethyst/amethyst.yml in this order. A sample can be found at /.amethyst.sample.yml

Configuration Keys

Key	Description
`layouts`	Ordered list of layouts to use by layout key (default tall, wide, fullscreen, and column).
`mod1`	First mod (default option + shift).
`mod2`	Second mod (default option + shift + control).
`mod3`	Third mod (not used by default).
`mod4`	Fourth mod (not used by default).
`window-max-count`	The max number of windows that may be visible on a screen at one time before additional windows are minimized. A value of 0 disables the feature.
`window-margins`	Boolean flag for whether or not to add margins between and around windows (default `false`).
`smart-window-margins`	Boolean flag for whether or not to set window margins if there is only one window on the screen, assuming window margins are enabled (default `false`).
`window-margin-size`	The size of the margins between and around windows (in px, default `0`).
`window-minimum-height`	The smallest height that a window can be sized to regardless of its layout frame (in px, default `0`).
`window-minimum-width`	The smallest width that a window can be sized to regardless of its layout frame (in px, default `0`)
`floating`	List of bundle identifiers for applications to either be automatically floating or automatically tiled based on `floating-is-blacklist` (default `[]`).
`floating-is-blacklist`	Boolean flag determining behavior of the `floating` list. `true` if the applications should be floating and all others tiled. `false` if the applications should be tiled and all others floating (default `true`).
`ignore-menu-bar`	`true` if screen frames should exclude the status bar. `false` if the screen frames should include the status bar (default `false`).
`float-small-windows`	`true` if windows smaller than the `small-window-size` threshold should be floating by default (default `true`).
`small-window-size`	Pixel threshold for `float-small-windows`. Windows with both width and height below this value are considered small (in px, default `500`).
`mouse-follows-focus`	`true` if the mouse should move position to the center of a window when it becomes focused (default `false`). Note that this is largely incompatible with `focus-follows-mouse`.
`focus-follows-mouse`	`true` if the windows underneath the mouse should become focused as the mouse moves (default `false`). Note that this is largely incompatible with `mouse-follows-focus`
`mouse-swaps-windows`	`true` if dragging and dropping windows on to each other should swap their positions (default `false`).
`mouse-resizes-windows`	`true` if changing the frame of a window with the mouse should update the layout to accommodate the change (default `false`). Note that not all layouts will be able to respond to the change.
`enables-layout-hud`	`true` to display the name of the layout when a new layout is selected (default `true`).
`enables-layout-hud-on-space-change`	`true` to display the name of the layout when moving to a new space (default `true`).
`enables-window-count-hud`	`true` to display notifications when window max count changes (default `false`).
`use-canary-build`	`true` to get updates to beta versions of the software (default `false`).
`new-windows-to-main`	`true` to insert new windows into the first position and `false` to insert new windows into the last position (default `false`).
`follow-space-thrown-windows`	`true` to automatically move to a space when throwing a window to it (default `true`).
`window-resize-step`	The integer percentage of the screen dimension to increment and decrement main pane ratios by (default `5`).
`screen-padding-left`	Padding to apply between windows and the left edge of the screen (in px, default `0`).
`screen-padding-right`	Padding to apply between windows and the right edge of the screen (in px, default `0`).
`screen-padding-top`	Padding to apply between windows and the top edge of the screen (in px, default `0`).
`screen-padding-bottom`	Padding to apply between windows and the bottom edge of the screen (in px, default `0`).
`restore-layouts-on-launch`	`true` to maintain layout state across application executions (default `true`).
`debug-layout-info`	`true` to display some optional debug information in the layout HUD (default `false`).
`disable-padding-on-builtin-display`	`true` to disable screen padding on in-built display (default `false`).
`hide-menu-bar-icon`	`true` to hide the menu bar icon (default `false`).

Commands

Commands are defined at the root of the config file, as either an object with mod and key values to customize the command or is false to entirely disable it.

Key	Description
`mod`	The modifier to use, either `mod1`, `mod2`, `mod3` or `mod4`.
`key`	The key on the keyboard to use.

Mods

A mod is a list of keyboard modifiers. Namely, option, control, shift, and command.

Command Keys

Command	Description
`cycle-layout`	Move to the next layout in the list.
`cycle-layout-backward`	Move to the previous layout in the list.
`shrink-main`	Shrink the main pane by a percentage of the screen dimension as defined by `window-resize-step`. Note that not all layouts respond to this command.
`expand-main`	Expand the main pane by a percentage of the screen dimension as defined by `window-resize-step`. Note that not all layouts respond to this command.
`increase-main`	Increase the number of windows in the main pane. Note that not all layouts respond to this command.
`decrease-main`	Decrease the number of windows in the main pane. Note that not all layouts respond to this command.
`increase-window-max-count`	Increase the maximum number of windows allowed on screen before additional windows are minimized.
`decrease-window-max-count`	Decrease the maximum number of windows allowed on screen before additional windows are minimized.
`command1`	General purpose command for custom layouts. Functionality is layout-dependent.
`command2`	General purpose command for custom layouts. Functionality is layout-dependent.
`command3`	General purpose command for custom layouts. Functionality is layout-dependent.
`command4`	General purpose command for custom layouts. Functionality is layout-dependent.
`focus-ccw`	Focus the next window in the list going counter-clockwise.
`focus-cw`	Focus the next window in the list going clockwise.
`focus-main`	Focus the main window in the list.
`focus-screen-ccw`	Focus the next screen in the list going counter-clockwise.
`focus-screen-cw`	Focus the next screen in the list going clockwise.
`swap-screen-ccw`	Move the currently focused window onto the next screen in the list going counter-clockwise.
`swap-screen-cw`	Move the currently focused window onto the next screen in the list going clockwise.
`swap-ccw`	Swap the position of the currently focused window with the next window in the list going counter-clockwise.
`swap-cw`	Swap the position of the currently focused window with the next window in the list going clockwise.
`swap-main`	Swap the position of the currently focused window with the main window in the list.
`focus-screen-n`	Move focus to the n-th screen in the list; e.g., `focus-screen-3` will move mouse focus to the 3rd screen. Note that the main window in the given screen will be focused.
`throw-screen-n`	Move the currently focused window to the n-th screen; e.g., `throw-screen-3` will move the window to the 3rd screen.
`throw-space-n`	Move the currently focused window to the n-th space; e.g., `throw-space-3` will move the window to the 3rd space.
`throw-space-left`	Move the currently focused window to the space to the left.
`throw-space-right`	Move currently the focused window to the space to the right.
`toggle-float`	Toggle the floating state of the currently focused window; i.e., if it was floating make it tiled and if it was tiled make it floating.
`display-current-layout`	Display the layout HUD with the current layout on each screen.
`toggle-tiling`	Turn on or off tiling entirely.
`enable-tiling`	Turn on tiling.
`disable-tiling`	Turn off tiling.
`reevaluate-windows`	Rerun the current layout's algorithm.
`toggle-focus-follows-mouse`	Turn on or off `focus-follows-mouse`.
`relaunch-amethyst`	Automatically quit and reopen Amethyst.

Layout Selection

Amethyst supports defining shortcuts for selecting specific layouts directly. They take the form of select-${layout_key}-layout. For example, defining the command select-tall-layout will define a shortcut that when used will switch directly to the Tall layout. Note, this works for custom layouts as well.