Skip to main content
Shux is the canonical product, package, command, protocol, and local data-directory name. The rename keeps old Mux entry points connected to the same implementation and data so existing users can upgrade and later downgrade without copying state by hand.

​
Canonical and legacy names

When both a SHUX_* variable and its MUX_* alias are set, the SHUX_* value wins and is mirrored to child processes under both names.

​
Local data migration

On startup, Shux performs one non-destructive directory transition before configuration or sessions are loaded:
  1. If only ~/.mux exists, it is moved to ~/.shux.
  2. ~/.mux is recreated as a directory link pointing to ~/.shux.
  3. The older ~/.cmux name also points to ~/.shux.
  4. Development builds apply the same behavior to .mux-dev and .shux-dev.
Older Mux binaries therefore read and write the canonical Shux directory after a downgrade. Writes through either path are immediately visible through the other path. On Windows, Shux uses a directory junction so the alias normally works without Developer Mode or administrator privileges. On macOS and Linux, it uses a directory symlink.
If ~/.shux and ~/.mux are independent existing directories, Shux does not merge, replace, or delete either directory. It reports the conflict and keeps the canonical directory active. Resolve the contents manually before relying on downgrade compatibility.If ~/.shux exists but is not a usable directory (for example a regular file or broken symlink), Shux leaves that entry unchanged and falls back to the first healthy leftover tree. Transition activePath is never that unusable entry, so desktop userData is not pointed at a file.
Explicit SHUX_ROOT or MUX_ROOT locations are never moved. Shux makes both variable names resolve to the same configured path instead.

​
Desktop state and downgrades

Electron state such as window position, browser storage, and local preferences is moved from the platform mux app-data directory to shux, then the old directory name points forward. The stable application identifier remains com.mux.app during the transition so operating-system updater and uninstall identity does not fork. The supported flow is sequential: close one version before launching or installing the other. Running old Mux and new Shux processes concurrently against the same sessions is not supported. A manual macOS DMG downgrade may replace or coexist with shux.app as Mux.app, depending on where the user drags the bundle. The packaged directory is shux.app even though the display name is Shux. The shared data links preserve state, but Shux cannot create a system-wide /Applications/Mux.app alias without installation privileges. Windows and Linux installers likewise preserve data even when shortcut or executable filenames change.

​
Compatibility names that intentionally remain

Some names are persisted protocols or externally managed infrastructure rather than display branding:
  • Project-controlled .mux/ hooks, agents, skills, plugins, and .muxignore
  • Provider/config identifiers such as mux-gateway
  • Internal persisted keys and extension IDs under mux.*
  • The VS Code Marketplace extension identity coder.mux
  • The stable desktop application ID com.mux.app
  • GitHub releases, documentation, Gateway, and OAuth URLs on existing mux domains
  • Docker storage at /var/mux
  • Existing SSH-host global storage at ~/.mux; local startup cannot safely migrate arbitrary or offline hosts
New user-visible labels use Shux even when one of these compatibility identifiers remains underneath.

​
Compatibility implementation ownership

Transition-only behavior is intentionally concentrated in:
  • src/common/compat/legacyMux.ts for names, environment aliases, and accepted protocols
  • src/node/compat/shuxTransition.ts for directory moves and forward links
  • packages/mux-compat/ for the published legacy npm command
  • scripts/create-legacy-mux-artifact-aliases.sh for release filenames
Canonical production code should not add new one-off mux fallbacks elsewhere. These boundaries can be removed together only in a release that explicitly ends downgrade support and after external package, URL, extension, remote-runtime, and persisted-key compatibility is no longer required.