wmux reads ~/.wmux/config.toml on startup (Windows: %USERPROFILE%\.wmux\config.toml). The file is optional — if it isn't present, built-in defaults apply.

Edit it, then run wmux reload-config (or restart wmux) to pick up changes.

[terminal]
font-family      = "Cascadia Mono"
font-size        = 14
cursor-style     = "block"        # block | underline | bar
cursor-blink     = true
scrollback-lines = 10000
# Touchscreens: scroll steps sent per row of finger travel when a drag scrolls
# a full-screen app. 1 / the app's own scroll speed makes the content follow
# the finger (opencode's scroll_speed is 3). Wheel and flick are unaffected.
touch-pan-gain   = 0.33

[terminal.colors]
# Default scheme for every new pane. Any bundled theme name works
# (see `wmux list-themes`), or the key of a user-defined scheme below.
default = "Dracula"

# User-defined named schemes — override individual fields of the base theme.
# Invoke them with:   wmux split --color-scheme prod
[terminal.colors.schemes.prod]
background = "#2b0b0b"
foreground = "#ffdddd"
cursor     = "#ff5555"

[terminal.colors.schemes.staging]
background = "#2b1f0b"
foreground = "#ffeecc"
cursor     = "#ffaa44"

[terminal.colors.schemes.dev]
background = "#0b1f0b"
foreground = "#ccffcc"
cursor     = "#55ff55"

# Full palette override (up to 16 ANSI colors) — optional.
[terminal.colors.schemes.mono]
background = "#000000"
foreground = "#ffffff"
palette = [
  "#000000", "#ff0000", "#00ff00", "#ffff00",
  "#0000ff", "#ff00ff", "#00ffff", "#ffffff",
  "#555555", "#ff5555", "#55ff55", "#ffff55",
  "#5555ff", "#ff55ff", "#55ffff", "#ffffff",
]

[workspace]
# What a NEW workspace opens with — the sidebar "+", Ctrl+N, first launch and
# `wmux new-workspace` all use this.
panes  = 3         # 1-8 terminal panes
layout = "grid"    # grid | columns | rows | left | down | single
# Snapshot the live layout this often, as an "Auto-save …" session. 0 = never.
snapshot-minutes = 5

[browser]
# Start page for a workspace's browser panel. Needs a scheme.
default-url = "http://localhost:3000"
# Extra ports that count as dev servers, merged with the built-in list.
dev-ports = [8501, 4321]
auto-open = true

[remote]
# In a direct SSH pane, SCP local files before inserting their remote paths.
upload-on-paste = true
upload-on-drop  = true

[keys]
# Remap what a key sends to the terminal (see "Key remaps" below).
"ctrl+k"       = "<C-k><Delete>"   # kill to end of line, then pull the next line up
"ctrl+alt+r"   = "clear<CR>"
"ctrl+shift+q" = ""                # empty value = swallow the key

[workspace] decides what a fresh workspace opens with. Every entry point reads it — the sidebar +, Ctrl+N, first launch, and wmux new-workspace:

[workspace]
panes  = 3
layout = "grid"

panes accepts 1 to 8; anything outside that is clamped, and wmux config show says so. Before 2.8.0 the sidebar + always made three panes and wmux new-workspace always made one — both now follow this setting, and wmux new-workspace --panes 1 --layout single pins the old CLI shape for a script that depends on it.

snapshot-minutes (Settings → Workspace → Snapshot sessions every) decides how often wmux saves the live layout as a named session. 0 switches it off; the default is every 5 minutes.

[workspace]
snapshot-minutes = 5

wmux already rewrites session.json every 30 seconds, but in place — so it only ever holds the layout you have now, which is no help at all once something has gone wrong. Snapshots land under Load session as Auto-save <date> <time>, and restore like any other saved session (layout only; PTYs respawn).

