App model

How people use Muxy: the apps, navigation, settings, and updates.

The apps

Every project knows which server it lives on, so the desktop app shows projects from several servers in one sidebar. Remote projects are marked with their server and path. There is no global "current server".

The Remote section at the bottom of the sidebar shows each remote server's state. Its popover adds servers (host, user, port, key file, or a password that Muxy asks for and keeps only in memory) and manages them. Add Project → Remote browses that server's folders. When a server lacks Muxy, a released app offers to install the same version there; when its version can't talk to the app, the section explains how to update it. Removing a server only forgets its projects in this app.

New Tab in Project… (⌘⇧N) lists local and remote projects. Picking one opens a tab there and switches workspace if needed; a remote server opens in its Home, connecting first if needed. Clicking a server in the Remote popover offers New Tab too.

Files and images dropped or pasted on a remote terminal, or sent from the composer, are copied to that computer and its path is pasted. Clicking a file path in a remote terminal offers a read-only copy here, or its path.

Each app keeps its own layout: tabs, splits, workspaces, and project order. Projects and terminals are shared. Several muxy windows can open the same terminal UI layout.

Navigation

flowchart LR
    FILTER["Workspace filter"] --> SIDEBAR["Project sidebar"]
    SIDEBAR --> PROJECT["Project"] --> TAB["Tab"] --> PANE["Focused pane"]

• The sidebar shows All projects by default. Pick a workspace to filter it. Home stays first and worktrees appear under their parent.
• One project order applies under every filter.
• Picking a project shows its tabs.
• A window has one focused pane. Closing it moves focus to a neighbor. Closing a tab moves focus to the next tab, or the previous one. Closing something in the background never steals focus.

Opening and restoring

• The desktop app restores all projects, tabs, and window state on launch. It never opens a tab by itself.
• The terminal UI opens one shell in Home the first time, then restores its layout.
• muxy <folder> opens the folder in the desktop app, selecting its project or adding one. Without the desktop app, or over SSH, it opens in the terminal UI.
• Existing Terminals lists a project's terminals that this app isn't showing, and which app owns each one. Opening one adds it to your layout.

Worktrees

New Worktree has a name, a new or existing branch, and Default, Template, or Folder location choices. Worktrees default to ~/.muxy/worktrees/<project>/<name>. Settings → General sets the global location; each project remembers its choice. Templates support {branch}, {base-dir}, and {project-name}.

Optional setup and teardown commands come from the source project's .muxy/worktree.json and $XDG_CONFIG_HOME/muxy/worktree.json (by default, ~/.config/muxy/worktree.json):

{ "setup": ["npm ci"], "teardown": ["docker compose down"] }

Review and enable commands when creating or removing a worktree; muxy worktree runs them only with --hooks. Setup runs per-machine commands first; teardown runs project commands first. Commands run in the worktree, with MUXY_PROJECT_PATH and MUXY_WORKTREE_ID, MUXY_WORKTREE_PATH, MUXY_WORKTREE_NAME, and MUXY_WORKTREE_BRANCH available. A setup failure keeps the new worktree; a teardown failure stops removal.

When things go away

The status bar shows the current project's server, with connect, restart, and stop.

Settings

• Settings is one window, separate from projects. It works while offline, and changes apply immediately.
• App preferences live in settings.toml, terminal preferences in terminal.toml, and custom themes in themes/.
• Every app shortcut can be changed in Settings → Keyboard. Terminal key bindings are set in Settings → Terminal, and the Quick Terminal shortcut has its own setting. Normal keystrokes in a terminal always go to the terminal.
• Settings → Appearance → App language picks the interface language. English is built in; other languages come from language-pack extensions, the same ones made for Muxy 1.x. Untranslated text stays English, and while the chosen pack is unavailable Muxy shows English.
• Server settings, such as the shell and history size, apply to this computer's server. muxy --host changes another computer's. Stopping or restarting it asks first.
• Settings → Mobile turns phone access on, shows a pairing code, and lists paired phones. muxy mobile does the same without the desktop app.
• Settings → Backup & Restore exports settings, themes, extension preferences, projects, and layouts. Restore applies on the next launch and keeps a recovery copy in Backups. Existing projects are kept; matching projects receive the saved layouts. Server settings take effect after restarting the server.
• Import supported 1.x settings and local projects from the installed app, a .muxy backup, or settings.json. Unsupported options are listed before import. A 1.x import adds to what is already there: existing projects, tabs, and workspaces are kept. A profile with no projects or workspaces yet imports the installed 1.x automatically, once, including its extensions. Profiles chosen with MUXY_DIR are left alone. Config files open in the system editor. Backups exclude live terminal sessions, paired-device credentials, extension packages, and project files. They keep the list of remote servers but not remote projects, which come back from their server.

Updates

flowchart TD
    UPDATE["Update available"] --> FITS{"Can the new version talk<br/>to the running server?"}
    FITS -->|"yes"| NOW["Installs now · terminals keep running<br/>server is replaced once no terminals are left"]
    FITS -->|"no"| CHOICE{"You choose"}
    CHOICE -->|"wait"| LATER["Installs once every terminal has ended"]
    CHOICE -->|"update now"| FORCE["Asks first · every terminal ends"]

When the new version can talk to the running server, checking Also restart the server in the update dialog replaces the server now too. Every terminal ends.

Desktop features

• Composer. Write a draft, with files, images, or dictation, and send it to the active terminal or to every visible split. Each project keeps its own draft, and a failed send keeps it.
• Web views. Extension pages as tabs, docked panels, popovers, or dialogs. They stay alive while hidden. Extension panels belong to a project: switching projects closes them, and switching back reopens them.
• Extensions. Add tabs, panels, a sidebar, toolbar and status bar items, shortcuts, and background scripts. They are managed in Settings → Extensions, declare their permissions, and ask before sensitive actions. Most extensions made for Muxy 1.x work unchanged; see the compatibility limits.
• Git and AI. For Git projects, the footer shows the branch and changes, commits and pushes with an AI-written message, and creates or manages pull requests. It uses an AI command-line tool you already have, chosen in Settings → AI.
• Tips. The sidebar shows a tip, picked at random on launch. Hide tips from the card or in Settings → Appearance.

AI agents

The server recognizes AI coding agents running in terminals and whether each one is working, waiting for you, or done.

• Tabs, worktrees, and projects show the state of their agents, and "waiting for you" comes first.
• The desktop app notifies you about agents in the background. Looking at the terminal clears the alert in every app.
• Detached terminals show no alerts, and no notification history is kept.