> ## Documentation Index
> Fetch the complete documentation index at: https://shux.coder.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Mux compatibility

> Upgrade, downgrade, storage, command, environment, and deep-link compatibility during the Shux rename

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

| Surface               | Canonical                          | Compatibility alias                                       |
| --------------------- | ---------------------------------- | --------------------------------------------------------- |
| npm package           | `@coder/shux`                      | `mux` forwarding package                                  |
| CLI                   | `shux`                             | `mux`                                                     |
| Local data            | `~/.shux`                          | `~/.mux` and older `~/.cmux` links                        |
| Development data      | `~/.shux-dev`                      | `~/.mux-dev` link                                         |
| Electron user data    | platform app-data directory `shux` | sibling `mux` link                                        |
| Environment variables | `SHUX_*`                           | `MUX_*`; `CMUX_ALLOW_MULTIPLE_INSTANCES` is also accepted |
| Deep links            | `shux://`                          | `mux://`                                                  |
| Release artifacts     | `shux-*`                           | matching `mux-*` aliases                                  |

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.

<Warning>
  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.
</Warning>

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.