Settings

Open settings from the command palette (Ctrl+K > "Open Settings"), the sidebar footer's gear Menu → Settings, or press Ctrl+,.

The command palette also jumps straight to a page: type settings to list every Settings page, settings git to narrow them, or a row name such as scrollback to land on the page that holds it (Session Restore).

Finding a Setting

Search

A Search settings field sits at the top of the left nav. Press Ctrl+F anywhere in Settings, or / when you're not typing in a field, to focus it.

Search matches every row and page by its label and by common synonyms, and groups the results by page. A result found through a synonym says so — Matches keyboard under Shortcuts, for example. Every word you type has to match, so git stats and appearance orb narrow the way they read. Use the arrow keys to move through results and Enter to open one: Settings switches to that page, scrolls the row into view, and highlights it briefly. Escape clears the query (a second Escape leaves Settings).

Search only shows what the page would: rows that need the Agent Chat GUI, a signed-in account, or the desktop app are left out when they wouldn't render.

Navigation groups

The nav is grouped by what a page is about:

Permissions, Skills, and Usage appear only while the Agent Chat GUI is on (it is by default). At narrow widths the nav becomes a section picker, without the search field.

The header shows Settings / <page>, and a Pin to footer button adds the current page to the sidebar footer (Unpin from footer removes it). Escape closes one layer at a time: an open menu, dialog, or sheet closes first, and Escape inside a text field doesn't leave Settings.

Saving and Sync

Most settings save the moment you change them. Text fields save when you leave them — Default base branch on blur or Enter, the Projects script fields on blur (with a brief Saved note) — and sliders save once, when you let go.

Settings fall into two kinds:

• Synced — saved to your Codemux account and applied on every device you sign into. A status next to the page title reports each change: Saving…, then Saved; Offline. Saved on this device, will sync when the server can't be reached (it syncs on reconnect); or Couldn't save.
• This device only — rows marked with a small monitor icon (tooltip: "Only on this device. Not synced to your account.") stay on the current machine.

Sync requires being signed in; see Authentication. The table at the end lists what syncs, page by page.

Account

When signed in:

• Email and Name — the account this machine is signed into, however you signed in.
• Skills sync — the Skills Sync panel (shown while the Agent Chat GUI is on):
  • Sync ready — the status row (also reads Syncing… or Sync error)
  • Last synced — 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
• Session → Sign out of Codemux — clears your token and settings cache.

When you're offline, the sync status row gives way to a single line — "Offline — using your cached settings. Changes will sync when the connection returns." — and syncs on its own once you reconnect. A non-network failure still shows Sync error with a Retry button. Skills are stored server-side, so any signed-in account is sync-ready immediately — no sync password, including for GitHub OAuth accounts.

When you're using Codemux without an account, the page says "You're using CodeMux locally. Connect a CodeMux account to sync across devices; your ChatGPT connection stays separate." with a Sign in for sync button that opens the sign-in screen.

Appearance

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

• Resource monitor — Show the CPU/memory monitor in the title bar. Synced.
• Reduce motion — Stop looping and sliding animations, and swap spinners for a slow fade. Always on when your operating system asks for reduced motion. Off by default; this device only.

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; Customize a copy while you're following Omarchy).

Six themes ship built in — five dark and Graphite Light — 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.

Three display settings sit under the same subsection, all on this device only:

• 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 (the default) keeps lines intact behind a horizontal scrollbar; each code block can override it from its own header.
• Time format — System (default), 12-hour, or 24-hour. Applies to clock times in chats, the tasks panel, pull requests, usage-limit reset times, and snooze menus. System follows your locale, and the row shows what that reads as right now.

Sidebar

Controls for the workspace inbox, both on this device only:

• 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 its agent has also been idle for an hour, so follow-up work stays visible while it's warm. Un-settling a card keeps it active until its agent runs again.

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, this device only; 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.

Notifications

