Settings Reference

Complete reference for all AgentMux settings. Settings are stored in settings.json and edited directly in your default editor.

Opening Settings

Settings is not a pane — there’s no defwidget@settings widget anymore. Open settings.json from the hamburger menu in the top tab bar:

Click the hamburger icon (≡) at the start of the tab bar.
Select Settings.
AgentMux opens settings.json in your default editor (via ensure_settings_file + open_in_editor).

You can also use the command palette (“Open Settings File”) if you prefer keyboard navigation.

The hamburger menu also includes inline submenus for the most-changed preferences so you don’t have to touch the file directly:

Theme ▸ Pick from Default, Midnight, High Contrast, Monokai, Nord, Dracula, Tokyo Night, Catppuccin, or Gruvbox. Selection persists across restart (writes window:theme).
Opacity ▸ Global window translucency from 100% down to 35% in 5% steps (writes window:opacity + window:transparent). For per-window control, use the InstancePanel slider — click the version chip in the status bar. See Window appearance.

Under Midnight specifically, the agent pane background is pure black; other panes use the theme’s deep-navy --main-bg-color.

Settings File Location

Settings are per-instance, under the unified data layout:

Mode	Path
Installed / Portable	`~/.agentmux/versions/<version>/config/settings.json`
Dev (`task dev`)	`~/.agentmux/dev/<branch>/config/settings.json`

Override the ~/.agentmux/ root with the AGENTMUX_HOME_OVERRIDE environment variable (intended for tests). See Multi-instance & dev mode for the full layout.

Terminal Settings

Setting	Type	Default	Description
`term:fontsize`	number	`12`	Font size in pixels
`term:fontfamily`	string	`"JetBrains Mono"`	Font family
`term:theme`	string	`"default-dark"`	Terminal color theme
`term:scrollback`	number	`1000`	Scrollback buffer lines
`term:copyonselect`	boolean	`true`	Auto-copy text on selection
`term:transparency`	number	`0.5`	Pane transparency (0.0–1.0)
`term:localshellpath`	string	`"/bin/bash"`	Default shell executable
`term:localshellopts`	array	`[]`	Shell launch arguments
`term:disablewebgl`	boolean	`false`	Disable WebGL renderer (falls back to Canvas)
`term:allowbracketedpaste`	boolean	`true`	Enable bracketed paste mode
`term:shiftenternewline`	boolean	`false`	Shift+Enter creates newline
`term:agentmaxruntimehours`	number	`0`	Max runtime for an agent pane in hours (`0` = unlimited)
`term:agentidletimeoutmins`	number	`0`	Idle timeout for an agent pane in minutes (`0` = unlimited)

Window Settings

Setting	Type	Default	Description
`window:theme`	string	`"default"`	UI color theme. One of `default`, `midnight`, `high-contrast`, `monokai`, `nord`, `dracula`, `tokyo-night`, `catppuccin`, `gruvbox`. Easier to switch from the hamburger menu’s `Theme` submenu.
`window:transparent`	boolean	`false`	Enable window transparency
`window:blur`	boolean	`false`	Blur background (macOS only)
`window:opacity`	number	`1.0`	Window opacity (0.0–1.0). The hamburger menu’s `Opacity` submenu (global) and the InstancePanel per-window slider both clamp to 0.35–1.0; direct edits to `settings.json` accept any number. Windows only — see Window appearance.
`window:bgcolor`	string	`""`	Custom background color
`window:zoom`	number	`1.0`	Global zoom factor
`window:tilegapsize`	number	`3`	Gap between panes in pixels
`window:showmenubar`	boolean	`false`	Show native menu bar
`window:nativetitlebar`	boolean	`false`	Use native title bar
`window:confirmclose`	boolean	`false`	Confirm before closing window
`window:savelastwindow`	boolean	`true`	Restore last window size and position
`window:dimensions`	string	`""`	Saved window dimensions (WxH)
`window:reducedmotion`	boolean	`false`	Reduce animations
`window:magnifiedblockopacity`	number	`0.6`	Opacity of background when a pane is magnified
`window:magnifiedblocksize`	number	`0.9`	Size of magnified pane (0.0–1.0)
`window:magnifiedblockblurprimarypx`	integer	—	Primary blur radius (px) behind a magnified pane
`window:magnifiedblockblursecondarypx`	integer	—	Secondary blur radius (px) behind a magnified pane
`window:maxtabcachesize`	number	`10`	Maximum cached tabs
`window:disablehardwareacceleration`	boolean	`false`	Disable GPU acceleration

App Settings