Two properties worth knowing (issue #238):

• Three are kept, not one. A single overwritten entry bounds recovery to the state a few minutes ago — which, after an accident, is the state after it. Three slots stay out of the way and keep some depth behind the mistake.
• Only a layout that actually changed uses a slot. Workspaces, their titles and their split trees count; a shell changing directory does not. So an idle machine never rotates its own history out of the ring.

Snapshots never become the session restored on your next launch — that pointer only ever follows a Save you asked for.

A saved layout marked Default (Settings → Workspace → Saved Layouts) wins over this section: it also carries each pane's shell, directory and startup commands, so it answers the same question more completely. Any other saved layout is one click away from the caret next to the sidebar +.

A workspace created from a saved layout — picked from that menu or the command palette, or made from the Default layout — is named after the layout with an instance number: Work-1, then Work-2, and so on. The number is one past the highest Work-N currently open; a plain Work does not count.

Any other new workspace with no title of its own is named after the tabs it opens with, in pane order: api + api + notes.md + Prompts. A terminal is named after its starting directory, else its shell; a markdown or code tab after its file; a tab with a custom title after that. The title is set once, at creation, and renamed like any other. When no tab has a name of its own — the plain Terminal + Terminal + Terminal of the shape above with no directory or shell — the workspace is called Workspace N instead. An explicit title always wins: wmux new-workspace --title, Open folder as workspace, and a restored session keep theirs.

[browser]
default-url = "http://localhost:3000"

Where a workspace's browser panel opens before it has been anywhere. A scheme is required — a bare localhost:3000 is refused with an explanation, because a webview handed one loads nothing and says nothing. Leave it empty (or omit it) for wmux's own page. This is the start page, and is separate from the default search engine, which decides where a typed non-URL goes.

The optional [remote] section controls local files pasted or dropped into a pane connected directly over SSH:

[remote]
upload-on-paste = true
upload-on-drop  = true

Both values default to true. upload-on-paste covers a screenshot or copied file inserted with either paste shortcut; ordinary clipboard text is never uploaded. upload-on-drop covers one or more files dropped onto the terminal. Hold Shift while dropping to bypass upload for that drop.

wmux invokes the Windows OpenSSH scp paired with the detected ssh client and uses BatchMode=yes. The connection must therefore authenticate without an interactive password or passphrase prompt, normally with a key or ssh-agent. Each successful file is inserted as a unique path in a private remote batch directory, such as /tmp/wmux-drop-<batch-id>/<file-id>.png, and remains there for the receiving program to use.

Detection covers wmux ssh and a direct ssh launched from an integrated PowerShell or Bash pane. Nested SSH (running a second ssh after reaching the first host) is not supported because that second client is outside the Windows process tree. wmux may still identify the outer Windows SSH process, so turn the relevant setting off (or hold Shift for a drop) while working on the inner host.

Run wmux reload-config after changing either value.

[keys] maps a key chord to the bytes wmux should send to the program running in the terminal. Each entry is "chord" = "sequence".

[keys]
"ctrl+k" = "<C-k><Delete>"

Chords are written ctrl+shift+alt+key (any subset, any order), or in the vim style <C-k> / <C-S-Tab>. alt and meta both mean Alt.

Sequences are sent as typed, with <...> naming a key:

Anything outside <...> is sent literally, so "clear<CR>" types the word and presses Enter. An empty value ("") swallows the key.

Notes:

• Remaps apply inside terminal panes only, and they take priority over wmux's own shortcuts there — remapping ctrl+t means Ctrl+T no longer opens a tab while a terminal has focus.
• Modifiers match exactly: a ctrl+k remap does not fire on Ctrl+Shift+K.
• A binding that doesn't parse is reported by wmux config show and skipped; the rest of your bindings still apply.
• wmux reload-config applies edits live, including removing bindings.

wmux ships English, Français, Español, Deutsch, Português, Italiano, Nederlands, Polski, Türkçe, Русский, Українська, 中文, 日本語, 한국어, हिन्दी, Svenska and Čeština. You can add a language, or correct a shipped one, without waiting for a release: drop a JSON file into ~/.wmux/locales/, next to config.toml.

~/.wmux/locales/
  tt.json      # adds Татарча to Settings → General → Interface language
  ko.json      # overrides individual bundled Korean strings

The filename is the language code. The file is a key → string map, optionally wrapped in strings with a label for the dropdown:

{
  "label": "Татарча",
  "strings": {
    "settings.title": "Көйләүләр",
    "markdown.copy": "Күчерү"
  }
}

A flat map without label/strings works too, in which case the code is used as the dropdown name.

How it merges. A file whose code matches a bundled language overrides only the keys it lists — you can fix one string without restating the rest. A file with a new code adds a language, falling back to English for anything it does not translate. Removing the file and reloading undoes it; the file is the whole state.

The full key list is the English dictionary, which is the source of truth: src/renderer/i18n/locales/en.ts. Placeholders like {count} and {name} must survive verbatim — they are substituted by the UI, so a renamed or dropped token silently breaks the string.

wmux locales          # what loaded, and why any file was rejected
wmux locales path     # print ~/.wmux/locales
wmux locales reload    # re-read and apply live (same as `wmux reload-config`)

Notes and limits:

• Codes must be base tags (de, not de-AT). Language auto-detection collapses the OS locale to its base tag, so a region-subtagged file would define a language that could never be selected automatically.
• Keys that are not in the English dictionary are ignored, and wmux locales reports how many — that is usually a typo or a key removed by a later release.
• A malformed file costs you that file only; the rest of the directory and every bundled language still load.
• Once you select a user-defined language it survives restarts. If you later delete the file, wmux falls back to your OS language rather than showing raw keys.
• Translations are welcome upstream too — a PR adding src/renderer/i18n/locales/xx.ts makes it a bundled language for everyone.

1. Built-in defaults
2. Settings UI values (persisted to Zustand / localStorage)
3. config.toml — applied over 1 and 2 at startup and on reload-config
4. Per-pane overrides (e.g. wmux split --color-scheme prod) — always win for that pane

"File wins at startup, app wins at runtime": if you tweak a value in the Settings UI after wmux booted, your tweak sticks until the next reload.

wmux config path      # print the config file path
wmux config show      # dump the parsed config (useful for debugging syntax)
wmux config reload    # re-read the file and apply to running surfaces
wmux reload-config    # alias of `config reload`
wmux list-themes      # print all valid `default`/`--color-scheme` names
wmux locales          # list community translations and any load errors

• Keys can be written either kebab-case or camelCase (font-family and fontFamily both work).
• cursor inside a scheme is the cursor color; use cursor-style (under [terminal]) for the shape.
• A parse error in one key is reported in wmux config show but never aborts loading — the rest of the file still applies.
• Per-pane overrides via wmux split --color-scheme NAME or wmux set-color-scheme [id] NAME always take precedence for that surface.