Installation & Setup
Download Muxy, install dependencies, configure permissions, and verify your setup.
Best for: New users installing muxy for the first time.
Read PageDocumentation
Muxy in five minutes.
This page gives a quick mental model for how Muxy helps you run and switch workspaces during parallel development.
Core Terms
Project
A codebase you configure once so new workspaces start with consistent behavior.
Workspace
An isolated stream of work for a feature, fix, or experiment.
Process
Commands you want running with the workspace, like app servers or agents.
Browser Session
Pages you want tied to a workspace so you can return to the same context.
Reserved Ports
Named port definitions allocated per workspace so parallel streams never collide on the same local port.
Status Check
A periodic shell command that tests a running process and surfaces green/red health in the UI.
Docs Overview
These pages cover the most common user questions and operational workflows from setup through troubleshooting.
Getting Started
Install requirements, connect a project, and launch a first workspace.
Best for: New users onboarding muxy for the first time.
Read PageProjects
Add and manage projects stored in the database, start project creation with source-first input (directory picker or git URL) before advanced template settings, get create/delete progress overlay feedback during project operations, configure templates (processes, ports, scripts, named browser sessions), and understand default workspace creation for directory projects and git-url imports.
Best for: Developers setting up and managing project definitions.
Read PageWorkspaces
Workspace concepts, New Workspace form flow (+ / cmd+n, visible cmd+n quick-create hint, and cmd+n quick-create when the form is open), create-progress overlay feedback for button/quick-create actions, branch-first progressive disclosure in git workspace creation, local-cached default name/branch suggestions, non-blocking branch option loading for fast form display, startup loading feedback for first app-open hydration, immediate startup hotkey availability, async startup reconciliation refreshes for responsive workspace switching, keyboard shortcuts (Return create, Escape cancel) with Create labels clean and Cancel labels showing (Esc), shared high-contrast primary create/save button styling, inline metadata editing (header title + branch/tooltip labels with Return save and Escape/outside-click cancel), protected main/master branch read-only behavior, git branch rename-on-edit behavior, settings overrides, ports, env vars, switching, focus tooltip overlays, sidebar hierarchy cues, and git signals.
Best for: Developers creating and configuring workspaces within projects.
Read PageWorkspace Lifecycle
Create, launch, ensure-running (`workspace up` with optional `--restart` and `--focus`), stop, restart, archive, and restore workspace behavior, including deferred setup during GUI create, launch waiting for setup completion, and optimistic archive removal in the GUI with archive-progress overlay feedback while cleanup runs in the background.
Best for: Developers managing multiple long-lived workstreams.
Read PageWindow Management
Capture and restore windows using yabai IDs with deterministic switching, plus iTerm2 session-aware terminal tab focus/cleanup, refresh-based terminal fallback title updates, clickable window cards in the Run tab and Dashboard, and a configurable iTerm2 focus pulse color (amber by default) to visually confirm which window was focused.
Best for: Users optimizing context switching and keyboard navigation.
Read PageProcesses
Configure process commands, runtime policies, logs, and restart behavior.
Best for: Teams running app servers, workers, and coding agents per workspace.
Read PageBrowser Sessions
Bind named URL sessions to workspace context so local routes and references reopen together.
Best for: Frontend and full-stack workflows that keep many task tabs open.
Read PageStatus Checks
Explain periodic health checks, stale-status avoidance, red unhealthy sidebar indicators, and on-fail restart behavior with clean stop-before-relaunch handling.
Best for: Developers who need fast health visibility before switching context.
Read PageDashboard
A Dashboard row at the top of the left panel opens an attention-items view in the right pane. It shows exited processes and failing status checks across all running workspaces, grouped by workspace and sorted most-recent-first. Items use the same window-row and status-check UI as the Run tab; shortcut badges are renumbered sequentially across the full view to avoid duplicates. A red count badge on the row updates automatically; an empty-state is shown when all workspaces are healthy.
Best for: Developers monitoring multiple concurrent workspaces who need a single place to spot failures.
Read PageKeyboard Shortcuts
Show global and workspace-level shortcuts for fast context switching and editor launch, including immediate global-focus behavior with deferred detail refresh.
Best for: Keyboard-first users and heavy multitaskers.
Read PageTroubleshooting
Common failure patterns with diagnosis and recovery playbooks, including additive database migration compatibility checks and transient SQLite lock handling guidance.
Best for: Anyone debugging launch, capture, process, or focus issues.
Read PageCookbook Guides
End-to-end project setup recipes for common stacks you can copy and adapt.
Best for: Developers looking for ready-made configuration examples for real-world projects.
Read PageCLI Reference
Complete mx command reference for managing projects, workspaces, config, settings, and worktree reconciliation (create missing, archive stale, refresh branches) from scripts and AI agent pipelines, plus contributor-focused automation hooks.
Best for: AI coding agents and developers who drive Muxy from the terminal or automated workflows.
Read Page