Install Frame
Frame requires macOS 13 Ventura or later. It includes a menu bar app that manages your windows and a frame command-line client for commands and scripts.
With Homebrew
If Homebrew is installed, run these commands in Terminal:
brew tap tvr-works/tap
brew install --cask tvr-works/tap/frameFrom a release
You can also download the latest release. Extract the archive and move Frame.app into Applications. The archive also includes the frame client; Homebrew makes the client available in Terminal automatically.
First launch
- Open Frame from Applications. The app runs in the menu bar.
- When prompted, open System Settings → Privacy & Security → Accessibility and enable Frame. This permission lets it move and resize other apps’ windows.
- Open a few ordinary app windows. Frame tiles them using its built-in defaults; you do not need a configuration file to begin.
Try the basic pattern
Hold Option and press H, J, K or L to move focus left, down, up or right. Keep Option and add Shift to move the window instead. Add Control as well to resize. Press one direction key at a time.
The shortcuts are handled by the native menu bar app. You do not need to keep Terminal open.
Windows, columns and rows
A workspace contains columns arranged side by side. Each column contains one or more windows stacked as rows. Windows share the available width and height, with gaps between them.

The first window fills an empty workspace. On a landscape display, the next tiled window creates a column to the right when there is only one column. With multiple columns, new windows join the bottom of the focused column. On portrait or square displays, new windows stack in the focused column.
Focus changes the active window
H and L focus an adjacent column’s most recently focused window. J and K focus the window below or above within the current column. Focus stops at the workspace edge.
Move changes a window’s place
Moving left or right sends the window into the adjacent column. At an outer edge, the move creates a column. Moving up or down reorders windows within the same column; it stops at the top or bottom. Empty columns disappear.
Resize changes the shared space
H and L adjust column width. J and K adjust a window’s height within its column. Neighboring columns or rows share the remaining space. A column or row needs a sibling to resize against; a single window filling the workspace has no internal boundary to push.
Keyboard shortcuts
These are the built-in defaults. H means left, J down, K up and L right. Slash-separated direction keys are alternatives. For workspaces, choose a number key from 1 through 9, or 0.
| Action | Shortcut | Result |
|---|---|---|
| Focus | Option + H / J / K / L | Move focus left, down, up or right without moving the window. |
| Move | Option + Shift + H / J / K / L | Move the focused window between columns or reorder it within its column. |
| Resize a column | Option + Shift + Control + H / L | Change the focused column’s width in 50-point steps. |
| Resize a row | Option + Shift + Control + J / K | Change the focused window’s height within its column in 50-point steps. |
| Switch workspace | Option + 1–0 | Show the workspace assigned to that number. |
| Send to workspace | Option + Shift + 1–0 | Send the focused window to that workspace. Focus stays in the source workspace by default. |
| Fullscreen | Option + F | Toggle fullscreen for the focused window. |
- Focus
Option + H / J / K / L - Move focus left, down, up or right without moving the window.
- Move
Option + Shift + H / J / K / L - Move the focused window between columns or reorder it within its column.
- Resize a column
Option + Shift + Control + H / L - Change the focused column’s width in 50-point steps.
- Resize a row
Option + Shift + Control + J / K - Change the focused window’s height within its column in 50-point steps.
- Switch workspace
Option + 1–0 - Show the workspace assigned to that number.
- Send to workspace
Option + Shift + 1–0 - Send the focused window to that workspace. Focus stays in the source workspace by default.
- Fullscreen
Option + F - Toggle fullscreen for the focused window.
Workspaces and displays
Option plus a number switches to that workspace. Option plus Shift and a number sends the focused window there. By default, sending a window keeps focus in the source workspace; switch to the destination to follow it.
On one display, all workspaces use that display. With multiple displays, workspaces remember their display. Workspace numbers do not imply a left or right monitor.
The website demo uses a fixed arrangement: 1–5 on the left display and 6–0 on the right. It also follows a window when sending it. Those are demo choices, not Frame’s native defaults.
Assign workspaces to a display
Add a [workspace-to-monitor-force-assignment] table to your configuration to pin workspaces. For example:
[workspace-to-monitor-force-assignment]
1 = "main"
2 = "secondary"main is the macOS primary display, which may be on either side. secondary means the other display in a two-display setup. You can also use numeric monitor order or a monitor-name pattern. See the full display configuration examples.
Configuration
Frame works without a custom file. Once you add one, it replaces the built-in configuration rather than merging with it. Start from the bundled defaults so shortcuts, workspace names and gaps stay intact.
cp -n /Applications/Frame.app/Contents/Resources/default-config.toml ~/.frame.tomlThe command leaves an existing file intact. Edit that file if it already exists. You can also read the complete default configuration.
File location and validation
The usual location is ~/.frame.toml. Frame also checks $XDG_CONFIG_HOME/frame/.frame.toml, or ~/.config/frame/.frame.toml when XDG_CONFIG_HOME is unset. Keep only one of those files: finding both is an ambiguity error, not a precedence rule. An explicit --config-path passed to the app selects that file instead.
The app’s startup flag is separate from the client API. Quit Frame before launching the installed app executable with an explicit configuration path, for example /Applications/Frame.app/Contents/MacOS/Frame --config-path /absolute/path/to/frame.toml. The file must exist.
frame doctor
frame reload-configValidate edits with frame doctor, fix any errors, then reload. Unknown keys, wrong value types, invalid patterns and duplicate bindings are errors. Put top-level settings before the first TOML table heading; edit existing tables instead of declaring a second copy of the same table.
Configuration reference
start-at-login- Boolean. Starts Frame at login; the bundled default is false.
persistent-workspaces- An array of workspace names that remain addressable when empty. The bundled defaults keep 1–9 and 0.
workspace-change-hook- An executable-and-arguments array run when focused workspace changes. See Scripting and integrations.
[binding]- Key combinations mapped to one Frame command or an ordered array of commands.
[key-mapping]- A qwerty, dvorak or colemak preset and optional custom key-notation mappings.
[gaps]- Inner and outer spacing in points, either constant or selected by display.
[workspace-to-monitor-force-assignment]- Workspace-to-display rules, with optional ordered fallback selectors.
[[window-classification-override]]- Ordered rules that choose tiling or excluded placement for matching windows.
Startup and persistent workspaces
start-at-login = true
persistent-workspaces = ["1", "2", "3", "4", "5", "6", "7", "8", "9", "0"]Persistent workspaces stay available when empty. This is useful for fixed shortcuts, relative workspace navigation and status-bar indicators. Persistence does not assign a display; use display rules for that.
Bindings and command composition
In the existing [binding] table, the modifier names are alt (Option), shift, ctrl (Control) and cmd (Command). A binding takes a command string or an array of Frame commands run in order.
[binding]
alt-h = "focus left"
alt-shift-2 = "move-node-to-workspace --focus-follows-window 2"
alt-b = ["balance-sizes", "focus left"]
ctrl-alt-d = "debug-window-events"These are entries to add or edit, not a complete bindings table. Keep every default binding you still want. The send example enables follow-focus for that shortcut; it is not the native send default.
Bindings accept focus, move, resize, workspace, move-node-to-workspace, focus-monitor, fullscreen, add-column, remove-column, balance-sizes, move-mouse, reload-config and debug-window-events. Query commands and arbitrary shell commands are not binding actions. Run the CLI from a script or launcher when you need shell logic.
Keyboard layout and custom notation
[key-mapping]
preset = "qwerty"
[key-mapping.key-notation-to-key-code]
mykey = "semicolon"Available presets are qwerty, dvorak and colemak. The optional notation table adds aliases for physical key codes. In this example, alt-mykey can be used in the bindings table. Alias names cannot contain whitespace or hyphens; mapped values must be recognized key-code names.
Gaps, including per-display values
[gaps]
inner.horizontal = 8
inner.vertical = 8
outer.left = 8
outer.right = 8
outer.bottom = 8
outer.top = [{ monitor."Built-in Retina Display" = 0 }, 32]Inner gaps separate windows; outer gaps separate the layout from the work-area edges. All six values accept a constant number of points or a per-display array. The example uses no top gap on a matching built-in display and 32 points elsewhere.
A per-display array contains one or more monitor rules followed by a numeric fallback. The first matching rule wins. Monitor selectors can be main, secondary, a one-based order, or a case-insensitive display-name regular expression.
Pin workspaces to displays
[workspace-to-monitor-force-assignment]
1 = "main"
2 = "secondary"
3 = [".*Studio.*", "main"]A value can be one selector or an ordered list. Frame uses the first matching display. The third rule prefers a display whose name matches Studio and falls back to the macOS primary display. Main does not mean left; use frame list-monitors to inspect names and one-based IDs.
See Accessibility and window rules for classification overrides, and Scripting and integrations for workspace hooks.
Accessibility and window rules
Frame uses Apple’s Accessibility API to discover other apps’ windows, observe changes, and request position and size updates. That is why it needs Accessibility permission. Apple’s accessibility model depends on the information and actions each app exposes.
Apps do not always report window roles, subroles, titles or controls consistently. A document, dialog and temporary panel can look similar in that information. Frame combines those signals with app-specific heuristics to decide which windows belong in the tiled layout.
Override a window’s classification
Add ordered [[window-classification-override]] rules to your configuration. A rule requires at least one matcher and a kind. All matchers in one rule must match; the first matching rule wins.
if.app-id- Exact app bundle ID. Find it with
frame list-apps --json. if.app-name-regex-substring- Case-insensitive regular expression matching part of the app name. Use anchors when you want the whole name.
if.window-title-regex-substring- Case-insensitive regular expression matching part of the window title.
kind = "tiling"- Include the matching window in the tiled workspace layout.
kind = "excluded"- Keep it outside tiled workspace management. Excluded windows are not workspace-local tiles and can remain visible across workspace switches.
[[window-classification-override]]
if.app-id = "com.example.Player"
if.window-title-regex-substring = "picture[- ]in[- ]picture"
kind = "excluded"
[[window-classification-override]]
if.app-id = "com.example.Player"
if.window-title-regex-substring = "^Library$"
kind = "tiling"Replace the example bundle ID and titles with values from your app. Put specific rules before broader ones. Prefer a title-specific rule when only one kind of window needs correction, rather than forcing every dialog from an app into tiling.
Validate and reload the file, then reopen the affected window if needed. An override changes Frame’s placement decision; it cannot supply a missing Accessibility window or make an app accept position and size requests it does not support.
Inspect inconsistent window reports
Add ctrl-alt-d = "debug-window-events" to the existing bindings table. Focus the affected app, press that shortcut, reproduce the behavior, then press it again to stop. Frame reports the log path; its default is /tmp/frame-window-events.log. The log includes window titles, observed events and classification signals.
Command-line API
The CLI exposes Frame’s window actions and state queries to shell scripts, launchers and other apps. Use it to automate layouts, select a specific window, or build a display/workspace indicator. The menu bar app performs the window management; the client sends requests to it.
Run frame <command> [arguments] while the app is running. Every command accepts -h or --help. Global frame --help and frame --version also work without the app. Arguments shown in angle brackets below are placeholders to replace.
Targets, output and exit status
Actions use the focused window or workspace unless a target is supplied. Supported --window-id or --workspace flags take precedence over the environment. For target-aware commands, FRAME_WINDOW_ID is checked next, then FRAME_WORKSPACE, then current focus.
Use Frame IDs such as frame-123 from list-windows, not macOS window numbers. IDs are session-specific; query them rather than hard-coding them across app restarts.
Query commands print text by default. --json returns a JSON array; --count prints a number. They are mutually exclusive. A zero exit status means success, and nonzero means failure. Some no-op actions can print an explanation to stderr while still succeeding; use --fail-if-noop where offered when that distinction matters to a script.
Query apps, windows and displays
list-apps
List applications registered with Frame. Use the bundle IDs in this output when writing classification rules.
frame list-apps [--macos-native-hidden [no]] [--count | --json]- --macos-native-hidden selects apps hidden by macOS; add no to select apps that are not hidden. Omit the flag for both.
- --json returns objects with app-pid, app-bundle-id and app-name. --count returns a number. These output flags cannot be combined.
frame list-apps --jsonlist-monitors
List displays and their one-based Frame monitor IDs.
frame list-monitors [--focused [no]] [--mouse [no]] [--count | --json]- --focused filters by the display containing the focused workspace. --mouse filters by the display containing the pointer. Each accepts no to invert its filter.
- --json returns monitor-id and monitor-name. --count returns the number of matches; it cannot be combined with --json.
frame list-monitors --json
frame list-monitors --focusedlist-workspaces
List Frame workspaces on the selected display or displays. A monitor selection is required.
frame list-workspaces --monitor <monitor>... [--visible [no]] [--empty [no]] [--count | --json]- A monitor is a one-based ID, focused, mouse or all. Supply multiple selectors after --monitor to combine displays.
- --visible selects workspaces currently shown; --empty selects workspaces without windows. Add no to either flag to invert that filter.
- --json returns objects with a workspace name. --count returns a number; it cannot be combined with --json.
frame list-workspaces --monitor all --json
frame list-workspaces --monitor focused --visible
frame list-workspaces --monitor 1 2 --empty nolist-windows
List windows by workspace, display or the currently focused window. At least one of --workspace, --monitor or --focused is required.
frame list-windows --workspace <workspace>... [--monitor <monitor>...] [--pid <pid>] [--app-bundle-id <id>] [--count | --json]
frame list-windows --monitor <monitor>... [--workspace <workspace>...] [--pid <pid>] [--app-bundle-id <id>] [--count | --json]
frame list-windows --focused [--count | --json]- Workspace selectors are names, focused or visible. Monitor selectors are one-based IDs, focused, mouse or all. Multiple selectors within one flag are combined; workspace and monitor filters intersect.
- --pid and --app-bundle-id narrow a workspace/display query to an app. --focused cannot be combined with any other filtering flag.
- --json returns window-id, app-name and window-title. --count returns the number of matches; it cannot be combined with --json.
frame list-windows --workspace focused --json
frame list-windows --monitor all --app-bundle-id com.apple.Safari
frame list-windows --workspace 2 --count
frame list-windows --focused --jsonFocus and arrange windows
focus
Change focus without changing the layout, or focus a particular Frame window ID.
frame focus <left|down|up|right> [--wrap-around]
frame focus <left|down|up|right> [--boundaries <boundary>] [--boundaries-action <action>]
frame focus --window-id <id>- The default boundary is workspace and its default action is stop. Boundaries: workspace or all-monitors-outer-frame.
- Boundary actions: stop, fail, wrap-around-the-workspace or wrap-around-all-monitors. The last requires all-monitors-outer-frame.
- --wrap-around is shorthand for wrapping within the workspace. It cannot be combined with --boundaries or --boundaries-action.
- --window-id is a separate form and cannot be combined with direction or boundary options.
frame focus left
frame focus --wrap-around down
frame focus --window-id frame-123focus-monitor
Focus a display’s active workspace. Direction uses display arrangement; next and prev use Frame’s display order.
frame focus-monitor [--wrap-around] <left|down|up|right|next|prev>
frame focus-monitor <monitor-pattern>...- --wrap-around is available for directional and next/prev navigation, not monitor-pattern selection.
- Patterns accept main, secondary, a one-based number, or a case-insensitive regular expression matching a display name. Multiple patterns are tried in order.
frame focus-monitor right
frame focus-monitor --wrap-around next
frame focus-monitor mainmove
Move a tiled window into a neighboring column or reorder it within its column.
frame move <left|down|up|right> [--window-id <id>] [--boundaries <boundary>] [--boundaries-action <action>]- --window-id selects a window instead of the current target.
- --boundaries accepts workspace (default) or all-monitors-outer-frame. --boundaries-action accepts create-implicit-container (default), stop or fail.
- At a horizontal edge, create-implicit-container makes a column and requires --boundaries workspace. stop leaves the window in place; fail reports failure. These options do not turn move into a cross-display transfer.
- Vertical movement stops at the top or bottom of the column. Moving excluded, native-fullscreen, minimized or hidden-app windows is not supported.
frame move right
frame move left --boundaries-action stop
frame move down --window-id frame-123resize
Resize the target and share the difference among sibling columns or rows.
frame resize <width|height|smart|smart-opposite> <points|+points|-points> [--window-id <id>]- width adjusts column width; height adjusts the window’s row height. smart uses the nearest parent orientation; smart-opposite uses the other orientation.
- A plain number sets the target layout size. A signed number pushes its active boundary by that many points. For the last column or row the active boundary is the leading edge, so do not assume + always makes it larger.
- --window-id selects a Frame window. A resize needs a sibling to share space with.
frame resize width -50
frame resize height +50
frame resize width 800 --window-id frame-123fullscreen
Toggle Frame’s fullscreen overlay for a tiled window. This is a Frame layout state, separate from macOS’s native fullscreen Space.
frame fullscreen [on|off] [--window-id <id>] [--no-outer-gaps] [--fail-if-noop]- Omit on/off to toggle. Use an explicit state for scripts that must be repeatable.
- --no-outer-gaps removes outer gaps while enabling the overlay; it cannot be used with off.
- --fail-if-noop requires on or off and returns failure when the window is already in that state. --window-id selects a particular window.
frame fullscreen
frame fullscreen on --no-outer-gaps
frame fullscreen off --window-id frame-123add-column
Create a column immediately after the target window’s column and move that window into it.
frame add-column- There are no command-specific flags. This operates on the current target; it does not create a permanently empty column.
frame add-columnremove-column
Remove the last column in the target workspace, moving its windows into the column to its left. It does not close those windows.
frame remove-column- There are no command-specific flags. If only one column remains, the command leaves it in place. This removes the last column, not necessarily the focused column.
frame remove-columnbalance-sizes
Reset column and row weights to equal shares within their respective parents.
frame balance-sizes [--workspace <name>]- --workspace selects a named workspace. Without it, Frame uses the current target workspace.
frame balance-sizes
frame balance-sizes --workspace 2move-mouse
Place the pointer at the target window or display’s center.
frame move-mouse <window-lazy-center|window-force-center|monitor-lazy-center|monitor-force-center> [--fail-if-noop]- lazy-center leaves the pointer where it is if it is already inside the target. force-center always centers it.
- --fail-if-noop is available only for the two lazy-center targets.
frame move-mouse monitor-lazy-center
frame move-mouse window-force-centerSwitch and send between workspaces
workspace
Show a named workspace, or select the next/previous workspace on the target display.
frame workspace <name> [--fail-if-noop]
frame workspace <next|prev> [--wrap-around] [--stdin|--no-stdin]- Direct names select that workspace; --fail-if-noop fails if it is already focused.
- next/prev use the target display’s available workspaces in sorted order. --wrap-around cycles past the end.
- --stdin reads an explicit ordered list of workspace names, one per line. --no-stdin ignores piped input. These flags apply only to next/prev. Non-terminal input requires one of them; lists are limited to 1,000 lines.
frame workspace 2
frame workspace next --wrap-around --no-stdin
printf '1\n2\n3\n' | frame workspace next --stdin --wrap-aroundmove-node-to-workspace
Send a window to another workspace. By default, focus stays in the source workspace.
frame move-node-to-workspace <name> [--window-id <id>] [--focus-follows-window] [--fail-if-noop]
frame move-node-to-workspace <next|prev> [--focus-follows-window] [--wrap-around] [--stdin|--no-stdin]- --focus-follows-window activates the destination and keeps that window focused, matching the website demo.
- --window-id selects a window for a direct named destination; it cannot be combined with next/prev. --fail-if-noop is also limited to a named destination.
- For next/prev, --wrap-around and explicit --stdin/--no-stdin work like workspace. The relative destination is resolved from the source workspace.
frame move-node-to-workspace 2
frame move-node-to-workspace --focus-follows-window 2
frame move-node-to-workspace next --no-stdin --wrap-aroundConfiguration and diagnostics
reload-config
Read the configuration again and apply valid settings, including shortcuts and login behavior.
frame reload-config- There are no command-specific flags. The command reports configuration errors instead of applying an invalid file. Run doctor first to validate changes.
frame doctor && frame reload-configdoctor
Report the CLI/app versions and configuration health. A running app is needed to validate its configuration.
frame doctor- There are no command-specific flags. If the app is unavailable, doctor can still report the client version and the missing connection; it cannot validate the app’s configuration then.
- A nonzero exit status indicates a problem such as an unavailable app, a version mismatch or invalid configuration.
frame doctor
frame --versiondebug-window-events
Toggle window-event diagnostics for the frontmost app and report the logging state and file location.
frame debug-window-events- There are no command-specific flags. The default log is /tmp/frame-window-events.log and includes classification signals and window titles.
- To diagnose another app, bind this command to a shortcut, focus that app, then use the shortcut to start and stop logging. Running it from Terminal targets the frontmost app at that moment.
frame debug-window-eventsScripting and integrations
The CLI lets you connect Frame to your own tools instead of limiting window management to built-in shortcuts. A script can query state, choose an action, and update a status bar or launcher.
Query state for a script
frame list-workspaces --monitor focused --visible
frame list-windows --workspace 2 --count
frame list-windows --focused --jsonThe first command prints the visible workspace on the focused display. The second counts windows in workspace 2. The JSON window result contains window-id, app-name and window-title. A script can use the returned ID with commands that accept --window-id.
React to workspace changes
The top-level workspace-change-hook setting runs a process whenever focused workspace changes. Its first array element is the executable path and the rest are arguments. Use a shell explicitly when you need shell expansion.
workspace-change-hook = [
"/bin/sh",
"-c",
'sketchybar --trigger frame_workspace_change FOCUSED_WORKSPACE="$FRAME_FOCUSED_WORKSPACE"'
]Place this before TOML table headings. Frame supplies FRAME_FOCUSED_WORKSPACE, preserves inherited environment variables, and prepends /opt/homebrew/bin:/opt/homebrew/sbin to PATH. If SketchyBar is installed elsewhere and is not on that PATH, use its absolute executable path. Reload Frame after editing the hook.
Example: display/workspace labels in SketchyBar
With SketchyBar installed and running, add a custom event and an item to its configuration. Subscribe to Frame’s event so the label updates on workspace changes; display and wake events plus a periodic refresh keep it current as displays change.
sketchybar --add event frame_workspace_change
sketchybar --add item frame.workspace left \
--set frame.workspace \
script="$HOME/.config/sketchybar/plugins/frame-workspaces.sh" \
update_freq=30 \
--subscribe frame.workspace frame_workspace_change display_change system_wokeSave this script as ~/.config/sketchybar/plugins/frame-workspaces.sh and make it executable:
#!/bin/sh
# Called by SketchyBar; NAME is the item being updated.
label=""
for monitor in $(frame list-monitors 2>/dev/null | awk '{print $1}'); do
workspace=$(frame list-workspaces --monitor "$monitor" --visible 2>/dev/null | head -n 1)
[ -n "$workspace" ] || continue
[ -z "$label" ] || label="$label | "
label="${label}${monitor}: ${workspace}"
done
sketchybar --set "$NAME" label="${label:-none}"
chmod +x ~/.config/sketchybar/plugins/frame-workspaces.shThe script asks Frame for each display’s visible workspace and produces a label such as 1: 2 | 2: 7. SketchyBar provides NAME for the item to update. Reload SketchyBar after registering the item. These are Frame workspace names, not macOS Space IDs.
This example uses plain-text Frame queries and standard shell tools. Use --json when an integration needs structured fields instead. See the SketchyBar event documentation for custom events, subscriptions and trigger variables.
Troubleshooting
Windows are not moving
Check that Frame is running in the menu bar and enabled under System Settings → Privacy & Security → Accessibility. Test with an ordinary app window; dialogs and other excluded windows do not join the tiled layout.
A shortcut does not respond
Check for a conflicting shortcut in macOS or the active app. If you have a custom configuration, confirm the binding exists and run frame doctor. Apply corrections with frame reload-config.
The configuration has an error
Frame validates configuration keys, types and values. Run frame doctor to see the affected section and a CFG error code. On startup, an invalid file produces a configuration error and Frame falls back to its built-in defaults.
A sent window did not receive focus
Sending keeps focus in the source workspace by default. Press Option and the destination number to switch there. The website’s scripted demo intentionally follows sent windows.
The terminal cannot find frame
With a Homebrew installation, check that Homebrew is on your shell’s command path. If you installed the release archive manually, the standalone client also needs to be in a directory on your command path.
For windows that are consistently misclassified, use classification overrides and window diagnostics after checking Accessibility permission.
If the issue remains, open an issue with your macOS version, Frame version, the action you tried and any relevant error output.