Installation

Codemux ships pre-built for Linux (AppImage / .deb / .rpm / AUR) and Windows (NSIS .exe). The AppImage and the Windows NSIS installer auto-update in-app; .deb, .rpm, and AUR installs update through their package manager instead. For source builds, see Build from Source below.

Windows users should also read the dedicated Windows Setup page for agent-CLI installation and known limitations.

Linux

AppImage (recommended — works on every distro)

# Grab the AppImage from the newest release without pinning a version:
curl -L "$(curl -sL https://api.github.com/repos/Zeus-Deus/codemux/releases/latest \
  | grep -o 'https://[^"]*\.AppImage')" -o codemux.AppImage
chmod +x codemux.AppImage
./codemux.AppImage

The AppImage is self-contained and bundles every runtime dependency. Drop it anywhere on your PATH (or use AppImageLauncher to integrate it with your menu and file associations).

In-app auto-update is wired through latest.json for the AppImage and the Windows NSIS build only (AUTO_UPDATABLE_FORMATS). Package-manager installs report format other and are told to update via their package manager.

The AppImage and your shell

An AppImage launcher rewrites LD_LIBRARY_PATH, PYTHONHOME, PATH and other loader variables to point inside the mounted bundle, so the app finds its bundled libraries. Every child process used to inherit them — which meant host binaries launched from a terminal inside Codemux linked against Codemux's bundled libraries instead of your system's. On a host with newer libraries than the bundle, that fails before the program even starts:

cargo: libssl.so.3: version `OPENSSL_3.5.0' not found

Fixed as of v0.17.1. Every child-spawn path — terminals, the agent daemon, workspace setup scripts, agent CLIs — now strips the bundle's own entries while keeping yours: path lists drop only bundle directories, and single values are cleared only when they actually point into the bundle. Distro packages (AUR, .deb, .rpm) were never affected; the fixup is a no-op there.

One consequence worth knowing if you write scripts: $APPDIR and $APPIMAGE are deliberately absent in any process Codemux spawns, so a codemux command run from a terminal pane cannot use them to detect the install shape.

Debian / Ubuntu

curl -L "$(curl -sL https://api.github.com/repos/Zeus-Deus/codemux/releases/latest \
  | grep -o 'https://[^"]*_amd64\.deb')" -o codemux.deb
sudo dpkg -i codemux.deb
sudo apt-get install -f   # install missing deps if any

Fedora / RHEL

curl -L "$(curl -sL https://api.github.com/repos/Zeus-Deus/codemux/releases/latest \
  | grep -o 'https://[^"]*\.x86_64\.rpm')" -o codemux.rpm
sudo rpm -i codemux.rpm

Arch (AUR)

yay -S codemux-bin
# or
paru -S codemux-bin

codemux-bin ships the prebuilt binary. If you prefer a from-source AUR package, watch for a codemux package; the canonical source build is documented below.

Always-current download links

Skip the version pin by hitting releases/latest directly:

• https://github.com/Zeus-Deus/codemux/releases/latest

GitHub redirects to the newest published release.

Windows

The NSIS installer is codemux_<version>_x64-setup.exe:

$url = (Invoke-RestMethod https://api.github.com/repos/Zeus-Deus/codemux/releases/latest).assets |
  Where-Object { $_.name -like "*x64-setup.exe" } | Select-Object -ExpandProperty browser_download_url
Invoke-WebRequest -Uri $url -OutFile codemux-setup.exe
.\codemux-setup.exe

After installation, see Windows Setup for the agent CLIs (Claude Code, Codex, Gemini, OpenCode, Pi) — those install separately on Windows the same way they do on Linux.

SmartScreen note: the installer is not Authenticode-signed yet. On first install, Windows SmartScreen warns "Windows protected your PC." Click More info → Run anyway.

Updates

Codemux self-updates through the in-app updater on Linux (AppImage) and Windows (NSIS). When a new release is available, you'll see a toast notification and an Update button in the title bar. The updater downloads the new binary, verifies its signature, and prompts you to restart.

Package-manager installs (.deb, .rpm, AUR) get updates through their respective package managers — re-run apt, dnf, or yay -Syu to refresh.

Build from Source

If you want to hack on Codemux itself, or if the prebuilt binaries don't fit your distro, building from source is straightforward.

Requirements

• OS: Linux (X11 or Wayland), Windows 10 1809+, or Windows 11
• Rust: current stable (CI tracks stable; no MSRV is pinned) (install via rustup)
• Node.js: 22 (the version release CI builds with) with npm
• Bun: 1.2.21+ (the version release CI builds with) (for the bundled Claude sidecar — install via curl -fsSL https://bun.sh/install | bash)
• System libraries: Tauri 2 dependencies for your distro

Linux system deps

Arch:

sudo pacman -S webkit2gtk-4.1 base-devel curl wget file openssl appmenu-gtk-module gtk3 libappindicator-gtk3 librsvg

Ubuntu / Debian:

sudo apt install libwebkit2gtk-4.1-dev build-essential curl wget file libssl-dev libayatana-appindicator3-dev librsvg2-dev

Fedora:

sudo dnf install webkit2gtk4.1-devel gcc-c++ openssl-devel curl wget file librsvg2-devel libappindicator-gtk3-devel

Build

git clone https://github.com/Zeus-Deus/codemux.git
cd codemux
npm install
npm run tauri build      # produces the desktop bundles

Note npm run build builds only the frontend bundle (tsc -b && vite build) — it does not produce a desktop binary.

For development mode with hot reload:

npm run tauri:dev

That starts Vite and the Tauri desktop window together. Plain npm run dev is Vite only — useful for browser-based UI work against the dev mock, but it does not launch the app. Dev builds use a separate data directory so they don't collide with an installed release on the same machine.

Verification

npm run verify

Runs cargo check, cargo test, tsc --noEmit, and vitest.

Optional Tools

These are not required but enable additional features:

• gh (GitHub CLI) — Enables pull request creation, CI checks, review comments on GitHub. See Pull & Merge Requests.
• glab (GitLab CLI) — The same for merge requests on GitLab, including self-hosted instances.
• claude (Claude Code CLI) — AI commit messages, merge conflict resolution, Claude-provider chat sessions.
• codex — OpenAI Codex CLI for Codex-provider chat sessions.
• opencode — OpenCode CLI for the federated multi-provider chat option (100+ upstream providers behind one rail entry).
• fd — Fast file search (Ctrl+Shift+P).
• ripgrep — Fast code search (Ctrl+Shift+F).
• ydotool — OS-level browser input for stealth automation (Tier 3). Requires ydotoold daemon running. Only needed for bypassing anti-bot detection.
• docker / docker compose — Container management for setup/teardown scripts.
• xdg-desktop-portal (+ a backend such as xdg-desktop-portal-gtk) or zenity — Native file pickers ("Open Project", attach file, settings import/export). Most desktop environments ship a portal already; bare window managers (i3, dwm, …) often don't, and without either backend file dialogs silently fail to open. Run codemux doctor to check. The AUR package already pulls the portal in as a dependency.

First Launch

1. Codemux opens with a login screen — sign in with GitHub or email, or click "Skip" to use it without an account (settings won't sync).
2. The empty-state Home shows quick actions: Open Project / New Project.
3. Open a project and create a workspace via the sidebar + button.
4. Press Ctrl+T for a terminal or Ctrl+Shift+D to split a pane; open a browser from the tab bar's + dropdown.

Agent Chat is enabled by default. To use the classic terminal-first interface instead, open Settings (Ctrl+,) → Personal → Interface, switch off Agent Chat GUI, then reopen Codemux.