Guided setup
The first time you open Layout, a guided setup takes you through seven steps. Nothing moves on your screen while you go through them: Layout only makes your projects’ workspaces at the last step, and only starts managing windows if you activate it there.
Go at your own pace. Continue moves to the next step, Back returns to the previous one, and you can click any step’s name at the top to jump to it. Layout saves where you are and the projects you chose, so if you quit in the middle, the setup reopens at the same step. The Accessibility permission isn’t saved with your progress: Layout asks macOS each time.
1. Welcome
Section titled “1. Welcome”What Layout does: a workspace per project, one shortcut between them, and agents that come to you when they finish or ask for you. The picture beside it is the Layout Overview, Layout’s own Mission Control: every project along the top, the selected one’s windows, and your agents on the side, one of them allowed in place. Like every picture of the setup, it uses sample projects, never yours. Once Layout is active, swipe up or press ⌃⌥O to open it. Click Set up my projects to start.
2. Accessibility
Section titled “2. Accessibility”Layout needs the Accessibility permission to move and resize your windows and to handle its shortcuts.
- Click Open settings. Layout asks macOS for the permission, and System Settings opens at Privacy & Security › Accessibility.
- Turn on Layout in the list. If it’s missing, click + and add Layout.app. Show Layout.app reveals the app in the Finder.
- Come back to Layout. The step checks the permission on its own; Check again checks it right away.
To continue without the permission, click Set up later. The step then stays unchecked, and the last step reminds you. See Accessibility permission.
3. Your projects
Section titled “3. Your projects”The projects you switch between, each of which becomes a workspace. The step lists the projects Claude, Codex and T3 Code know on your Mac, the most recent first, and the first time it checks the two latest. Each row shows what its workspace brings back when you switch to it: the editor and the terminal in the project’s folder, and the latest chat in Claude, Codex or T3 Code. The setup never shows your chats’ titles, and it opens none of your projects’ files: it only checks that their folders are still there, so a project in Documents, Desktop, Downloads or iCloud Drive doesn’t make macOS ask for access to that folder.
- Click a row to check it or leave it out. The workspaces get their ⌃⌥ numbers in the list’s order.
- Choose Folders… adds projects from anywhere on your Mac, several at once. When your agents list no project, the step offers only that.
- Opens in picks the editor and the terminal every project opens in. They start with the ones your Mac points to: the ones your workspaces use, the ones open now, or the only ones installed; otherwise none. Choose No editor or No terminal to leave one out. Your workspaces get what the pills show, even if you open or quit apps before you finish.
- A project that one of your workspaces opens already reads “In” and that workspace’s name, even when the workspace reaches its folder through a symbolic link or spells it with other capitals: the setup doesn’t make it twice.
Nothing is made yet: the workspaces appear when you finish the setup, each one as New Workspace from Project makes it, with the Stacked layout. A project named like one of your workspaces, or like another project you checked, gets its parent folder’s name too, such as “web (acme)”. Change their apps and layouts later in the editor.
4. Your agents
Section titled “4. Your agents”Connect adds Layout’s hooks to Claude Code’s, Codex’s or Cursor’s own file, as in Settings › Integrations. With them, an agent that finishes or asks for you in another project shows on a card, where you can Allow or Deny what it asks, and ⌃⌥N takes you to it. Each file keeps its previous version beside it, as .layout-backup.
An agent that never ran on your Mac reads “Not on this Mac yet”: connect it later in Settings › Integrations. Codex asks you to review the hooks once, the next time it starts. See Agents.
If you opened Layout from its disk image, or from the download without moving it, macOS runs a copy that goes away once you quit Layout or eject the disk image, and hooks pointing to it would stop working. The step then asks you to move Layout to Applications first, and connects nothing. Drag Layout to your Applications folder and open it from there: the setup picks up at this step.
5. Your shortcuts
Section titled “5. Your shortcuts”The step lists the keys to start with. If you change them later in Settings › Shortcuts, it shows yours:
| Action | Shortcut |
|---|---|
| Switch projects | ⌥Tab |
| See every project and agent | ⌃⌥O |
| Go to the agent that needs you | ⌃⌥N |
| Choose any agent session | ⌃⌥Tab |
| Go to project 1…9 | ⌃⌥1…9 |
It also shows the swipe between workspaces, with the number of fingers your Mac uses to swipe between desktops, and the swipe up that opens the Overview, unless they’re off in System Settings or in Settings › Shortcuts.
Replace ⌘ Tab makes ⌘Tab go through the recent windows of the current workspace instead of your apps. Your wildcard apps, if you have some, come last. It’s off by default. ⌥Tab works either way while Layout is active.
See Switchers and Keyboard shortcuts.
6. Menu bar
Section titled “6. Menu bar”Show the Layout bar turns the Layout bar on or off. It’s on by default. Below it, the step explains how to have macOS hide its own menu bar automatically, with a button, Open macOS Menu Bar settings, that opens System Settings for you. That change is optional, and you make it yourself. See Layout bar.
7. Ready to go
Section titled “7. Ready to go”The last step sums up your choices (your projects, the agents connected, the ⌘ Tab switcher and the Layout bar) and checks the three conditions Layout needs to activate:
| Check | Ready when it reads | Otherwise |
|---|---|---|
| Accessibility | Allowed | Permission needed |
| Displays | Connected display count | Connect a display |
| Window manager | No conflict detected with AeroSpace | Quit AeroSpace |
When all three pass, click Activate and launch: Layout makes your projects’ workspaces, starts managing windows, and launches each project, opening its editor, its terminal and its chat, then shows the first one. Turn off Launch them now to activate without opening anything; the button then reads Activate Layout. Explore while paused makes the workspaces and opens the editor without moving anything.
When a check fails, fix it: grant the permission, connect a display, or quit AeroSpace. The checks update on their own. Review permissions takes you back to the Accessibility step. You can still finish the setup with Explore while paused.
Layout checks these conditions again every time it activates, so passing them once isn’t enough if something changes later.
Explore while paused
Section titled “Explore while paused”Explore while paused closes the setup and opens the editor with Layout paused, with your projects’ workspaces in it. You can create workspaces, choose layouts, and assign apps, and your windows stay where they are.
While Layout is paused, a strip under the editor’s header reads “Layout is paused. Nothing moves until you resume it.” When you’re ready, click Resume Layout in the header, or choose Resume Layout from the Layout menu bar icon. If the permission is still missing, the header’s button reads Allow access instead, which reopens the setup at the Accessibility step.
Run the setup again
Section titled “Run the setup again”Open Settings, and in the About tab click Review… next to Guided setup. The setup starts over from the first step. Your workspaces and settings stay as they are, unless you change them in the steps. The projects step checks nothing on its own this time, even when General is your only workspace: the projects your workspaces open read “In” and their workspace’s name, and only the projects you check become new workspaces.