• Notification sounds — Play a sound when an agent finishes, or when a chat agent needs your approval or an answer.
• Desktop notifications — Show a system notification for the same events; click it to open the agent.

Both sync. See Notifications.

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. Your bindings sync. See Keyboard Shortcuts for the full list.

Agent

Use your ChatGPT plan

The top of the page connects a ChatGPT plan to Codex — separate from your Codemux account and cloud sync. Continue with ChatGPT opens your browser ("Finish in your browser", with Cancel sign-in; the request expires after five minutes). Once connected, the block shows the account email and "Eligible Codex requests use your ChatGPT plan", with Manage usage (opens ChatGPT's usage page) and Disconnect. Saved connections lists accounts you've used before, and Use a different ChatGPT account adds another. If the Codex CLI isn't installed, the block links to its installation guide. Not shown in the web remote.

New chats

Shown while the Agent Chat GUI is on. What a new chat starts with — you can still change any of it in the composer before sending. Both rows are on this device only.

• Default model — Automatic prefers your connected ChatGPT plan, otherwise Claude's default model, and shows what it resolves to. Custom picks the provider, model, and reasoning level for every new chat. A saved model that no longer exists falls back to the provider's default.
• Workspace — New worktree (default) gives each chat its own branch and checkout; Current checkout works directly on the project's checked-out branch.

Changing either one also updates an empty composer that's already open. Drafts with text or attachments are left alone.

Tools & runtime

• Utility agent — One inexpensive default used for conversation handoffs and other lightweight generation. Automatic prefers Codex Luna, then Claude Haiku. Without one, handoffs still work but arrive as raw transcripts rather than summaries. Only Claude, Codex, and OpenCode can run background jobs like this. This device only.
• Hermes · experimental ACP integration — its own block: the Hermes executable and Hermes root used to find your Hermes profiles, Save and refresh, and per profile Check runtime and Disconnect (which asks first, since disconnecting can cut off background learning). Stored on this device only. See Agent Chat → Hermes.
• Default Hermes profile — New Hermes chats start with this profile. Automatic uses the only installed profile; a profile you pick in a project's chat is remembered for that project. This device only.
• Custom agents (Local ACP) — Add custom agent connects an installed ACP v1 harness: an Agent name, Executable, arguments, environment variables, an optional Authentication method, and Enabled. Each saved agent has Probe, edit, and delete buttons. It runs directly, without a shell, with your OS account's access; configuration stays on this machine and environment values are stored encrypted.
• Auto-configure MCP for workspaces — Automatically write .mcp.json so agents discover Codemux tools. Disable if you manage MCP config manually. This device only.

The remaining rows appear while the Agent Chat GUI is on:

• 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, synced, and currently Codex only — see Per-Turn Revert Checkpoints.
• Resume automatically after usage limits reset — When a provider reports when your usage limit resets, continue the interrupted run then. At most two automatic attempts before it waits for you. On by default; this device only.
• Delegate to other agents — When you ask for it, a Full-access Claude or Codex chat can hand a task to another installed agent, e.g. "have Codex implement X, then review it". Each task opens as a tab next to the chat and shares its folder. Turning it off hides the tool from Claude chats right away and from new Codex chats. On by default; this device only.
• Desktop-size background browser — Starts the agent's background browser at a real desktop viewport — the Browser page'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 — see Background Browser.

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

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. What's included → expands the full list.

Open Agents → 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. This page stays visible in either mode so you can always find your way back.

MCP Servers

While the Agent Chat GUI is on, the page lists every MCP server Codemux discovered across Codemux / Claude / Cursor configs. Servers spawn lazily on the first chat session; Codemux's own MCP is always on. Per server you can:

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

If starting, stopping, or restarting a server fails, a toast names the server and gives the reason (for example "Couldn't start github"). The 50-tool cap warning surfaces here too. See MCP Servers.

Below it, Outside assistants lets another assistant use Codemux tools — separate from the servers your in-app agents use. This part shows in either interface. See Codemux MCP Server.

Permissions

When the Agent Chat GUI is enabled, the Permissions page lists every tool-permission rule the agent honors — the allow, deny, and ask rules read from your settings.json files. Rules are grouped by where they live:

• User-wide — ~/.claude/settings.json (applies everywhere)
• This project (gitignored) — <project>/.claude/settings.local.json (this machine only)
• This project (shared) — <project>/.claude/settings.json (committed)

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 page is for reviewing and pruning them.

Skills

The Skills page 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)

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 — plus your plan limits read straight from Claude Code and Codex. See Usage.

