Settings

Open settings from the command palette (Ctrl+K > "Open Settings"), the sidebar gear icon, or press Ctrl+,.

Settings Sync

Most personal settings sync across devices via your Codemux account. When you sign in, your settings are pulled from the server. Changes you make are saved both locally and to the cloud. If you're offline, changes are cached locally and synced when you reconnect.

Machine-local settings (sidebar state, window layout, terminal presets, project scripts) stay on the current machine.

Beta Features

Codemux's newest surfaces ship behind a master Beta toggle. Open Beta Features in Settings to flip them on:

• Enable Agent Chat — turns on the Agent Chat (Beta) pane, the multi-provider model picker, Skills Sync, the MCP host runtime, Attachments, and lazy workspace creation. Two underlying feature flags (enable_agent_chat and enable_lazy_workspace_creation) flip together.

Toggling Beta Features triggers a clean quit and restart so the data flag flip lands cleanly. The legacy main-branch experience is preserved when Beta is off.

Sync

Open Account → Sync for the Skills Sync panel:

• Sync state — On (signed in), or a sign-in hint when you're signed out
• Last sync — relative time ("3 minutes ago")
• Sync now — manual trigger
• Export skills… — write all current skills to a JSON file for backup
• Import skills… — restore from an export

Skills are stored server-side, so any signed-in account is sync-ready immediately — no sync password, including for GitHub OAuth accounts. (There's no "reset sync" step because there's no device key to lose.)

Skills

The Skills section lists every skill discovered across the four watched directories (~/.codemux/skills/, ~/.claude/skills/, ~/.codex/skills/, ~/.opencode/skills/). Per skill you can:

