Agents waiting for you

When several agents work at once, each in its own project, the one that needs you is rarely the one in front of you. Layout knows which workspace each project belongs to: when an agent asks for you or finishes, it marks that workspace, shows a notification, and ⌃⌥N takes you there.

Connect Claude Code, Codex and Cursor

Open Settings › Integrations. Under Agents, click Add next to each agent you use. Layout adds hooks to the agent’s own file, after the hooks already there:

Claude Code: Notification and Stop, in ~/.claude/settings.json. New sessions use them.
Codex: PermissionRequest and Stop, in ~/.codex/hooks.json. The next time Codex starts, it asks you to review them: Codex runs no new hook before you approve it.
Cursor: stop, in ~/.cursor/hooks.json, for the agent in the editor and the CLI. Cursor reloads it automatically. A completed task gets a green mark; a task that stops with an error gets an amber mark saying “Stopped with an error”. Aborted tasks make no mark. Cursor’s hooks do not report waiting for approval, so those prompts make no agent mark. See Cursor’s hook reference.

The rest of the file stays as it was written, and its previous version stays next to it, as settings.json.layout-backup or hooks.json.layout-backup. Remove takes the hooks out again. They call the layoutctl inside Layout, so they work without installing the command; if you move Layout or use another copy of it, Update points them to the one you’re using.

When the file isn’t valid JSON, Layout leaves it alone and says on which line it breaks: fix it and come back, or click Copy and add the hooks yourself.

An agent that has never run on this Mac has no folder yet, ~/.claude, ~/.codex or ~/.cursor: its row reads “Not set up on this Mac” and has no Add.

Any other tool can mark a workspace too, with layoutctl notify: layoutctl notify --kind needs-input --message "Deploy?" from the project’s folder.

Which workspace

Layout marks the workspace whose folders hold the folder the agent works in: its project folder, its Claude and Codex projects, and its editors’ and terminals’ own folders. When several match, the deepest folder wins, so an app in ~/code/shop/web marks the workspace of web rather than the one of shop.

A git worktree counts as its repository, wherever it lives: Claude’s and Codex’s own worktrees mark the project’s workspace.

For Cursor, Layout uses the first valid absolute folder in the hook’s workspace_roots. In a window with several root folders, the first one determines the workspace. A hook without a valid root is ignored. Going to its notification brings the matching editor or terminal window forward; it does not select a particular Cursor conversation.

The workspace you’re in is never marked: you’re already there.

The mark

Amber: the agent asks for you. It needs a permission, asks a question, or waits for your next message.
Green: the agent is done with its turn.

Cursor errors also use amber. Cursor’s application badge remains a separate notification: Layout reads it when it appears or grows in the Dock, even without the agent hook. A macOS banner or an alert inside Cursor without a Dock badge is not mirrored.

A question stays amber until you answer it, even when a turn ends after it.

With Codex’s auto-review, its reviewer answers permissions in your place: they mark nothing, and the mark comes when the turn ends.

The mark shows:

on a card under the Layout bar for a few seconds, with what the agent said;
in the Layout bar, after the workspace’s name: the first notification to visit, with +2 when others wait too. Click it to go there, or hover it to read what each agent said;
in the workspace switcher and the Overview, next to the workspace’s name;
in the menu of the workspace’s name on the Layout bar.

Going to the workspace clears its mark, whichever way you get there.

Go to the next one

Each mark is also a notification, next to the apps’ Dock badges. ⌃⌥N goes to the next one, the agents asking for you first, and ⌃⌥P back; ⌃⌥/ lists them all. Change the keys in Settings › Shortcuts. If one of your workspaces already used one of them, it keeps it.

It takes you to the agent itself, not only to its workspace:

In Claude or Codex, their window comes forward and the session that asked for you opens, even when the project has several. A session the app no longer has opens the latest chat of the agent’s folder instead.
In a terminal or an editor, its window comes forward: the one showing the agent’s folder when there are several.
In tmux, the agent’s pane becomes the current one in its window, grouped sessions included, and the terminal showing it comes forward.
In cmux, its window comes forward showing the agent’s tab, and the agent’s pane gets the keyboard. See cmux.

When that window is in another workspace, you go there, and the mark goes too. When there’s no window to bring, because the app quit or no terminal shows the tmux session, you land in the marked workspace.

cmux

cmux keeps its own notifications, one per pane: an agent that asks for you or finishes, whichever agent it is, or any tool that notifies in a cmux terminal. Layout makes each pane with a notification you haven’t read in cmux one of its own, in every workspace, with its card, its place in ⌃⌥/ and ⌃⌥N. Nothing to set up: Layout reads the log cmux keeps of its events, ~/.cmuxterm/events.jsonl, as cmux writes it. cmux’s Dock badge then no longer counts as a notification of its own.

What it says: the agent cmux saw in the pane and the cmux tab’s name. cmux leaves the notifications’ words out of its log, so Layout doesn’t have them. When you also connected Claude Code or Codex, the agent’s own words show, and the pane’s notification and the agent’s mark are one: it stays new until you answer it, as an agent’s mark does.
Which workspace: the one whose folders hold the pane’s folder, as for an agent; otherwise the one cmux’s window is in. A wildcard cmux comes to the workspace you’re in.
Going there: cmux’s window comes forward, already showing the tab, then the pane gets the keyboard. The first time, macOS asks to let Layout control cmux. Without that permission, cmux’s window comes forward without the tab; Settings › Integrations says so and opens Privacy & Security › Automation.
When it goes: once you read it in cmux, as cmux does when you focus the pane, whichever way you got there. Once cmux has come to the front, it stays in the list, dimmed, until you read it there; one that comes while cmux is in front gets no card. Cleared from the list, a pane stays out until its next notification.

cmux still shows its own banners. If Layout’s card is enough, turn cmux’s off in System Settings › Notifications › cmux. Turn Layout’s reading of cmux off in Settings › Integrations, with cmux: an agent’s mark in a cmux pane then brings cmux’s window forward, as for any terminal.