The page appears while the Agent Chat GUI is on. The same view also opens beside the sidebar as its own page, from the sidebar footer's Usage button or /usage in the chat composer.

Projects

Lifecycle scripts and worktree files for each project. A project picker in the page header chooses which project you're editing — it defaults to the active workspace's project, and lists every project you have open. With no project open, the page offers Open project… instead.

• Worktree includes — Files matching these patterns are copied from the main project into new worktrees, one pattern per line. Defaults to .env .env.* .env.local when empty. A .codemuxinclude file in the project root takes priority, so you can share patterns with your team. See Worktree Setup.
• Setup — Commands that run when a new workspace is created, and on an explicit Re-run Setup (e.g., npm install, docker compose up -d). One per line.
• Teardown — Commands that run when a workspace is deleted (e.g., docker compose down).
• Run — The dev command executed by the Run button (Ctrl+Shift+G).
• Environment variables — A reference list of the $CODEMUX_* variables every script can use: $CODEMUX_ROOT_PATH, $CODEMUX_WORKSPACE_PATH, $CODEMUX_BRANCH, $CODEMUX_PORT, $CODEMUX_WORKSPACE_NAME, $CODEMUX_WORKSPACE_ID.

Fields save when you leave them, with a brief Saved note; a save that fails keeps your edit so you can try again. Settings configured here are stored in the local database. File-based config (.codemux/config.json) takes precedence when present, and the page tells you when it finds one. See Setup Scripts.

Presets

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

• Show preset bar — Display the preset quick-launch bar below the tab bar. This device only.
• Your presets — Drag the grip to reorder. Click a preset (or focus it and press Enter) to edit it; the star pins it to the preset bar.
• New preset — The New preset button (in the Your 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. Deleting asks for confirmation. 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
• Working directory — Override the default CWD per preset

Closing the editor sheet keeps any name or description edits you were still typing.

Archive

Workspaces archived from the sidebar. Files, branches, and worktrees stay on disk until you delete them here — unarchive to bring a workspace back (files, branch, and worktree are preserved; the pane layout starts fresh). See Restore from Settings → Archive. This page also hosts Import recent chats.

Session Restore

• Enable session restore — Save and restore terminal scrollback across app restarts. See Session Persistence.
• Scrollback lines — Lines saved per terminal pane, 1,000–50,000.
• Max disk usage — Cap on all saved scrollback, 10–500 MB.

The sliders show their value as you drag and save once you let go. All three sync.

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.).
• Detected editors — The editors found on this machine and the command each one runs.

Open a workspace in your editor from the title-bar launcher or the Open in editor entry in the sidebar context menu.

Terminal

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

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.

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.

Both clear actions ask for confirmation first. Per-session overrides are available from the CLI and MCP — see Viewport Presets.

Git

• Default base branch — Used when creating feature branches (defaults to main). Saves on blur or Enter; a blank value is flagged rather than saved. Synced.

Diffs

The starting state for diff tabs and the pull request Code tab, all on this device only. The toggles in a diff toolbar update these too, so your last choice sticks.

• Diff layout — Unified (default) stacks old and new lines in one column; Split shows them side by side.
• Hide whitespace changes — Skip lines that only change indentation or spacing when reviewing a pull request. Off by default.
• Files start — Whether each file of a pull request diff opens Expanded (default) or Collapsed to its header. Files you mark viewed always collapse.

AI Tools