• View the rendered SKILL.md in a modal
• See its compatibility badges (which providers, which scopes)
• Enable / disable the skill (disable is local-only and doesn't sync)

MCP

The MCP section lists every MCP server Codemux discovered across Codemux / Claude / Cursor configs. Per server you can:

• See the status badge (running / failed / disabled) and tool count
• Enable / disable the server
• Click "View tools" to inspect each tool's description and JSON schema

The 50-tool cap warning surfaces here too. See MCP Servers.

Permissions

When Agent Chat (Beta) is on, the Permissions section lists every "Allow always" rule you've persisted from tool approval prompts. Each rule shows the tool name, the rule pattern, and a remove button. Per-tool body rendering matches what the chat pane shows during the approval prompt.

Account

The Account section shows your profile information:

• Signed in via GitHub — Shows your GitHub email and display name
• Email/password accounts — Shows your email
• Sign out — Clears your token and settings cache

Appearance

• Theme — Syncs with Omarchy system theme automatically. Falls back to a Tokyonight-inspired dark theme.
• Accent colors — Success, danger, warning, and attention colors derived from the system palette.
• Terminal colors are fully theme-reactive (16 ANSI colors + foreground, cursor, selection).

Editor

• IDE selector — Choose which external editor to use when opening files. Codemux auto-detects installed editors (VS Code, Cursor, Zed, etc.).
• Open a workspace in your editor from the title-bar launcher or the Open in editor entry in the sidebar context menu.

Terminal

• Default shell — Uses $SHELL by default
• Scrollback — Terminal scrollback buffer size
• Cursor style — Block, underline, or bar

Rendering needs no setting: terminals use the WebGL renderer and fall back to the DOM renderer automatically when the GPU context is lost or WebGL2 is unavailable.

Git

• Default base branch — Used when creating feature branches (defaults to main)

AI Tools

• AI commit messages — Enable/disable the sparkle button next to the commit input. Requires Claude CLI.
• Model override — Specify a model for commit message generation, or leave empty for the CLI default.

Merge Conflict Resolver

• Enable — Show the "Resolve with AI" button in the Conflicts section
• CLI tool — Claude Code, Codex, or OpenCode
• Model override — Specify a model or leave empty
• Strategy — Smart merge, Keep both, Prefer my branch, or Prefer target

Presets

Manage terminal presets — saved agent configurations for one-click launch.

• New preset — The New preset button (in the Presets header, and the preset-bar gear menu) opens an unsaved draft that's persisted only when you click Create preset.
• Preset type — A draft can be one of two types, switched with the Type toggle in the editor:
  • Agent launcher (structured) — Build a named launcher by picking an agent, a model + reasoning (the same model pickers as the workspace-creation dialog, shown for Claude / Codex / OpenCode / Gemini), and an optional prompt that becomes the agent's first instruction. The model/reasoning ride alongside the command and are applied at launch, so a preset and a dialog launch with the same picks produce identical commands. Example: a "Git Pull" preset that launches Claude with Opus + High reasoning and a canned prompt.
  • Raw command — One or more literal shell command lines (the original model). Each preset can run several commands in sequence.
• Create / Edit / Delete — Custom presets carry a name, icon, and either a structured config or raw commands. Built-in presets can be edited and unpinned but not deleted.
• Launch mode — New tab or split pane
• Keystroke driver — Mark a preset as Human (inherits host DISPLAY/WAYLAND_DISPLAY — use for shells, build scripts, dev servers you drive yourself) or Agent (strips desktop env so AI tool calls can't pop windows on your real desktop). Built-in agent presets (Claude Code, Codex, OpenCode, Gemini, Pi) are always Agent; the Shell preset is always Human; custom presets default to Human and can be flipped. See Display Isolation for details.
• Auto-run — Optionally run on workspace creation or new tab
• Pin to preset bar — Toggle "Show in preset bar" for quick access
• Working directory — Override the default CWD per preset

Projects

Configure per-project settings for workspaces.

• Run command — The dev command executed by the Run button (Ctrl+Shift+G). Set it here or via .codemux/config.json.
• Setup scripts — Commands that run automatically when a workspace opens (e.g., npm install, docker compose up -d)
• Teardown scripts — Commands that run when a workspace closes (e.g., docker compose down)

Settings configured here are stored in the database. File-based config (.codemux/config.json) takes precedence when present.

Shortcuts

A read-only reference of all keyboard shortcuts grouped by category. See Keyboard Shortcuts for the full list.

Agent

• Auto-configure MCP for workspaces — Automatically write .mcp.json so agents discover Codemux tools. Disable if you manage MCP config manually.
• Checkpoint before agent runs — Shown when Agent Chat (Beta) is enabled. Snapshots the working tree in the background when a chat session starts so you can roll back everything the run changed — see Run Checkpoints. Synced across devices.

AI commit messages and the merge conflict resolver are configured under Git above.

Notifications

• Sound — Toggle notification sounds on/off
• Desktop notifications — Toggle desktop notifications on/off
• Notifications use the system notification daemon (notify-rust)

Hosts

The Hosts section is where you register the remote machines you want to run workspaces on. Codemux talks to remote hosts over plain SSH — there are no credentials in the app and no Codemux server in the middle. Authentication uses your existing ~/.ssh/config, ssh-agent, and known_hosts.

The pane has two parts:

• Sidebar — All registered hosts grouped by Online / Offline. Click Add host at the bottom to register a new one (just a friendly name + an SSH target like user@hostname).
• Detail pane — Edit the selected host's name or target, run Test connection, or remove it.

Test connection

Runs a non-interactive ssh -o BatchMode=yes probe that reports one of three outcomes:

Install codemux-remote

When a host needs the helper binary, the Install button opens a consent modal that names the binary, says it's a small static executable installed to ~/.local/bin in your user account (no root, no system changes), and links to the source. On confirm, Codemux uploads the right binary for the host's architecture (over an SSH cat > path pipeline that works correctly with modern OpenSSH 9.0+) and re-probes to verify.

After a successful install, Codemux also automatically provisions the headless codemux-remote serve daemon on the host:

1. Writes ~/.config/systemd/user/codemux-remote.service.
2. Runs loginctl enable-linger so the daemon survives logout and reboot.
3. systemctl --user enable + restart codemux-remote so the daemon picks up the freshly-installed binary (restart is idempotent on first install — same as a clean start).
4. The daemon writes a manifest with its endpoint + a 32-byte bearer secret to ~/.local/share/codemux-remote/manifest.json (mode 0600).

Any MCP-aware agent on that host can then point its config at codemux-remote mcp and immediately drive Codemux locally — no further setup. Push a workspace from your desktop and the daemon also drops a .mcp.json in the workspace dir so agents started there auto-discover Codemux without any config file edits.

Upgrades

When you update Codemux on your desktop, hosts auto-upgrade on three triggers, each of which re-uploads the new binary and switches the running daemon over to it:

• App start — a background task ~5 seconds after Codemux launches walks every registered SSH host, probes its codemux-remote version, and silently re-bootstraps any host that's behind. Per-host 30s timeout so an offline host doesn't block the poll. This is the "I update Codemux and my hosts catch up on their own" path. It will not interrupt your host-side work: restarting the host daemon would kill any agents you have running directly on that host (the "work on a host without pulling" flow), so when the host reports live sessions the new binary is uploaded but the restart is deferred — it activates on the next upgrade while the host is idle, or after a host reboot. (Workspaces you pushed from your desktop are unaffected either way — their agents run in a separate process.)
• Test connection — if the host's codemux-remote version differs from the one bundled with your desktop Codemux, Test reports v<old> on host, v<new> bundled — Install to upgrade and the Install button re-runs the install path.
• Push workspace — every push first checks the host's version. If it's older than the bundled one, the binary is re-uploaded and the serve daemon is restarted before the push continues.

The background poll only upgrades existing installations — it never installs codemux-remote on a host that doesn't already have it. Fresh installs always go through the Install button so consent is explicit.

Picking a host for a workspace

Wherever you start a new workspace (the New Workspace dialog) you'll see a Device Picker pill in the dialog's bottom bar — defaults to Local Device, with a submenu listing every host you've registered here. The actual workspace-push action is being wired separately.

Connection health

A workspace running on a host stays connected over an SSH tunnel. If that tunnel drops — your laptop sleeps and wakes, your Wi-Fi flaps — the workspace would otherwise just look frozen with no explanation. Its sidebar row now shows what's happening:

• Reconnecting… (amber) — the tunnel dropped and Codemux is automatically retrying. This usually clears on its own once the network is back.
• Connection lost — re-push (red) — reconnection has repeatedly failed and Codemux has given up retrying. Push the workspace to the host again to re-establish it.

Local workspaces, and remote workspaces with a healthy tunnel, show no pill.

All Settings Sections