Settings

Open settings from the command palette (Ctrl+K > "Open Settings"), the sidebar footer's gear Menu → Settings, 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.

Interface

The Agent Chat GUI is Codemux's default interface. It includes the native Agent Chat pane, multi-provider model picker, Skills Sync, MCP host runtime, Attachments, and lazy workspace creation.

Open Personal → Interface to switch back to the classic terminal-first UI, or turn the GUI on again later. The switch updates the two underlying feature flags (enable_agent_chat and enable_lazy_workspace_creation) together, then closes Codemux. Reopen the app to apply the change; a deliberate opt-out is remembered on that device.

Sync

Open Account → Sync for the Skills Sync panel:

• Sync ready — the status row (also reads Syncing… or Sync error), or a sign-in hint when you're signed out
• Last sync — relative time ("3 minutes ago")
• Sync now — manual trigger
• Export skills locally — write all current skills to a JSON file for backup
• Import skills from backup — 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 supported user roots (~/.codemux/skills/, ~/.claude/skills/, ~/.codex/skills/, ~/.agents/skills/, ~/.opencode/skills/, ~/.config/opencode/skills/) and the matching project roots. 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 Servers

The MCP Servers 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 the Agent Chat GUI is enabled, the Permissions section lists every tool-permission rule the agent honors — the allow, deny, and ask rules read from your settings.json files. Rules are grouped by scope so you can see where each one lives:

• User — ~/.claude/settings.json (applies everywhere)
• Project — <project>/.claude/settings.json (shared, committed)
• Local — <project>/.claude/settings.local.json (this machine only)

Each rule shows the tool name, its pattern, its behavior, and a remove button; removing one rewrites only the file that owns it. New rules are added as you work (for example clicking "Always allow" on an approval prompt, or editing the files by hand) — this panel is for reviewing and pruning them.

Account

The Account section shows your profile information:

• Email and Name — the account this machine is signed into, however you signed in
• Sign out — Clears your token and settings cache

Appearance

Typography sits at the top of this section — font families and sizes for the interface, conversation, code, and terminal. See Themes & Typography.

• Border radius — a read-only reference value, fixed across themes so a palette can't change the app's geometry.
• Resource monitor — Show the CPU/memory monitor in the title bar. Synced across devices.

Theme

One palette drives the app shell, terminal ANSI colors, chat code, and the file editor. Themes are picked from the command palette (Ctrl+K, then type a theme name) rather than from a grid here — the whole app repaints as you arrow through the list. This row states what's on and gives you Change (reopens the palette on the Themes group) and Customize (opens the theme studio).

Five dark themes ship built in, and you can generate your own from two colors or import one from VS Code, shadcn/Tailwind, or a .codemux-theme file. Your selection and your custom themes sync between devices. See Themes & Typography.

Two display settings sit under the same subsection:

• Density — Comfortable (default) or Compact, which tightens card padding, grid gaps, and group rhythm everywhere.
• Wrap code in chat — Sets the default for horizontal wrapping in Agent Chat code blocks. Off keeps lines intact behind a horizontal scrollbar; each code block can override it from its own header.

The earlier Color palette toggle (Cool / Warm) is gone — those are now the Graphite and Warm Stone themes, picked the same way as any other.

Sidebar

Controls for the workspace inbox:

• Show git stats — show the ↑ahead and +/− diff numbers on workspace cards. The branch name always shows. Default on.
• Auto-settle idle work — sweep a workspace card into the Settled section after this many days without agent activity: Off / 1d / 3d / 7d / 14d, default 3d. A card whose PR merges or closes settles once it has then been idle for an hour, so returning to it for a review comment doesn't snap it out of sight while you're still reading. Un-settling a card pins it active — auto-settle won't touch it again until its agent actually runs.

Scrolling

• Smooth scrolling — Animate mouse-wheel scrolling instead of jumping straight to the new position. Off by default: with a high-resolution or free-spin wheel the animation falls behind, so scrolling faster actually moved the page slower. Applies immediately, no restart. Linux desktop only (it drives a webview setting), and machine-local — not synced.

On Linux, scrolling across the whole app — chat transcript, sidebar, menus — is GPU-accelerated. If accelerated startup repeatedly fails on a machine, Codemux automatically falls back to the older compatibility rendering mode.

Agents

Controls the orb shown wherever an agent is running — sidebar cards, thread turns, subagent rows, and the composer.

• Match the orb to the activity — the orb's motion changes with what the agent is doing: searching the repo, writing files, running a build, talking to GitHub, resolving a conflict, waiting on you. Turn it off to show the same neutral working orb everywhere. On by default; a live two-row preview sits under the toggle.

The orb is always monochrome — white ink on dark themes, black on light — and picked automatically, so there is no color setting. Red stays reserved for "needs a human", which the sidebar still shows as a red dot rather than an orb.

The earlier Working indicator glyph picker (braille / ring / blink / sweep / typing) and its six-color Indicator color swatch row were replaced by the orb. Any values you had saved are simply no longer read.

