FAQ
Answers to common questions about setting up Zonal, using it, and fixing the few things that can go wrong.
Getting started
Which versions of macOS does Zonal support?
Zonal needs macOS 15 or later (Sequoia).
Does Zonal need any permissions?
Zonal needs one: Accessibility. It does not ask for Input Monitoring or Screen Recording. If you use the Rail for agent sessions, macOS also asks once per terminal app whether Zonal may control it (Automation), so Zonal can find the window that runs a session.
macOS does not let an app move another app's windows unless you allow it in Privacy & Security > Accessibility. Zonal uses that access to move and resize windows when you Snap them. It does not record your screen or read what you type.
Is Zonal on the Mac App Store?
No. You download Zonal from this site. The app is signed with a Developer ID and notarized by Apple.
Using Zonal
Can each display have its own Layout?
Yes. Each display has its own Layout, and Zonal remembers it. If you unplug a display and connect it again, it gets its Layout back. Choose a display's Layout from the Zonal menu-bar menu.
Does the Layout change when I switch Spaces?
No. A display keeps the same Layout on every Space.
Can I change the keyboard shortcuts?
Yes. Open Settings > Hotkeys from the Zonal menu and record a new combination for any action. You can also clear a shortcut. The shortcut works at once, without a restart.
A shortcut needs ⌃ or ⌘ among its modifiers, and it can't match another Zonal shortcut. The Hyper preset switches all four actions to ⌃⌥⇧⌘ plus the same keys.
To change the key you hold while dragging, open Settings > General. You can choose ⇧, ⌥ or ⌘, or turn on Always show Zones and hold the key to hide them.
How do I cancel a Snap while I'm dragging?
Press esc, or release the ⇧ key (or the key you chose in Settings) before you let go of the mouse button. The Zones disappear and the window stays where you drop it.
Which Layout should I use?
Start from the display's shape and what you do on it: 2 Columns on a laptop, Priority Grid on an ultrawide (main window in the center), 3 Columns on a 27-inch or 4K display, 2 Rows on a portrait display. The guide has a Layout for each way of working, including one for coding agents.
Holding a key while dragging is awkward on my trackpad. Is there another way?
Yes: hold ⌘ and rest the pointer on the window's green button. The Zone picker opens; click a Zone and the window Snaps there, with no drag. You can also use the shortcuts, or turn on Always show Zones in Settings > General so a plain drag shows the Zones.
I want one window wider for a while. Do I need a new Layout?
No. Drag the edge between two Snapped windows: the neighbour follows, and the Layout stays as it was, so the next Snap returns to it. Or span the window across two Zones by adding ⌃ while you drag.
What is the Rail, and do I need it?
The Rail is for people who run coding agents such as Claude Code in several terminal windows. It is a Zone where the windows of sessions that are working wait at a smaller size; a session that needs you comes back to its Zone by itself. If you don't run agents, you can ignore it: nothing happens until you mark a Zone as the Rail and connect Claude Code. See Agent sessions and the Rail.
Does the Rail read my terminal or my Claude Code conversations?
No. Claude Code's hooks tell Zonal only that a session is busy or waiting, with the session's ID, terminal and working folder, so Zonal can find its window. Zonal never reads what your terminal shows, what you type or what the agent writes, and nothing leaves your Mac. Details are in the privacy policy.
Does the Rail work with agents other than Claude Code?
Yes, if they can run a command when they start and stop working. Zonal listens for zonal://busy and zonal://waiting URLs, which any tool or script can open. The guide shows the URL format and an example.
Does Zonal conflict with Rectangle, Magnet or other window managers?
It can, if both apps use the same shortcut. When one is running, Zonal shows a warning in Settings > Hotkeys and in the welcome window. Zonal's defaults, ⌃⌥⇧ plus a key, avoid the usual defaults of Rectangle and Magnet.
If a shortcut does overlap, record a different one in Settings > Hotkeys, or choose the Hyper preset. Dragging with ⇧ held does not use any of these shortcuts.
Troubleshooting
Nothing happens when I Shift-drag a window.
Check these in order:
- Open the Zonal menu. If it says Accessibility access needed, choose Grant Accessibility Access… and turn Zonal on.
- Check your Trial or License in Settings > License. When the Trial ends and there is no License, Snapping and shortcuts stop. The Layout editor still opens.
- Drag the window by its title bar. Zones don't appear when you resize a window or select text.
- Check the window type. Zonal does not move dialogs, sheets, panels, palettes or windows in native full screen.
- Check the activation key in Settings > General. If you changed it, hold that key instead of ⇧.
I allowed Accessibility, but Zonal says it's missing.
This can happen when the Accessibility list holds an outdated entry for Zonal, for example after you replaced the app with another copy. macOS ties the permission to the app's signature. Zonal notices within a few seconds, shows a warning triangle on its menu-bar icon and opens the Accessibility step.
- Open System Settings > Privacy & Security > Accessibility.
- Select Zonal in the list and click the minus button (−) to remove it.
- Choose Open Settings in the welcome window (Zonal menu > Welcome…), or Grant Accessibility Access… in the Zonal menu, and turn Zonal on again.
Zonal picks up the change on its own. You don't need to restart it.
A window doesn't fill the Zone.
Some windows have a minimum or fixed size, and an app can refuse a size that is smaller than its minimum. When that happens, Zonal centers the window in the Zone and keeps it fully on screen. For example, System Settings has a fixed width, so it fills the height of a Zone and is centered across its width.
A window larger than the display is lined up with the left and top edges of the visible area, so its title bar stays reachable. Choose a larger Zone, or a Layout with wider Zones, if you want the window to fill it.
Terminal windows are a little smaller or larger than the Zone.
Terminal sizes its windows in whole character cells, so it can't match a Zone to the pixel. In testing, a Snapped Terminal window differed from its Zone by a few points. Zonal centers the window on the Zone, so the leftover space is split evenly.
Preview doesn't move when I drag its title.
In the middle of Preview's title bar is the document's proxy icon. Dragging it drags the file, not the window. Drag the title bar somewhere else, for example near the left or right edge, with ⇧ held.
How does Zonal work with Stage Manager?
When Stage Manager is on and its strip of recent apps is visible, Zonal leaves room for the strip, so no Zone sits under it. When the strip is hidden, Zones use the full screen. Turning Stage Manager on or off takes effect on your next drag or shortcut.
You can Shift-drag a window out of the strip and Snap it.
macOS tiles my window when I drag it to a screen edge.
macOS can tile a window when you drag it to an edge, and Zonal can react to the same drag. While Zonal's Zones are showing, Zonal wins: it Snaps the window when you release, over any macOS tile. You may see macOS's preview flash for a moment.
If you'd rather not see it, turn on Turn off macOS tiling while Zonal runs in Settings > General. Zonal puts your macOS setting back when you turn it off or quit Zonal. You can also turn off edge tiling yourself in System Settings > Desktop & Dock: Settings > General shows a note with an Open Desktop & Dock button when edge tiling is on.
My agent's window does not move to the Rail.
Zonal moves a session's window only when Claude Code is connected and Move Busy agent windows to the Rail is on in Settings > General, the window is Snapped, its display's Layout has a Rail, and the session has been Busy for 20 seconds. The terminal must be Terminal, iTerm2 or Ghostty 1.3 or later, and Zonal must be allowed to control it in System Settings > Privacy & Security > Automation; Settings > General says so when it is not.
If a window stays in the Rail after you interrupt Claude Code with esc, click it: Claude Code sends no signal on an interrupt. See Agent sessions and the Rail.
Updates and uninstalling
How do updates work?
Zonal checks for updates once a day and asks before it installs one. To check yourself, choose Check for Updates… in the Zonal menu, or Check now in Settings > Updates.
In Settings > Updates you can turn on Automatically download and install updates, which is off by default, and Include beta versions. All 1.x updates are free.
How do I uninstall Zonal completely?
If you're moving your License to another Mac, open Settings > License and choose Deactivate this Mac first. That frees one of your three Activations.
- In System Settings > General > Login Items, turn Zonal off, or untick Start Zonal at login in Zonal's Settings > General.
- If you connected Claude Code, click Disconnect Claude Code in Zonal's Settings > General, so your sessions stop calling Zonal's hook.
- Choose Quit in the Zonal menu.
- Drag Zonal from the Applications folder to the Trash.
That removes the app. Zonal also keeps a few small files. To remove them, delete the folder that holds your Layouts and License records, and the preferences file:
~/Library/Application Support/Zonal ~/Library/Preferences/org.anteras.Zonal.plist
Then, in Keychain Access, delete the two items named org.anteras.Zonal.trial and org.anteras.Zonal.license.
Contact
Write to zonal@anteras.org. Please include your macOS version and your Zonal version (choose About Zonal in the Zonal menu), and describe what you did and what happened.