Setting	Type	Default	Description
`app:globalhotkey`	string	`""`	Global activation hotkey
`app:defaultnewblock`	string	`""`	Default pane type for new blocks
`app:showoverlayblocknums`	boolean	`false`	Show block numbers as overlay
`app:dismissarchitecturewarning`	boolean	`false`	Suppress the architecture-mismatch notice

Shell Environment

Setting	Type	Default	Description
`cmd:env`	object	`{}`	Environment variables passed to all shell processes

Telemetry Settings

Setting	Type	Default	Description
`telemetry:enabled`	boolean	`true`	Enable telemetry collection
`telemetry:interval`	number	`1.0`	Metrics collection interval in seconds
`telemetry:numpoints`	number	`120`	Number of history data points to track

Connection Settings

Setting	Type	Default	Description
`conn:wshenabled`	boolean	`true`	Enable wsh shell integration on remote connections
`conn:askbeforewshinstall`	boolean	`true`	Prompt before installing wsh on remote hosts

Network Settings

Setting	Type	Default	Description
`network:lan_discovery`	boolean	`false`	Advertise this instance + browse for peer AgentMux instances via mDNS. Off by default — on Windows, flipping it on triggers the firewall prompt for UDP 5353. See LAN discovery for the toggle in the HostPopover (preferred over editing this file directly, since the UI flips the daemon live without a restart).

Other Settings

Setting	Type	Default	Description
`widget:showhelp`	boolean	`true`	Show help widget in top bar
`widget:icononly`	boolean	`false`	Icon-only widget bar (no labels)
`blockheader:showblockids`	boolean	`false`	Display block IDs in pane headers
`preview:showhiddenfiles`	boolean	`false`	Show hidden files in file previews
`tab:preset`	string	`""`	Default tab layout preset

MCP Servers

MCP servers are configured per-agent in a Memory bundle, not via a global settings.json key. The agent runtime materializes the bundle’s mcp_servers field into the agent’s .mcp.json at launch and the AgentMux MCP server is auto-injected alongside any user-defined entries.

See Memory bundles for the bundle schema (including the mcp_servers field).

Environment Variables

AgentMux respects these environment variables:

Variable	Purpose
`AGENTMUX_HOME_OVERRIDE`	Override the `~/.agentmux/` root (intended for tests)
`AGENTMUX_RUNTIME_MODE`	Set by the launcher; consumers read it to know they’re running installed/portable/dev
`AGENTMUX_DATA_DIR`, `AGENTMUX_CONFIG_DIR`, `AGENTMUX_LOG_DIR`, …	Per-instance paths exported by the launcher; never set these manually
`CLAUDE_CONFIG_DIR`	Per-instance Claude Code auth/config dir; AgentMux sets this automatically
`CODEX_HOME`	Per-instance Codex CLI auth dir
`GEMINI_CLI_HOME`	Per-instance Gemini CLI auth dir
`GEMINI_FORCE_FILE_STORAGE`	`true` — required for Gemini CLI auth-dir isolation
`OPENCLAW_HOME`	Per-instance OpenClaw auth dir
`KIMI_SHARE_DIR`	Per-instance Kimi Code CLI auth dir
`COPILOT_HOME`	Per-instance GitHub Copilot CLI auth dir
`PI_HOME`	Per-instance Pi auth dir
`CLAUDE_API_KEY`	Optional fallback for Claude agent panes (OAuth is the primary path)
`OPENAI_API_KEY`	Optional fallback for Codex agent panes (OAuth is the primary path)
`GEMINI_API_KEY`	Optional fallback for Gemini agent panes (OAuth is the primary path)

The per-provider *_HOME / *_CONFIG_DIR variables are set automatically by AgentMux at launch (sourced from each provider’s authConfigDirEnvVar field in PROVIDERS). Setting them manually is only useful when scripting an out-of-AgentMux workflow against the same auth dirs.

Data Directories

All per-version state lives under <data-dir>/, where <data-dir> is ~/.agentmux/versions/<version>/ (installed / portable) or ~/.agentmux/dev/<branch>/ (dev). See Persistence and Multi-instance & dev mode for the full layout.

Purpose	Path
Config (`settings.json`, etc.)	`<data-dir>/config/`
Logs (rotated daily, 7-day retention)	`<data-dir>/logs/`
SQLite stores (objects, filestore, sagas)	`<data-dir>/data/db/`
Launcher event log (JSONL)	`<data-dir>/data/launcher-events.log`
Account-wide state (cookies, OAuth)	`~/.agentmux/shared/`