Editor

• Default editor — Choose which external editor to use when opening files from the file tree panel. 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

• Cursor style — Block, underline, or bar
• Font — a pointer row with an Open Appearance button; terminal font family and size are set under Appearance → Typography alongside the other surfaces
• Color theme — where the terminal's 16 ANSI colors come from: Match app theme or System (Omarchy)

Rendering needs no setting: a startup probe picks the WebGL renderer only where GPU acceleration is verifiably a win and the DOM renderer everywhere else, and falls back to DOM automatically when the GPU context is lost or WebGL2 is unavailable. See Renderer for which case your machine lands in.

Scrollback size lives under Session Restore, not here.

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, and pick which agent writes them. Claude, Codex, and OpenCode are all supported.
• Agent — Which AI agent (and model) generates commit messages.

A Merge Conflict Resolver subsection sits below it with its own Agent and Strategy rows.

Source Control

Codemux reads pull and merge requests through each product's own command-line tool. This section is where you check that tooling is installed and signed in, and where you tell Codemux which product a self-hosted server runs. See Pull & Merge Requests.

Providers

Codemux drives each product through its own CLI, using the credentials that tool already holds — nothing is stored here. Four rows, always in the same order:

Each served row shows the CLI's version line, a masked account you can click to reveal, and a Serves … line built from what that provider actually supports (GitHub adds deployments; GitLab does not). When something is missing, one fix line appears — install beating sign-in — such as Install glab from gitlab.com/gitlab-org/cli or Run glab auth login. Rescan re-probes; otherwise the probe runs when you open the section.

Bitbucket and Azure DevOps rows stay visible but dimmed, so you can see they're recognized and not yet integrated.

Self-hosted servers

Tell Codemux which product a server runs when its hostname doesn't say. Everything else is detected automatically.

• Add self-hosted server — enter a Hostname (e.g. git.acme.internal) and pick what it Runs: GitHub or GitLab.
• The field accepts a pasted clone URL, user@host, or a bare hostname and normalizes it for you.
• Mappings sync across your devices and take priority over automatic detection. Empty by default.

A host that already contains github or gitlab in its name (gitlab.acme.com) is detected without a mapping — you only need this for neutral domains.

Links

• Open pull request links in the browser — Off by default, which means a link to a pull request in a project you have open goes to the Pull Requests page instead of your browser. Shift-click always goes to the browser either way.

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
• 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 is created, and on an explicit Re-run Setup (e.g., npm install, docker compose up -d)
• Teardown scripts — Commands that run when a workspace is deleted (e.g., docker compose down)

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

Browser

Settings for the built-in browser pane.

• Default viewport — The size new browser sessions start at: Default (1280×800), Full HD (1920×1080), QHD (2560×1440), or 4K (3840×2160). A custom WxH set from the CLI is shown as-is. This is also the size the agent's background browser is pinned to when Desktop-size background browser is on. Synced across devices.
• Profile storage — A readout of how much disk the browser profile currently uses.
• Clear cookies & site data — Signs you out of sites but keeps cache and preferences.
• Clear all browser data — Wipes the entire profile.

Per-session overrides are available from the CLI and MCP — see Viewport Presets.

Session Restore

• Enable session restore — Restore terminal scrollback and pane layout when a workspace reopens. See Session Persistence.
• Scrollback lines — How much history to keep per terminal, 1,000–50,000.
• Max disk usage — Cap on total scrollback stored on disk, 10–500 MB.

Shortcuts

Every keyboard shortcut grouped by category, each row rebindable — record a new combo, override a conflict, or reset one or all back to defaults. 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 — Available while the Agent Chat GUI 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.
• Desktop-size background browser — Available while the Agent Chat GUI is enabled. Starts the agent's background browser at a real desktop viewport — the Browser section's Default viewport, 1280×800 out of the box — instead of matching the small peek overlay, so the agent sees desktop CSS breakpoints rather than mobile ones. The peek scales the larger frame down to fit. On by default; synced across devices — see Background Browser.
• Per-turn revert checkpoints — Snapshots the workspace before each supported turn so Revert can rewind files, the provider conversation, and the transcript together. Off by default, and currently Codex only — see Per-Turn Revert Checkpoints.
• Utility agent — One inexpensive default used for conversation handoffs and other lightweight generation. Automatic prefers a small, cheap model. Without one, handoffs still work but arrive as raw transcripts rather than summaries.

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

Usage

Token and cost accounting for every agent session on this machine, read from your agent CLIs' own local history — including sessions Codemux didn't launch. See Usage.

The section appears while the Agent Chat GUI is enabled.

Notifications

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

Devices (Hosts)

The Devices 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 device 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. Choosing a host records the workspace's destination; after creation, use Push to host from the workspace menu or the Workspaces Overview to transfer its files, restart its panes remotely, and attach the UI through the SSH tunnel.

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