For a step-by-step workflow, read the related guide. For current provider support, consult Capabilities; this chapter describes reviewed surfaces and their limits.
Choose the scope before saving
| Concept | What it preserves | What it does not do |
|---|---|---|
| Workspace | Project membership and the current fleet filter. | Copy project files or conversations. |
| Saved View | Pane layout, complete tab order and selection, and per-chat configuration. | Migrate a native session between providers. |
| Agent workbench | An isolated Git working tree and branch. | Automatically approve, verify or merge work. |
| Project | A registered folder and project contract. | Authenticate a provider account. |
Switch a fleet filter, not a project folder
Replace WORKSPACE with an existing workspace name. Listing is read-only; selecting or clearing changes the active local filter. No files move and no agent starts.
commandem workspace ls --json
commandem workspace use WORKSPACE
commandem workspace use --clearExpected result: the list shows workspace membership, selection filters the fleet, and clearing returns to all projects. See workspace commands. To preserve pane configuration instead, save a project layout.
Find the actual isolated checkout
Replace PROJECT with a registered project name. This inspects workbench paths and divergence; it does not create or land a branch.
commandem workbench ls PROJECTExpected result: existing workbench directories and their relationship to trunk, or an empty list if none exist. Review pending work before any workbench landing operation.
Saved Views and project defaults
Save the current layout from the palette, inspect Saved Views, and assign an appropriate saved layout as the project's default. A Saved View captures pane destinations, split direction and divider, follow/pin behavior, complete displayed chat/file tab order and selection, and each chat's provider, account, model, effort, mode and workbench choice. The original chat can be reordered or absent when other tabs remain. Newly created chats start fresh; a reused existing chat may retain its conversation. Prompts, transcripts, credentials and session identities are not copied. Review manual replacement and automatic restoration before applying it.
Boundary and recovery: Verify project, pane and provider/account/model selections before sending. Restoring a layout is not native session migration or authentication.
Workspace scope
A Workspace groups projects and filters status/sidebar views. Select it with the workspace switcher; All projects clears that filter. Workspace export/import is distinct from layout saving.
Boundary and recovery: A filtered list can hide existing projects; it does not delete them. Do not confuse a Workspace with a Saved View or an agent workbench.
Agent workbenches
A workbench is an isolated Git working tree used for concurrent implementation. The primary checkout is the integration lane; branches are reviewed, tested, committed and landed back to trunk.
Boundary and recovery: Infrastructure visibility is configurable in Layout; hidden workbenches still exist. Isolation does not excuse modifying another agent's files or skipping commit gates.
Command palette and menu routes
Use the configured command-palette shortcut to discover global actions, Settings destinations and saved layouts. Static destinations are listed below; project-specific or user-defined entries may also appear.
Work panes. Working views open as panes in the main window, the way Home does, with the sidebar still showing. They are Monitor, Usage, Activity timeline, Agent runs, Peer review, Automations, Experiments, Runner control, Discover, Review & Merge, Git Across Projects, Standing Directives, Activity, Matrix, Run Reports, Replay, Context and Plan. Only one is open at a time, and opening another replaces it. When the open pane holds unsaved work, opening a different pane from the palette, a menu or a notification asks Discard unsaved work? first (Discard and continue opens what you asked for, Keep editing drops it), and is refused while a sheet is open over the pane; a link inside a pane to another pane, such as Replay from Monitor, replaces it without asking. A pane has no Done button. Close it with the x at its top right or with Esc. Esc takes one step per press: a sheet or dialog open over the pane takes it first, then the pane clears a search or filter field it has, then a focused text field gives up focus, and only then does the pane close. Selecting a project, from the sidebar, the palette or a row that navigates, also closes the pane. Closing by any of these routes asks Discard unsaved work? when the pane holds unsaved work: Standing Directives with edits not yet applied, Plan with Missions selected for an Operation preview or planning text not yet submitted, and Run Reports while a Debrief is waiting to open. Peer review does not ask, because its comments and any AI review result are kept when the pane closes. Confirmations, sign-in, the policy editor and a Debrief stay sheets or dialogs over the window.
Boundary and recovery: An entry opens a surface or performs its named action; visibility is not permission for broad mutations. Commands and shortcuts can be customized locally.
Project tab layout
The project tab bar has seven direct buttons: Chat, Overview, Plan, Monitor, Review, Code and Terminal. Overview is the project home. Plan, Monitor and Review each open the last pane you used in that section for this project (the first time: Missions, Control, News). Plan holds Missions, Campaigns, Notes and Links; Monitor holds Control, Messages, Checks, Log and Config; Review holds News, History, Stats and Matrix. A small strip atop each pane moves within its section, and none shows on Overview, Chat, Code or Terminal. Code is a pull-down of Files, Search and Diff. Cmd-1 to Cmd-7 open the Nth button the bar actually shows, in the order it shows (a dragged order is honoured, a hidden button is skipped, and a digit beyond the last button does nothing), Config, Log, Stats and the other panes have no default shortcut, a shortcut you set yourself for a tab or button can shadow one of those digits so check the shortcut list after changing them, and next/previous tab follows the visible bar. In a narrow pane the bar shows icons instead of labels (the selected button keeps its label if it fits) and tooltips stay; its tooltips read "Plan: this project", while the Plan and Monitor windows at the top right cover all projects. Right-click the bar to hide individual panes, reorder buttons, use icons only and adjust sizes; Quick Open/shortcuts still reach hidden tabs.
Boundary and recovery: Keep at least one usable tab visible. Reset tab layout when a hidden destination looks missing rather than recreating the project.
Sidebar destinations
Click the active activity icon again to toggle its panel. Files, Search and Changes depend on a selected project; Projects and Agents are global. Workspace filters and collapsed groups affect what is visible, not what exists.
Projects
Global project list, current selection and workspace scope. If the panel appears empty, check selection and workspace scope before changing the project registry.
Files
File navigation for the selected project; no selection means no project file root. If the panel appears empty, check selection and workspace scope before changing the project registry.
Search
Search within the selected project; separate from conversation/Matrix retrieval. If the panel appears empty, check selection and workspace scope before changing the project registry.
Changes
Repository changes for the selected project; inspect base and worktree before review. If the panel appears empty, check selection and workspace scope before changing the project registry.
Agents
Global agent/run visibility and entry points. If the panel appears empty, check selection and workspace scope before changing the project registry.
Configurable shortcut defaults
Composer Up/Down/Escape input recall follows the focused draft’s context. While a turn is running, Up can prepare a prior input for a new follow-up without rewinding the active work. Review input recall, local-history limits and send behavior.
Mouse gestures switch tabs/projects, close and undo close from each pane’s gesture strip. A preview appears while the right button is held; release executes an exact match once. Escape or an unmatched stroke cancels. Configure and practice in Settings → Input. Command+Shift+T also invokes Undo Close Tab in the focused chat pane.
Selected .md/.markdown tabs search their bounded read-only document preview; other file tabs and the inline Files source editor retain their existing Find behavior. Open Fleet from Tools → Fleet. Input settings expose an assignable Fleet action, with no default key assigned; this does not add a ninth built-in shortcut.
Open Settings → Input to edit keyboard bindings. These are source defaults, not a dump of current user settings. Focus and context matter; ordinary arrows navigate focused lists. Restore a binding if an override conflicts with an OS shortcut.
Command–T creates a chat tab in the primary pane. Option–Tab / Option–Shift–Tab select the next / previous chat tab there; these are distinct from macOS window tabs. Command–F and Command–W first use the most recent click that still identifies a pane in that window, then the pane containing the focused control, then the pane under the pointer. A click outside the panes does not override valid pane focus. Command–W closes the selected chat or file tab in that pane; with no active chat/file tab it closes the window. Chat and Roadmap keep their existing search; Files, Diff, Log, Activity, History, Board, Notes and Links have pane-local Find or filtering. A selected file tab within Chat, or an inline source editor open in Files, retains its editor’s native Find behavior. Read each pane’s search scope and limits. Search, Shell, Matrix, Stats, Config and Actions keep their existing keyboard behavior.
Open selected project
Command–O: Opens the selected project surface; requires a meaningful selection. Local overrides can change this binding.
Acknowledge attention
Command–D: Mutes current attention until project state changes; does not fix the condition. Local overrides can change this binding.
Snooze selected project
Command–E: Snoozes attention for 24 hours; project history is preserved. Local overrides can change this binding.
Open command palette
Command–P: Discovers app commands and destinations. Local overrides can change this binding.
Previous project
Command–[: Navigates the available project list in the current scope. Local overrides can change this binding.
Next project
Command–]: Navigates the available project list in the current scope. Local overrides can change this binding.
MRU project switcher
Control–Tab: Hold Control to cycle recent projects; add Shift for Control–Shift–Tab to move backward. Release Control to select the highlighted project, or press Escape to cancel. This is not the OS Command–Tab switcher. Local overrides can change this binding.
Open Notifications
Command–Shift–B: Opens the unified notification surface, not the OS Notification Center. Local overrides can change this binding.
Static palette entries
These source-declared entries are discoverable through the command palette. User-defined commands and Saved View names are intentionally excluded from the published inventory. Each entry remains subject to selection, permissions and the underlying feature limits.
Activity chart
Open this entry from the palette. See the related feature or workflow for its operation, scope and limits; opening a surface is not approval to execute its actions.
Activity log
Open this entry from the palette. See the related feature or workflow for its operation, scope and limits; opening a surface is not approval to execute its actions.
Add project…
Open this entry from the palette. See the related feature or workflow for its operation, scope and limits; opening a surface is not approval to execute its actions.
Agent runs
Open this entry from the palette. See the related feature or workflow for its operation, scope and limits; opening a surface is not approval to execute its actions.
All projects
Open this entry from the palette. See the related feature or workflow for its operation, scope and limits; opening a surface is not approval to execute its actions.
All Settings
Open this entry from the palette. See the related feature or workflow for its operation, scope and limits; opening a surface is not approval to execute its actions.
Announce to active chats
Open this entry from the palette. See the related feature or workflow for its operation, scope and limits; opening a surface is not approval to execute its actions.
Broadcast (run/queue/goal across projects)
Open this entry from the palette. See the related feature or workflow for its operation, scope and limits; opening a surface is not approval to execute its actions.
Configure Loadouts
Open this entry from the palette. See the related feature or workflow for its operation, scope and limits; opening a surface is not approval to execute its actions.
Configure Profiles
Open this entry from the palette. See the related feature or workflow for its operation, scope and limits; opening a surface is not approval to execute its actions.
Configure Security
Open this entry from the palette. See the related feature or workflow for its operation, scope and limits; opening a surface is not approval to execute its actions.
Git across projects
Open this entry from the palette. See the related feature or workflow for its operation, scope and limits; opening a surface is not approval to execute its actions.
Guide (help / concepts)
Open this entry from the palette. See the related feature or workflow for its operation, scope and limits; opening a surface is not approval to execute its actions.
Keyboard shortcuts
Open this entry from the palette. See the related feature or workflow for its operation, scope and limits; opening a surface is not approval to execute its actions.
New project (guided)
Open this entry from the palette. See the related feature or workflow for its operation, scope and limits; opening a surface is not approval to execute its actions.
Notifications (everything that needs you)
Open this entry from the palette. See the related feature or workflow for its operation, scope and limits; opening a surface is not approval to execute its actions.
Peer review workspace
Open this entry from the palette. See the related feature or workflow for its operation, scope and limits; opening a surface is not approval to execute its actions.
Plan
Open this entry from the palette. See the related feature or workflow for its operation, scope and limits; opening a surface is not approval to execute its actions.
Provider usage
Open this entry from the palette. See the related feature or workflow for its operation, scope and limits; opening a surface is not approval to execute its actions.
Review & merge agent branches
Open this entry from the palette. See the related feature or workflow for its operation, scope and limits; opening a surface is not approval to execute its actions.
Review inbox
Open this entry from the palette. See the related feature or workflow for its operation, scope and limits; opening a surface is not approval to execute its actions.
Run receipts
Open this entry from the palette. See the related feature or workflow for its operation, scope and limits; opening a surface is not approval to execute its actions.
Runner control
Open this entry from the palette. See the related feature or workflow for its operation, scope and limits; opening a surface is not approval to execute its actions.
Save current view…
Open this entry from the palette. See the related feature or workflow for its operation, scope and limits; opening a surface is not approval to execute its actions.
Saved Views…
Open this entry from the palette. See the related feature or workflow for its operation, scope and limits; opening a surface is not approval to execute its actions.
Standing directives (brief)
Open this entry from the palette. See the related feature or workflow for its operation, scope and limits; opening a surface is not approval to execute its actions.
Toggle current / condensed sidebar
Open this entry from the palette. See the related feature or workflow for its operation, scope and limits; opening a surface is not approval to execute its actions.
Toggle second pane
Open this entry from the palette. See the related feature or workflow for its operation, scope and limits; opening a surface is not approval to execute its actions.
Tool approvals
Open this entry from the palette. See the related feature or workflow for its operation, scope and limits; opening a surface is not approval to execute its actions.
Week (weekly review)
Open this entry from the palette. See the related feature or workflow for its operation, scope and limits; opening a surface is not approval to execute its actions.
Current source boundaries
These are source-level boundaries reviewed against 8f06da03. They do not replace the dated source captions or screenshots elsewhere in this handbook, or certify installed-app, physical-input, device, provider or OS-permission behavior.
Last active, workbenches and hover details
Last active prioritizes projects waiting for input or approval; it is not a pure ordering of immutable timestamps. Other activity uses the recorded project and agent observations. Idle groups initially show up to 20 entries with an explicit Show all control. Expanding a project's workbench lanes uses cached counts and lazily loaded details; a synthetic lane row is not proof of an always-live registered project.
Sidebar hover details come from recorded ledger observations, loaded asynchronously and checked against the observed owner identity. Unavailable or unknown details remain so; a hover card is not a readiness, liveness or provider-health certificate. Folder import and the Review queue route still require their own scope and review: opening a sheet or queue does not import a directory, approve a change or merge a branch.
Pane input and recovery
Tab moves land on the destination Chat strip of the same project. A different-project destination or a draft/confirmation conflict can refuse the move. Tab undo retention is bounded and best-effort. If a secondary pane's project disappears, close or reselect that pane explicitly.
When enabled, mouse gestures also have a middle-button route in project panes and the sidebar; the existing right-button bottom strip remains separate. Settings practice shows the current keyboard shortcut, or that none is assigned. Feedback visibility and size are configurable; hiding the live overlay does not hide explicit practice instructions. These declarations do not enable experimental held-right/global input capture or certify external mouse remapping. The cold-launch window reconciliation is a one-time repair, not a promise that only one window can ever exist.