[teamleaderleo]

An agent chat is now its screen's main pane, and nothing opens into it. Links, files and folders a chat opens, and its subagent and side chat panes, become tabs in one column on the chat's right. A chat alone on its screen docks left the first time, so that column slides in beside it. Closing the column's last tab gives the chat its full width back: the daemon folds the dock into a plain pane, which dock_column_flags_cleared_by_a_close_stay_cleared_after_restart covers.

This is on by default as layout.mainPane: "agent-chats", and "off" turns it off. Debug Settings > Panes and Columns > Main pane layout overrides the setting: Follow the setting, On or Off.

How it works

MainPaneLayout.side (CmuxNextLayout) reuses ChatColumnPlacement, the rule a person's new tab from the chat already follows:

• From the chat dock, the new tab goes into the strip pane the person used last.
• From a lone chat, the chat docks left (.dockChat).
• Any other pane keeps today's rules: a strip pane, a terminal, a chat sharing its screen without a dock, a zoomed screen, and Home's pinned dock when it is alone.

The callers:

• LinkOpener: links, files and folders from the chat go to the column on its right. Before this, a click in a chat opened a tab inside the chat (cmux-next: what a page opens is a tab in its pane; Cmd-click still opens right #22822).
  • From a lone chat, the tab opens unselected in the chat's pane, then the chat docks left with the agent chat role (MainPaneLayout.dockChat).
  • A folder docks the chat and leaves the folder's terminal in its pane, in one daemon commit (ChatColumnPlacement.route).
• AgentTabStore.openBeside: subagent panes and side chats open as tabs in that column, not as splits stacked beside the chat.
• Agent opens (beside_caller: browser, diff, process terminal, Files tree) and a person's Cmd-T from the chat already landed there. They're unchanged.

Focus follows the link-focus rule. A person's click focuses the new tab. An agent's open, or an unfocused subagent open, selects its tab in the column without moving keyboard focus (selectWhenReportedKeepingFocus). A lone chat's open reports finished only once the chat is listed in its dock, so a second open right after it is a tab in the same column, not a split. A past chat picked on a New Tab page in the dock still replaces the page in the dock (mainPane: false): chats never become tabs in the right column.

The slide-in uses the existing pane springs. #22949 (directional-motion) holds the chat in place while a lone chat docks for AgentBesidePlacement. Once it lands, MainPaneLayout.dockChat gets the same one-line handOffContent hint.

Changelog

• New: an agent chat stays as the main pane, and what it opens appears as tabs in one column on its right (Settings > General > Main Pane).

Testing

• I ran 5 suites on the fleet at the PR's head: MainPaneLayoutTests, MainPaneSettingTests, LinkOpenPlacementTests, LinkPlacementSettingTests and HomeLoneDockTests. All 30 tests passed, at both bf31888 and ea6e682.
• The settings exports were regenerated by the PR autofix (run 39588693869). defaults_guard.py check-stamp passes.
• prepush-gate.py found no new violations, and lint-ios-package-conventions.sh passed.
• The independent review is in the PR comments. It found three problems in the first version, all now fixed: agent opens took focus, a quick second open made a split, and resumed chats landed in the right column.
• The tour is scripts/cmux-next/media/tours/main-pane.json, run under the media-tour label. It shows a lone chat docking for a link, tabs joining the right column, and closing the column giving the chat its full width back.

🤖 Generated with Claude Code

Agent session: cosmic-gray

---

^{Need help on this PR? Tag @codesmith-bot with what you need.}

---

Summary by cubic

An agent chat now stays as its screen's main pane: links, files, folders, subagent panes, and side chats it opens land as tabs in one column on its right, instead of inside the chat (#22822) or as splits stacked beside it.

• On by default as layout.mainPane: "agent-chats"; "off" restores the previous rules. A Debug Settings override (panes.mainPane: Follow the setting, On, Off) can force either.
• A chat alone on its screen docks left the first time so that column slides in beside it; the dock hands off the chat's content so only the new column moves, and cancels the hint if the dock fails. Closing the column's last tab gives the chat its full width back.
• A person's click focuses the new tab; an agent's open selects it without taking focus, and a queued open waits until the chat is in its dock so it lands in the same column.
• A past chat picked on a New Tab page in the dock still replaces the page there; main pane routing applies to terminals, browsers, and links only.
• Settings exports, MDM docs, and localizations were regenerated; tests, a tour, and a release-note highlight with a New Agent Chat try-it action cover the change.

^{Written for commit 48354b3. Summary will update on new commits.}

[teamleaderleo]

Owned by projects-d9 on cosmic-gray · session

[github-actions]

cmux status _{(one comment, edited in place; each line is updated by the job that owns it)}

Review 48354b3: HQ feed card · gallery before/after runs · checks

App of this head (app.zip, kept 1 day)

gh workflow run reload-build.yml -R manaflow-ai/cmux --ref feat-cmux-next -f tag=pr23105 -f ref=main-pane-layout -f platform=macos -f backend_mode=local

Not verified: macOS jobs did not run: compile and app tests were skipped on 48354b34a7; ci-status is green without them.

CI passes on 48354b34a7 (run 39595977415 attempt 1).
macOS jobs did not run: compile and app tests were skipped: Fast static checks skipped (the macos job needs both to succeed). Re-run CI once they pass, before merging.

Written by scripts/ci/classify_failures.py (ci-failure-attribution.yml); signatures are its SIGNATURES table. A machine verdict is the runner's fault, not this PR's; yours means the failing file is one this PR changes, also red on main that main's latest full suite fails the same way, seen on other PRs that it failed on another pull request's run lately.

web and size checks: green

Tour of 48354b34a7 (run): no media. The tour job failed before the tour ran (build or setup); the run log has the output.

[teamleaderleo]

Bead cx-k6vrc created for this PR by the cmux coordinator.

[teamleaderleo]

Review (independent subagent): SHIP at bf31888

I reviewed the full diff against feat-cmux-next by reading the code. Nothing was built on this host.

• Compile: I checked import and PaneID resolution in every file the diff touches (DaemonPaneID in the routing file, a scoped import struct in Wiring). The calls to TabMoves.toNewDockColumn, PaneController.select, selectWhenReportedKeepingFocus, apply and snapshot, paneTabBars, ActionRunScope.carrying, TabMirror.reaches and Locate, and AgentTabPending all match their declared signatures. Every switch over LinkOpenPlacement.Target handles .dockChat. The Debug help string's quotes are escaped. The tunable choice and both test files look right.
• Behavior: created and finished reach AgentSidePanes and AgentSubagentPanes exactly once. In the .dockChat path, finished now runs only after the store lists the chat in its dock, so a queued open finds the column on its right. Unfocused opens select the new tab with selectWhenReportedKeepingFocus, so keyboard focus stays in the chat. A chat picked from a New Tab page keeps the old rules (mainPane: false). With layout.mainPane off, LinkOpener and openBeside behave exactly as before. Zoomed screens, Home's lone pinned dock, and daemons without dockColumnRole fall back to the usual rules.
• Settings: the schema row, agent-settable policy and snapshot parse are in place. All 4 xcstrings keys have every locale. The highlight follows WRITING.md, and the try-it action exists. The tour JSON passes tour.py's schema.
• Still to do: the settings exports (schemas/settings, docs/mdm, defaults snapshot) need the autofix regeneration; that is the defaults-snapshot red. No test covers openAgentTab or dockChat yet; they need a live store.

[teamleaderleo]

cmux-next crash-class rules / cmux-next crash-class rules is red on 12 of 12 fresh feat-cmux-next PR heads in the last 2:00:00, so it is most likely a base red, not this PR's. The base-reds lane has it; a base merge picks up the fix once it lands.

[teamleaderleo]

Review (independent subagent): SHIP at ea6e682

This follows the SHIP at bf31888. I checked the merge of feat-cmux-next (410d713) and the autofix exports (ea6e682) by reading only; nothing was built on this host.

• The merge left the PR's changes unchanged. For every file the PR touches except Localizable.xcstrings, its changed lines against the new base are identical to its changed lines at bf31888 against the old base.
• Localizable.xcstrings at head parses as JSON with no duplicate keys. Compared with the new base, it adds exactly the 4 layout.mainPane keys, and no other entry is removed or changed. The large textual diff is git placing entries in a different order; the catalog was not sorted on base either.
• Base did not change any API the PR calls. Over the merge range, LinkOpener, LinkOpenPlacement, ChatColumnPlacement/ChatPlacement, NewTabPage+Open, ChatsOpenCoordinator, AgentBesidePlacement (selectWhenReportedKeepingFocus), TabMirror, AgentTabs+Header/Wiring/Lifecycle, the side and subagent trackers, ActionRunScope and DebugSettingsService are unchanged. AgentTabs.swift (pageHost flag), TabMoves (only move-to-workspace intents) and PaneController (newTabShortcut) changed in places the PR does not call. CmuxConfigSnapshot gained base's terminalFirst and browserToolbarPosition next to mainPane.
• The exports contain layout.mainPane (default agent-chats, choices agent-chats and off) in settings-schema.json, the defaults snapshot and docs/mdm. The other rows in that diff come from base's own sources: tabs.terminalFirst, sessions.promptSuggestions, notifications.attention.*, and the workspaces.newPlacement default of afterCurrent.

[teamleaderleo]

codex-review: SHIP at c04a225

• Reviewed the current diff, its focused tests, and the affected call paths; no correctness bug found.

[teamleaderleo]

Review (independent subagent): SHIP at 8d0d6a2

This follows the SHIP at ea6e682. I checked the base merges c04a225, ebe84dc and 8d0d6a2 and the autofix exports 1f386e5 by reading only; nothing was built on this host.

• Conflict in AgentTabs+Wiring.swift: no conflict markers are left. tabs.openInMainPane and base's tabs.runAttach are separate statements, and each matches its property in AgentTabs.swift. The scoped import struct CmuxNextLayout.MainPaneLayout stays, and nothing else in the file names a CmuxNextLayout type.
• The PR's own changes are unchanged: for every PR file except the generated exports, its changed lines against base 92c12bc are identical to its changed lines at ea6e682 against c96af48. Localizable.xcstrings at head parses with no duplicate keys and, compared with base, adds only the 4 main pane keys.
• Base did not change any API the PR calls: LinkOpener, LinkOpenPlacement, ChatColumnPlacement, NewTabPage+Open, ChatsOpenCoordinator, AgentBesidePlacement, TabMirror, AgentSidePanes, ActionRunScope, PaneHandlers.focus, PaneController.select and AgentTabs+Header. AgentTabStore.open (remote child chats) and AgentSubagentPanes (focus owed to a click during an unfocused open) changed only inside, and both still fit the PR's create, finish and focus order. The new switch over ChatColumnPlacement in SplitRoomCheck is exhaustive, and the PR adds no cases to that enum.
• Exports: only the 6 generated files change against base. layout.mainPane is in settings-schema.json, the defaults snapshot and docs/mdm. The other rows the defaults snapshot adds (home.server, notifications.attention.flash, notifications.attention.flashOnTyping, notifications.showPreviews, agentPane.display.inspector.placement) are already in base's settings-schema.json; base's defaults snapshot had not caught up with them.

[teamleaderleo]

Review (independent subagent): SHIP at 416026d

This follows the SHIP at 8d0d6a2. I checked the base merge 1c78451, the content hand-off in 0d3b7c7 and the test registry revert in 416026d by reading only; nothing was built on this host.

• Hand-off pane: handOffContent(of:) names the giver, the pane that shows the content now and keeps the new tab, which then slides in (LayoutModel+ContentHandoff, PaneArrival.handoff). In dockChat that is controller.layoutPaneID, the lone chat's pane, which holds the new tab unselected while the chat moves to the dock. AgentBesidePlacement passes lone.layoutPaneID the same way. The hint is set right before TabMoves.toNewDockColumn, so the dock's structural change spends it well inside the 3 s window. A failed dock cancels it, so a later split still plays as a split.
• Callers: LinkOpener .dockChat (a person's click with focus, an agent link without) and openAgentTab's lone chat path all go through the same dockChat, and the hand-off only changes how the change animates. Focus, then and finished order are as I last reviewed them. The folder .dockChat path still docks through ChatColumnPlacement.route, which base did not give a hand-off; that is an animation difference, not a fault.
• Tunables: LayoutTunables.all keeps base's holdsContentInMotion.descriptor and puts MainPaneLayout.all back before DropOverlayTunables.all. Nothing is dropped or listed twice.
• tests/test-execution.toml now matches base exactly.
• The PR's own changes against base 5c4e212 are what they were at 8d0d6a2, apart from the 5 hand-off lines and the tunables line. Localizable.xcstrings still adds only the 4 main pane keys, with no duplicates and no other entry changed. Over this merge, base changed AgentBesidePlacement (the hand-off), LayoutModel and a menu row in PaneController+Intents, and none of them changes an API the PR calls.

[teamleaderleo]

Review (independent subagent): SHIP at 48354b3

This follows the SHIP at 416026d. I checked the base merge 48354b3 and its AgentTabs+Header.swift conflict by reading only; nothing was built on this host.

• Resolution: base's lines are kept. openBeside is internal, and openTab takes (session, destination) and calls openFork, which matches AgentPaneModel+Header's new (String, AgentForkDestination) -> Bool hook. The PR's lines are all back: main: provisional on the side chat and subagent calls, main: String? = nil in the signature, and the openInMainPane line. Against base 7052345, the PR's changes to this file are exactly those lines; every other PR file is unchanged from 416026d.
• openFork (AgentTabs+Fork.swift) calls openBeside without main, so main pane routing leaves it alone. I agree it should. Every Fork destination is one the person picked (a split on a named side, a tab, a workspace, a window), and a fork is a chat, which belongs in the dock and not the column on its right; ChatsOpenCoordinator was left out (mainPane: false) for the same reason. The call compiles: main is defaulted and its labels are in order, and the file's PaneID is CmuxNextDaemon's, as in openBeside.
• Over this merge, base changed only AgentTabs+Header.swift and AgentPaneModel+Header.swift among everything the PR calls: LinkOpener, ChatColumnPlacement, TabMoves, PaneController, AgentBesidePlacement, LayoutModel (content hand-off), NewTabPage, ChatsOpenCoordinator, TabMirror, AgentSidePanes, AgentSubagentPanes, ActionRunScope, settings and tunables.

[teamleaderleo]

Merged at 48354b3 (squash 2a7eec5).

• Review: the independent review approved at the head; the receipt is above.
• Compile: cmux-ci compile-check --app passed on the fleet at that head (job 5f91772b89ac459e0eeed928). CI's Mac compile and test jobs had been queued for over an hour.
• Checks: all 77 that had finished passed, with none red.
• Fleet suites: the main pane, link placement and lone dock suites passed at bf31888 and ea6e682.
  • At 416026d the package's test target didn't compile, because of a base test from cmux NEXT: show and open a Cloud VM chat's child chats #23163, RemoteChildSessionsTests.

Two things for later:

• Defaults call: this adds layout.mainPane, which is on by default for agent chats. No call owner from .github/defaults-call-owners.json has reviewed it; @lawrencecchen was asked. The cmux-next defaults guard workflow never ran on this PR. The call came from Leo's brief ("ON by default for agent-chat workspaces"). To change the default, edit MainPaneSetting.fallback. Debug Settings > Panes and Columns > Main pane layout overrides it.
• Follow-up: a folder opened from a chat alone on its screen docks the chat through ChatColumnPlacement.route, which has no content hand-off. That open animates as a split instead of the slide-in. It's cosmetic and is left for a small follow-up.

[teamleaderleo]

Defaults approval: Leo's order (relayed by claude-sr2, 2026-10-21): keep layout.mainPane = agent-chats.

[github-actions]

Shipped in:

• cmux NEXT nightly 1.0.0-nightly.3961101575901 (101cc33db2)
• cmux NEXT nightly 1.0.0-nightly.3961563706401 (5c92af7a3b)