• AI commit messages — Show the generate button next to the commit input.
• Agent override — Commit messages use the Utility agent by default. Set an override only when they need a different agent and model; Claude, Codex, and OpenCode are all supported. The same choice drives the pull request form's Write with agent chip — see Creating a Request.

A Merge Conflict Resolver subsection sits below it with its own Agent and Strategy (Smart merge, Keep both, Prefer my branch, Prefer target) rows. AI Tools and the resolver are stored on this device only.

Source Control

Codemux reads pull and merge requests through each product's own command-line tool. This page 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 page.

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.

Add-ons

Browse, install, and manage optional add-ons. See Add-ons.

Devices (Hosts)

The Devices page is where you register the other machines you want to run work on — a home server, a desktop, a cloud VM. Codemux talks to them 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 page lists This machine (by hostname) followed by your devices, each with a live status — Connected, Updating…, Needs setup, or Offline — and a … menu with Test connection, Set up again, Rename…, and Remove… (which asks first). With no devices yet it reads "No devices yet. Add a home server, a desktop, or a cloud VM — anything you can SSH into."

Device names and SSH targets sync with your account, so a device you add on one machine shows up on your others. SSH keys and config never leave ~/.ssh.

Adding a device

Add device takes an SSH target — user@host or an ~/.ssh/config alias, with matching aliases suggested under From your SSH config — and an optional Name. One Connect runs every step and shows its progress:

1. Save device
2. Connect over SSH — if this fails, the dialog shows the SSH error and reminds you that ssh <target> must work from a terminal without a password prompt.
3. Install Codemux helper — installs the small static codemux-remote binary to ~/.local/bin in your user account (no root, no system changes). Marked already installed when it's there.
4. Ready

Clicking Connect is the consent to install the helper; a failed step turns the button into Retry. Set up again re-runs the same flow for an existing device.

After the helper is installed, Codemux also 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.

Upgrades

Devices catch up with your desktop on their own. Whenever a reachable device has an older codemux-remote than the one bundled with your desktop — at startup or any time later — it's upgraded in the background and shows Updating… meanwhile. Upgrades never kill terminals, never downgrade a device that a newer desktop already updated, and restart the helper's service only when it's idle: if the host reports live sessions, the new binary is uploaded and takes over at the service's next restart.

Background upgrades only touch existing installations — a missing helper is installed only through Connect or Set up again, so consent stays explicit.

Picking a device for a thread

A device picker leads the strip under the new-thread composer: it shows this machine's hostname, and its dropdown lists your devices with their status. Pick a device and the thread runs there. To move a workspace you already have, use Move to device… in its sidebar context menu. The Devices Page shows the work that lives on your other machines.

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 — its sidebar row 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. Move the workspace to the device again to re-establish it.

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

Remote Access

Reach this desktop's sessions from a browser on another device. Off by default behind the page's own toggle. See Web Remote Access.

About

Which build you're running, whether it's current, and what to attach when you report a problem.

• Version — Codemux v<version> and how it was installed (AppImage, Windows installer, or System package for deb, rpm, and AUR installs), with a Release notes link.
• Updates — the update status and the one action that moves it forward: Check for updates, Download update, Restart to update, or Open release page on package-manager installs. It drives the same flow as the update toast; see Updates.
• Performance diagnostics — Copy diagnostics copies bounded startup, workspace-switch, renderer, payload-size, and native timing summaries. Paths, titles, messages, and IDs are excluded.
• Logs — Show log file opens the folder holding Codemux's rotating log file (codemux.log).
• Reset settings — Reset… returns every synced setting (appearance, editor, terminal, Git, shortcuts, notifications, browser, agent chat, and session restore) to its default, and deletes your custom themes and custom source-control hosts. Signed in, this applies on every device. Projects, presets, workspaces, chats, and preferences kept only on this device (such as density and sidebar options) are not touched. A confirmation dialog warns that it can't be undone.

Logs and Reset settings are hidden in the web remote.

All Settings Pages