Getting Started

Requirements

• • macOS 14 or later.
• • `yabai` installed and running (window IDs and focus routing).
• • iTerm2 installed (process terminals).
• • Google Chrome installed (browser sessions).
• • Accessibility permissions granted to Muxy dependencies.

First Session Flow

1. 1. Install dependencies (`yabai`, iTerm2, Google Chrome) and grant permissions.
2. 2. Add or connect a project.
3. 3. Create a workspace for the branch or task you are starting.
4. 4. Launch the workspace and continue where you left off.
5. 5. Switch to another workspace without rebuilding context from scratch.

Add Your First Project

Use either a local directory or a Git repository URL. On project add, Muxy detects whether the directory is a Git repository and creates a non-archivable default workspace.

Create a Workspace

For Git projects, create a workspace by choosing a workspace name, branch, and target branch. Target branch defaults to `main` or `master` when available. Non-Git projects create workspaces from the project directory and do not require branch inputs.

Launch and Validate

Launch is valid only for stopped workspaces. A launch allocates ports, starts configured processes, and opens browser sessions.

• • Confirm the workspace shows as running in the sidebar.
• • Confirm process rows appear in the Run tab.
• • Confirm URLs in browser sessions are open in Chrome.
• • Confirm named port env vars (e.g. `FRONTEND_PORT`, `API_PORT`) appear in the Env tab.

Product Boundaries

• • Muxy manages workspace context and switching.
• • Muxy does not manage tiling geometry; keep using yabai for layout.
• • Browser session focus and cleanup are URL-based; tab-title matching is intentionally avoided.
• • Existing tools still handle editing and coding.
• • Multiple workspaces can run in parallel while you stay focused on one.