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 / Off / Setup needed / Repair needed
• Last sync — relative time ("3 minutes ago")
• Sync now — manual trigger
• Export skills… — write all current skills to a .zip for backup
• Import skills… — restore from an export
• Forgot password / reset sync… — destructive reset flow (forces export-or-explicit-skip before wipe)

OAuth users get a one-time "Set sync password" form here on first device. Email/password users have sync configured automatically from the sign-in flow.

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 workspace in editor: Ctrl+Shift+E

Terminal

• Default shell — Uses $SHELL by default
• Scrollback — Terminal scrollback buffer size
• Cursor style — Block, underline, or bar
• Canvas rendering — Avoids WebGL context limits when many terminals are open

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.

• Create / Edit / Delete — Add presets with custom names, icons, and commands
• Multiple commands — Each preset can run several commands in sequence
• 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

• AI commit messages — Model override for the commit message generator
• Merge conflict resolver — CLI tool selection (Claude Code, Codex, OpenCode), model override, strategy (smart merge, keep both, prefer my branch, prefer target)

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 — all running the same provision_serve path that restarts the systemd unit, so the running daemon switches to the new binary immediately (not at the next host reboot):

• 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.
• 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.

All Settings Sections