Installation

Install Codemux from a pre-built release on Linux or Windows, or build from source.

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 are told to update via their package manager instead — see Updates.

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 checks for a new release in the background every 4 hours. Settings → About → Updates shows the current status and a Check for updates button, and the bottom strip of the sidebar footer's gear Menu shows the running version next to Up to date, Update available, Downloading…, Restart to update, or Retry update.

AppImage and Windows installer

These update in-app. When a release is available, a toast offers Install & Restart and What's new (the release notes). The updater downloads the new binary, verifies its signature, and shows its progress; the Update ready toast then offers Restart Now or Later. After Later, the gear menu keeps Restart to update available until you restart.

If a download or restart fails, the toast stays up as Update failed with the reason, plus Retry (re-runs the step that failed), Download manually (opens the release page), and Dismiss. The gear menu reads Retry update, with the reason in its tooltip.

When paired remote devices are connected, the toast warns that restarting will briefly disconnect them. A paired browser gets its own Desktop update available toast with Update & restart desktop, and only hears about updates the desktop can install in place.

Package-manager installs

The in-app updater can't replace a .deb, .rpm, or AUR install, so Codemux doesn't try:

AUR — Codemux detects that pacman owns the binary, and the toast reads "Codemux was installed with pacman, so update it from a terminal:" with yay -S codemux-bin and a copy button (paru works the same way).
.deb / .rpm — the toast says to update with the package manager you installed it with, with a Download button for the release page. Re-run apt or dnf to refresh.

On these installs, Update available in the gear menu and Open release page in Settings → About both open the release page instead of starting a download.

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

Codemux opens with a sign-in screen — connect your ChatGPT plan for Codex, sign in with GitHub or email to sync settings, or click Continue locally with another provider to use it without an account (settings won't sync). See Authentication.
The empty-state Home shows quick actions: Open Project / New Project.
Open a project and start a chat with the sidebar New agent button (Ctrl+N).
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+,) → Agents → Interface, switch off Agent Chat GUI, then reopen Codemux.

On this page