Configuration · ckmux

On macOS and Linux, ckmux reads ~/.config/ckmux/ckmux.conf (precisely: $XDG_CONFIG_HOME/ckmux/ckmux.conf, or the file CKMUX_CONFIG names). A missing file is the ordinary case — every setting has a default, and this page states each one. Windows uses %LOCALAPPDATA%\ckmux\ckmux.conf, falling back to the current user's LocalAppData known folder when that environment variable is absent or not absolute. CKMUX_CONFIG overrides the file on every platform.

ckmux check-config parses the file and reports every problem with its file and line, starting nothing; it exits non-zero when the file has problems. A running ckmux shows the same warnings at startup rather than guessing. The Settings dialog (Settings ▸ General…) writes the same keys back to the same file.

Sizes take an optional upper-case suffix: K, M, or G (powers of 1024).

Choose a shell

The default is your resolved POSIX shell on macOS/Linux and cmd.exe on Windows. Set an executable path to choose another shell; do not add shell arguments or surrounding quotes to the value. For PowerShell 7 installed at its usual Windows location:

[general]
shell = C:\Program Files\PowerShell\7\pwsh.exe

For macOS/Linux, an example is shell = /bin/zsh. The selected executable must exist. Shell selection applies to newly created terminals; existing programs keep running. Use ckmux check-config to check configuration syntax.

[general]

Key	Default	Meaning
`prefix`	`C-b`	The one key ckmux takes from the programs inside it.
`shell`	Automatic	What New Terminal runs: resolved POSIX shell on macOS/Linux; `cmd.exe` on Windows. An empty value selects that default.
`login-shell`	`true`	POSIX only: start an interactive login shell. Windows uses native shell profile behavior and preserves this key without offering it in Settings.
`scrollback`	`10000`	Lines of history per terminal; `0` means remember nothing.
`max-terminals`	`64`	The most terminals one session may hold.
`theme`	`dark`	`dark`, `light`, or `mono`.
`on-exit`	`hold-on-error`	A window whose program exited: `close`, `hold`, or `hold-on-error` (keep it only when the exit status was non-zero — when the text on screen is the evidence).
`audible-bell`	`false`	Whether a child's bell reaches your terminal as a sound. The visual half — border flash and footer flag — is always on.
`confirm-kill`	`true`	Ask before closing or killing something with a live program in it.
`kill-grace-seconds`	`5`	How long programs get to end on their own when a session is killed; `0` means don't wait.
`kill-empty-session`	`true`	A session whose last terminal closed goes away.
`clock`	`seconds`	The menu-bar clock: `seconds`, `minutes`, or `off`. The big clock (`^B t`) drops its seconds for `minutes`.
`desktop-size`	`fixed`	Shared desktop sizing: `fixed`, `fit-smallest`, or `fit-latest`. With one attached reader, resizing its host also resizes the desktop. With several readers, this policy decides; a desktop resize affects every child.
`resize-windows-to-fit`	`false`	After a reattach on a smaller screen has moved an oversized window up and left, whether a second, resizing step shrinks it to fit.
`show-cpu`	`false`	CPU readout on every terminal window's footer (View menu).
`show-memory-rss`	`false`	Memory (RSS) readout.
`show-memory-real`	`false`	macOS footprint, Linux PSS, or Windows private resident working-set pages (labelled `Private RSS`, not virtual commit charge). Missing fields are not measured zero.

[terminal]

Key	Default	Meaning
`term`	`auto`	`$TERM` inside terminals: `auto` lets ckmux claim what it can honestly support; anything else is used verbatim.
`mouse`	`true`	Forward mouse events to programs that ask for them.
`alternate-scroll`	`true`	Wheel scrolling in full-screen programs becomes arrow keys.
`sixel`	`auto`	Sixel graphics: `auto` or `off`.
`sixel-max-megapixels`	`64`	The largest picture a program may draw — an allocator guard, far above a full 4K screen.
`osc52`	`true`	Whether a program may put text on the clipboard with OSC 52 (capped at 64 KiB).
`clipboard`	`osc52, pbcopy`	Where a copy goes, in order: `osc52` (native clipboard on Windows, outer terminal on POSIX), `pbcopy` (a macOS helper), or `exec:<command>` (text on stdin).

[printer]

Programs can print through the terminal (the ANSI printer controls); ckmux captures that output per window.

Key	Default	Meaning
`mode`	`ask`	`ask` (a popup offers the capture), `capture` (always keep it), or `off`.
`ask-cache`	`256K`	How much print output the Ask popup holds.
`spool-limit`	`1M`	The most one print job may spool.
`save-format`	`txt`	Saved jobs: `txt` (plain text) or `ansi` (with colors and attributes).
`save-folder`	`~/Documents`	Where saved jobs go.
`save-ask-name`	`true`	Ask for a file name on save.

[render]

Key	Default	Meaning
`max-fps`	`30`	The most frames per second the client draws.

[keys]

bind and unbind lines rebind the chords; they never add or remove commands — a command with no chord is still in the menus.

[keys]
bind terminal C new-terminal
unbind terminal x

(# is not a comment character inside a bind line — it is a chord someone may want to bind.)

The form is bind <context> <chord> <action> and unbind <context> <chord>. Order matters: two binds of one chord mean the later one; an unbind after a bind means neither.

Contexts: terminal (the key after the prefix), desktop, copy-mode, picker, move-resize.

Actions: new-terminal, close-terminal, kill-terminal, move-terminal, rename-terminal, print-output, printer-settings, next-terminal, previous-terminal, window-list, zoom, minimize, move-resize, tile-horizontally, tile-vertically, tile-grid, cascade, menu-bar, copy-mode, paste, detach, sessions, new-session, rename-session, kill-session, key-reference, settings, status-bar, fit-desktop, show-cpu, show-memory-rss, show-memory-real, show-clock, show-date, show-date-time, about, send-prefix, quit.

ckmux check-config also names any key that is parsed and validated but not yet acted on by this version, with the work it waits for — so "I set this, why did nothing happen?" always has an answer.

Known diagnostic limitation: check-config still lists ask-cache, save-format, save-folder, and save-ask-name as waiting for printer work. The runtime does honor all four; only that report is stale.