Editors and terminals

VS Code, Cursor, Devin Desktop, the JetBrains IDEs, and your terminal (Terminal, Ghostty, iTerm2, WezTerm, kitty, or cmux) can open a folder when the layout launches. In Apps, their row reads Add a folder until you choose one.

Choose the folder

When the workspace has a project folder, the app opens it: its dialog starts on Project folder. Choose Its own folder to give the app another one, or None to open no folder at all.

Otherwise, click the app’s row to open its dialog, then:

• click Choose… and pick the folder,
• drag the folder from the Finder onto the card, or
• type its path, such as ~/Projects/my-app.

The path must be absolute, or start with ~/. Once a folder is set, Show in Finder reveals it and Remove clears it. Click Save to keep your choice.

If the folder doesn’t exist, the dialog says so: “This folder doesn’t exist. Launching the workspace reports it until you choose another one.” The app’s row in Apps then shows a warning triangle.

VS Code, Cursor and Devin Desktop

When the layout launches, Layout finds or opens a window of the editor that shows your project, and places it in the editor’s zone:

1. Layout first looks for a window that already shows this project. A window matches when the file it shows is inside the folder or, when the editor doesn’t report a file, when its title contains the exact name of the folder.
2. If exactly one window matches, Layout uses it. If two windows match equally, for example two projects with the same folder name, Layout doesn’t guess and reuses neither.
3. Otherwise, Layout asks the editor’s own command-line tool, bundled inside the app, to open the folder in a new window (--new-window). If an existing window starts showing the project after that, Layout accepts it too.

If no matching or new window appears within ten seconds, Layout shows an error instead of placing an unrelated window: “No matching or new context window appeared. Open the configured folder or URLs in the app, then launch the workspace again.”

Layout doesn’t run any project command. It only asks the editor to open the folder.

JetBrains IDEs

WebStorm, IntelliJ IDEA, PyCharm, GoLand, PhpStorm, RubyMine, CLion, Rider, RustRover and Android Studio open a project folder too. When the layout launches, Layout finds the window of your project, or has the IDE open it, and places it in the IDE’s zone:

1. A window matches when its title names the project, as in app – index.ts for the folder app. When two open projects share a name, the IDE adds the folder to the title, as in app [~/Work/app] – index.ts, and Layout goes by that folder. Layout also remembers which folder it opened each window for, so the window of one app is never taken for another. A window you opened yourself, whose title only says app, isn’t taken either while another of your workspaces opens a folder named app that has no window yet.
2. Otherwise, Layout hands the folder to the IDE, as the Finder does, and the IDE opens the project in a new window. The first time, the IDE asks whether you trust the folder.
3. An IDE that’s starting takes a few seconds before its window shows: Layout waits up to 30 seconds, then reports, for example, “No window appeared for app. If WebStorm asks whether you trust the folder, answer it, then launch the workspace again.” Launched again while the question is still up, the IDE opens the project twice once you answer: Layout takes one of the two windows.

Layout never asks for a project whose window is already open, since the IDE would open it a second time. A project you renamed in the IDE isn’t recognized by its title: launching then opens it again.

An IDE you quit and open again within five minutes, for example to update it, gets each project back in its workspace. Later, the projects it reopens as it starts all land in the workspace you’re in. A launch that finds its project’s window in a workspace where the window only opened takes it from there, instead of sharing it: launch each workspace, and each project ends up in the workspace whose folder it shows. VS Code, Cursor and Devin Desktop windows follow the same rule.

Several folders

VS Code, Cursor, Devin Desktop and the JetBrains IDEs can open more than one folder, so two repositories can share a workspace. Under Also opens, in the editor’s dialog, click Add a Folder… or drop folders from the Finder. The app’s row in Apps shows how many more with a tag such as +1.

Each folder opens in a window of its own. When the editor has several zones in the layout, each zone takes the next window and the last one stacks the rest: with the editor in a left and a right zone, the first folder opens on the left and the others on the right.

Terminals

Your terminal opens a window in the folder when the layout launches. Launching again puts the workspace’s terminal window back instead of opening another one.

Commands

