Workspace Lifecycle

Lifecycle States

• • Default: auto-created per project and cannot be archived.
• • Stopped: persisted workspace with no active processes or tracked windows.
• • Running: processes and windows tracked and available for switching.
• • Archived: hidden from normal lists; worktree removed for Git projects.

Create

Creating a workspace copies project templates into workspace settings, runs the setup script, and reserves ports based on port definitions.

• • Git projects create a worktree directory for the workspace.
• • Branch creation uses this precedence: local branch, then remote branch, then new branch from target.
• • A branch is required for Git workspaces.

Launch

Launch is allowed only when a workspace is stopped. If the workspace is already running, use restart instead.

• • Starts workspace processes in dedicated terminal windows.
• • Opens browser sessions and tracks matching Chrome tabs by URL prefix.
• • Captures workspace windows so they can be focused later by shortcut.

Update While Running

• • Newly added processes start immediately in new terminal windows.
• • Process command changes restart the process in the same terminal window.
• • Newly added browser session URLs open immediately.

Stop and Restart

Restart runs stop first, then launch, for the same workspace.

• • Processes are gracefully interrupted, then terminated if needed.
• • The stop script runs after process termination (if configured).
• • Tracked workspace windows are closed (terminals and browsers).

Use mx workspace up for idempotent automation: it launches stopped workspaces and otherwise does nothing by default. Add --restart to force stop then launch when runtime state is already present.

Archive

• • The default workspace cannot be archived.
• • Archive runs the same stop flow as stop/restart.
• • For Git projects, the worktree directory is removed but branches are kept.
• • For non-Git projects, the project directory is never deleted.
• • Reserved ports are released on archive.