Projects

What Is a Project?

A project points to a local directory. Muxy detects whether the directory is a Git repository and adjusts workspace behavior accordingly.

• • Git detection runs when a project is added and at application startup.
• • Project configuration can be shared across machines.

Project Settings

• • Directory — the project folder. The display name is inferred from the directory name.
• • Setup script — a shell script that runs once when a new workspace is created (e.g. copy environment files into a worktree).
• • Stop script — a shell script that runs whenever a workspace is stopped (including restart and archive), after processes are terminated.

Project Templates

Projects define templates that are copied into each workspace on creation. After creation, each workspace maintains its own independent overrides.

• • Processes — commands to run in terminal windows (servers, workers, coding agents).
• • Status Checks — health commands that run at intervals and update status indicators.
• • Browser Sessions — URLs opened in Chrome at workspace launch and tracked for focus cycling.
• • Port Definitions — named env vars (e.g. `FRONTEND_PORT`, `API_PORT`) that receive reserved port numbers per workspace.

Adding a Project

Add a project by pointing to a local directory or providing a Git repository URL. Git URLs are cloned into a Muxy-managed location.

• • On add, Muxy checks whether the directory is a Git repo and creates a default workspace automatically.
• • You can then configure processes, status checks, browser sessions, and port definitions.

Default Workspace

Every project gets a non-archivable default workspace created automatically.

• • Git projects — default workspace corresponds to the `main` or `master` branch.
• • Non-Git projects — default workspace corresponds to the project directory itself.
• • The default workspace cannot be archived.

Removing a Project

• • Removing a project cleans up related workspaces and workspace directories.
• • For Git projects cloned by Muxy, the cloned directory is also removed.
• • Projects pointing to directories you manage yourself are never deleted from disk.