Product model

The things Muxy is made of, and who owns them.

The pieces

flowchart TB
    subgraph SERVER["Server · shared by every app"]
        PROJECT["Project"]
        WORKTREE["Worktree project"]
        SESSION["Terminal session"]
        PROJECT -->|"parent of"| WORKTREE
        PROJECT -->|"owns"| SESSION
    end
    subgraph APP["Each app · private"]
        WORKSPACE["Workspace"]
        TAB["Tab"]
        PANE["Pane"]
        TAB -->|"split into"| PANE
    end
    WORKSPACE -.->|"groups"| PROJECT
    TAB -.->|"belongs to"| PROJECT
    PANE -.->|"shows"| SESSION

Piece	What it is
Server	Runs on a computer. Owns projects, terminal sessions, and server settings.
Project	A folder on a server, with a name, color, and optional icon or logo.
Home	The built-in project for your home folder.
Worktree project	A Git worktree, shown under the project it came from.
Workspace	A group of projects in one app, used to filter the sidebar.
Tab	Belongs to one project and holds one or more panes.
Pane	One view in a tab: a terminal, a web page, or an extension view.
Session	A running terminal. Belongs to exactly one project.
Paired device	A phone allowed to connect to the server.

Shared or private. Project names, icons, colors, and deletions reach every app. Tabs, layouts, workspaces, and project order stay in the app that made them.

Projects

A project is an identity that points to a folder. Two projects can point to the same folder. They share its files but are otherwise separate.
A new project is named after its folder. Its name, icon, logo, and color can be changed.
If the folder disappears, the project shows as failed and can only be deleted. An offline server does not make its projects fail.
Changing directory inside a terminal never moves it to another project.

Home

Every server has one Home project for the user's home folder. Quick Terminal and other one-off terminals live there. Home is always first in the sidebar. It can't be deleted, have worktrees, or join a workspace. A remote server's Home goes by the server's name and is listed only under Remote Servers.

Workspaces

A workspace is a named filter for the sidebar. A project can be in no workspace, one, or several, and a workspace can be empty. Deleting a workspace never touches its projects. Remote Servers is a fixed workspace, offered once a remote server has connected, that lists each remote server's Home.

Worktrees

A worktree project is a child of a normal project, pointing to a Git worktree's folder. You can create one from a branch or add a worktree that already exists. It takes the branch name and its parent's color, and has its own tabs. Worktrees can't have children of their own.

Worktrees made outside Muxy show up automatically. A new project shows worktrees only if its repository already has some; turn them on or off from the project menu.

After a worktree is deleted outside Muxy, its entry is removed automatically if it has no tabs in this app and no terminal history.

flowchart LR
    PARENT["muxy<br/>~/code/muxy"] --> FEATURE["feature-x<br/>~/code/muxy-feature-x"]
    PARENT --> FIX["fix-login<br/>~/code/muxy-fix-login"]

Deleting

Deleting always asks first and explains what will end.

You delete	What happens
A project	It disappears from every app and its terminals end. Files stay on disk.
A worktree project	The same, and its worktree folder is removed too.
A project with worktrees	Its worktree projects are deleted too. Their folders stay on disk.
Home	Not allowed.

Tabs and panes

A project can have any number of tabs, including none.
A tab splits into panes, side by side or stacked, as deep as you like. Closing its last pane closes the tab.
Drag a tab to an edge of the content to show it beside the others in a new group. Each group has its own tab strip.
Closing a group's last tab removes the group.
Tabs can have a custom title and color, and can be pinned. Pinned tabs stay first and can't be closed until unpinned.
A terminal's title is the one its program sets, otherwise the running program's name, otherwise its folder.
New terminals open in the project's folder, or optionally in the folder of the pane they were split from.
Terminals support selection, copy and paste, search, links, the mouse, input methods, and shell integration: jump between prompts and select a command's output.

Project layouts

Named layouts live in .muxy/layouts/ inside a project or worktree. Use YAML, YML, or JSON files; the filename is the layout's name. Choose Apply Layout… from the project menu or the layout button in the top bar. Layouts are never applied automatically. Confirmation replaces that project's tabs in this app; terminals still shown by another app keep running.

layout: horizontal
panes:
  - tab:
      name: editor
      command: nvim .
  - layout: vertical
    panes:
      - tab: npm run dev
      - tab:
          name: shell

horizontal means side by side; vertical means stacked. Splits can be nested. A leaf's tab is a command string or an object with optional name and command. Commands run in the project folder; a command list is joined with &&. Legacy tabs lists keep their extra entries as separate top-level tabs.