The workspace’s first terminal can also start commands, such as your dev server. In its dialog, Commands holds up to four, a pane each; an empty pane is a plain shell. When the folder’s package.json names a dev server, a button adds it: pnpm dev, npm run dev, and so on. In Desktop, Documents, Downloads, iCloud Drive or another folder macOS guards, Layout doesn’t open the file, so macOS doesn’t ask you to let it in: type the command yourself.

When the workspace launches, each command is typed into your own shell in the folder, so your PATH, nvm, and aliases apply, its output stays in sight, and Ctrl-C gives you the shell back.

When a browser in the workspace opens a local address, such as localhost:5173, the terminal starts first and the tab opens once the dev server answers, after 8 seconds at most. You see your app, not a page that can’t connect.

Terminal	Where the commands run	Permission
Ghostty, iTerm2	One window, a pane per command	macOS asks once to let Layout control the app.
WezTerm	One window, a pane per command	None
Terminal, kitty	A window per command, stacked in the terminal’s zone	None
cmux	A tab per command	None

For Ghostty, iTerm2 and WezTerm, and in a tmux session, Commands draws the terminal’s window with its panes where they open, like the zones of a layout. Click a pane to type its command. Hovering a pane shows buttons to split it right or down, or to remove it, and right-clicking it offers Split Right, Split Down and Remove Pane. The panes of a split share its space equally, and removing a pane gives its space to the others. For Terminal, kitty and cmux, which open a window or a tab per command, Commands is a list.

Launching again types nothing twice: the terminal windows the workspace holds are put back in place. Closing a window stops its commands, and stopping the workspace gives them a ⌃C before closing its windows. Switching workspaces never runs anything.

Run in a tmux session

Check Run in a tmux session to show a tmux session instead. The session outlives the window: closing the window leaves what runs in it running, and launching again attaches a window to it. A list, searchable like the Claude and Codex projects, chooses the session:

• New session, the default: Layout starts a session for the workspace, with your commands in the same arrangement, or a single shell when there are none. Stop Session… in the dialog ends it, and so does stopping the workspace.
• One of your own sessions, the most recently used first: Layout attaches a window to it as it is and types nothing into it, so the dialog hides the commands. If it isn’t running when the workspace launches, Layout starts it again under the same name, with a shell in the terminal’s folder. Stopping the workspace closes its window and leaves the session running.

The list shows what your tmux server runs, without ever starting tmux. The sessions Layout started for your other workspaces aren’t in it. This needs tmux (brew install tmux), and a tmux server that Layout starts loads your tmux configuration, including plugins that restore saved sessions.

Share one Ghostty window

With Ghostty, several workspaces can share one window instead of each opening its own. Check Share one Ghostty window across workspaces in Ghostty’s dialog, in each workspace that should share it. This turns on Run in a tmux session, which the shared window needs.

When you switch between those workspaces, the window stays on screen and shows the tmux session of the workspace you switch to, so each workspace keeps its panes and what runs in them. The other sessions keep running. Ghostty’s row in Apps reads “Shared window · tmux follows this workspace”.

Layout remembers the shared window and its tmux client, including when Layout restarts. Other Ghostty windows can stay open without blocking its session switches. When the shared window isn’t open, Launch creates a new one and leaves your other Ghostty windows alone, even one already running tmux. Until then, switching moves your windows and leaves tmux as it is; before the first shared window, Layout reminds you to launch the workspace. Enabling sharing in another workspace then reuses that same window; it does not close that workspace’s older terminal.

If the shared window is in full screen or on another desktop, Layout asks you to bring it back. If its tmux client was detached, close that window and launch the workspace again. Layout never switches a different client as a fallback. New shared windows briefly show a unique startup title so Layout can identify them before attaching tmux; a Ghostty configuration that forces a fixed title can prevent that identification.

Errors you may see

Message	What to do
Folder not found, followed by the path	The folder was moved or deleted. Choose it again.
Choose an absolute folder path (or ~/…).	Type a full path, or one that starts with ~/.
The configured app is not installed.	Install the app, or remove it from the workspace.
No matching or new context window appeared…	Open the folder in the app yourself, then launch the workspace again.
Layout isn’t allowed to control Ghostty…	Turn Ghostty (or iTerm2) on under Layout in System Settings › Privacy & Security › Automation, then launch again.
tmux isn’t installed…	Install it with brew install tmux, or uncheck Run in a tmux session.

Errors in one app don’t stop the others from launching.