Skip to content

Settings reference

τ-mux persists settings to ~/Library/Application Support/hyperterm-canvas/settings.json. The settings panel (⌘,) writes this file, and so do the command palette toggles and RPC verbs like claude.auto_approve — those paths persist and apply live. Hand-editing the file works too, but τ-mux does not watch it: an external edit is only picked up on the next launch (and will be overwritten if the app writes settings first).

Schema: AppSettings in src/shared/settings.ts. Defaults: DEFAULT_SETTINGS. Validation: validateSettings (per-field schemas in settings.schema.ts, so an out-of-range or wrong-typed value falls back to the default rather than breaking the app).

This page lists every field, with the default read from DEFAULT_SETTINGS.

FieldTypeDefaultEffect
shellPathstring""Shell binary. Empty = $SHELL. New surfaces only — existing shells keep running.
scrollbackLinesnumber10000Lines retained in the scrollback buffer per surface.
fontFamilystring'JetBrainsMono Nerd Font Mono', 'JetBrains Mono', 'Berkeley Mono', 'SF Mono', 'Menlo', monospaceTerminal font stack.
fontSizenumber13Terminal font size in px.
lineHeightnumber1Line-height multiplier (0.8–2.0).
cursorStyle"block" | "bar" | "underline""block"Terminal cursor shape.
cursorBlinkbooleantrueBlink the terminal cursor.
terminalRenderer"dom" | "webgl""dom"Experimental GPU renderer. Falls back to DOM automatically on unsupported hardware, init failure, or context loss — the settings panel shows a live “running on DOM — reason” hint when it has. It shipped enabled in v0.4.9 and rendered panes blank on some setups; a one-time migration in v0.4.12 reset a persisted webgl back to dom. Command palette: “Use WebGL/DOM Terminal Renderer”.
terminalOsc94EnabledbooleantrueHonour OSC 9;4 progress sequences (per-pane progress chip).
terminalOsc9NotifyEnabledbooleantrueHonour OSC 9 ; <message> (the iTerm2 dialect) as a notification request. This is the channel agent CLIs mean by “iterm2 notifications” — Claude Code’s preferredNotifChannel: iterm2 lands here. Notifications go through the same pipeline as ht notify: overlay, sidebar, sound, and Telegram forwarding when enabled.
terminalBellNotifyEnabledbooleantrueTurn BEL into a notification — the terminal_bell channel agent CLIs offer. Throttled to one per pane per 5 s so a program ringing the bell in a loop cannot flood the centre.
ideBridgeEnabledbooleantrueAdvertise this window to Claude Code as an IDE. Writes ~/.claude/ide/<port>.lock and serves MCP over a loopback-only WebSocket, so a diff Claude proposes opens in an editor pane and waits for your verdict — an approval that also reaches Telegram when forwarding is on. The port is ephemeral, bound to 127.0.0.1, and every connection must present a per-launch token from the 0600 lock file, which is removed when τ-mux exits. Turn it off to stop advertising and close the listener.
terminalOsc52WriteEnabledbooleantrueLet programs write the system clipboard with OSC 52 — how a yank in nvim or tmux over SSH reaches your local machine. Payloads above 100 000 characters are refused rather than truncated. There is deliberately no read counterpart: OSC 52 also defines a clipboard read, which would let any process with terminal access exfiltrate your clipboard silently, and τ-mux always refuses it. No setting turns that on.
FieldTypeDefaultEffect
themePresetstring"tau"Named theme preset. See Themes.
chromeTheme"system" | "graphite-dark" | "graphite-light" | "high-contrast""system"App chrome theme, independent of the terminal palette.
accentColorstring"#6fe9ff"Primary accent (cyan — focus, selection, human identity).
secondaryColorstring"#ffc56b"Secondary accent (amber — agent identity).
foregroundColorstring"#d6e2e8"Default terminal foreground.
bgBasestring"0, 0, 0"Terminal background as an r, g, b triple, combined with terminalBgOpacity.
terminalBgOpacitynumber1Terminal background opacity, 0–1.
ansiColorsobject16-colour TAU paletteThe full ANSI 16 (black…brightWhite).
terminalBloombooleanfalseWebGL bloom layer over the terminal.
bloomIntensitynumber0Bloom strength, 0–2.
legacyBloomIntensitynumber0Snapshot of the pre-TAU bloom value, kept so the migration is reversible.
bloomMigratedToTaubooleanfalseInternal migration marker — do not set by hand.
onboardingCompletedbooleanfalseSet once the first-run welcome overlay has been dismissed. Reset to false to see it again. Since v0.24.2.
paneGapnumber2Gap between panes in px, 0–20.
sidebarWidthnumber320Sidebar width in px, 200–600.
layoutVariant"bridge" | "cockpit" | "atlas""bridge"Chrome layout variant — see Layout variants.
FieldTypeDefaultEffect
workspaceCardDensity"compact" | "comfortable" | "spacious""comfortable"Vertical density of workspace cards.
workspaceCardShowMetabooleantrueShow the meta row (cwd, branch).
workspaceCardShowStatsbooleantrueShow CPU / memory / pane stats.
workspaceCardShowPanesbooleantrueShow the per-pane list.
workspaceCardShowManifestsbooleantrueShow the package.json / Cargo.toml card.
workspaceCardShowFileExplorerbooleantrueShow the inline file explorer.
workspaceFileExplorerShowHiddenbooleanfalseInclude dotfiles in the file explorer.
workspaceFileExplorerMaxEntriesnumber200Cap on entries listed per directory.
workspaceCardShowStatusPillsbooleantrueShow ht set-status pills on the card.
workspaceCardShowProgressbooleantrueShow the progress bar (ht set-progress, OSC 9;4).
statusBarKeysstring[]["workspace","panes","cpu","mem","procs","fg","cwd","branch","ht-all","ports","time"]Which segments the bottom status bar renders, in order.
htStatusKeyOrderstring[][]Explicit ordering for ht set-status keys; unlisted keys follow.
htStatusKeyHiddenstring[][]ht set-status keys to hide.
FieldTypeDefaultEffect
notificationSoundEnabledbooleantruePlay finish.mp3 when a sidebar notification arrives.
notificationSoundVolumenumber1Arrival-cue volume, 0–1.
notificationOverlayEnabledbooleantrueShow the transient on-screen notification overlay.
notificationOverlayMsnumber6000How long the overlay stays up, in ms.

See the Claude Code integration.

FieldTypeDefaultEffect
claudeAutoApprovebooleanfalseAuto-accept the permission prompt Claude Code shows in a terminal pane by sending Enter. Only fires for that terminal prompt — never the τ-mux approval modal, never the Claude Code pane — pauses itself after a burst, and logs every approval to the pane’s sidebar log. Off by default: this grants unattended consent for commands the agent asks to run.
claudeAutoApproveDelayMsnumber700Delay before the Enter keystroke, 0–10000 ms. The prompt is re-checked when the delay expires, so a prompt you answered yourself never receives a stray Enter.
FieldTypeDefaultEffect
browserSearchEngine"google" | "duckduckgo" | "bing" | "kagi""google"Engine used when the address bar input isn’t a URL.
browserHomePagestring""Page opened for a new browser surface. Empty = blank.
browserForceDarkModebooleanfalseAsk pages to render in dark mode.
browserPartitionMode"shared" | "per-surface""per-surface"Cookie/storage partitioning across browser panes.
FieldTypeDefaultEffect
packageRunner"bun" | "npm" | "pnpm" | "yarn""bun"Command used to run package.json scripts from the sidebar.

See auth & hardening.

FieldTypeDefaultEffect
webMirrorPortnumber3000Mirror listen port, 1–65535.
autoStartWebMirrorbooleanfalseStart the mirror at launch.
webMirrorBind"127.0.0.1" | "0.0.0.0""127.0.0.1"Bind address. Loopback by default since v0.24.0. 0.0.0.0 exposes the mirror to your whole LAN — with an empty or weak token τ-mux now generates a strong one automatically instead of running unauthenticated.
webMirrorAuthTokenstring""Shared token for mirror access. Empty means authentication is off on loopback only — on a 0.0.0.0 bind a missing or short (<16 chars) token is replaced by a generated one, persisted here and logged once at startup.
rpcSocketRequireTokenbooleantrueRequire the per-boot token for state-mutating ht socket calls. On by default since v0.4.12; every first-party client presents it automatically.

See the Telegram bridge.

FieldTypeDefaultEffect
telegramEnabledbooleanfalseRun the long-poll bot service.
telegramBotTokenstring""BotFather token.
telegramAllowedUserIdsstring""Comma-separated Telegram user ids allowed to talk to the bot. Fail-closed: empty rejects everyone.
telegramNotificationsEnabledbooleanfalseForward sidebar notifications to Telegram.
telegramNotificationButtonsEnabledbooleanfalseAdd inline action buttons to forwarded notifications.
telegramAskUserEnabledbooleanfalseForward ht ask questions to Telegram (answer from your phone).

Nested object — see auto-continue.

FieldTypeDefaultEffect
autoContinue.engine"off" | …"off"Which decision engine runs. off disables the feature entirely.
autoContinue.dryRunbooleantrueDecide and log, but never send the continue keystroke.
autoContinue.cooldownMsnumber3000Minimum gap between continues.
autoContinue.maxConsecutivenumber5Runaway guard — pauses after this many consecutive continues.
autoContinue.modelProviderstring"anthropic"Provider for the model-backed engine.
autoContinue.modelNamestring"claude-haiku-4-5-20251001"Model used by the model-backed engine.
autoContinue.modelApiKeyEnvstring"ANTHROPIC_API_KEY"Env var read for that provider’s key.
FieldTypeDefaultEffect
auditsGitUserNameExpectedstring | nullnullExpected git config user.name; the startup audit warns on drift. null disables the check.

Most fields apply live across all panes the moment they’re saved. Exceptions:

  • shellPath — new surfaces only.
  • webMirrorPort, webMirrorBind, webMirrorAuthToken — restart a running mirror (they are honoured on auto-start at launch since v0.3.161).
  • autoStartWebMirror — only at launch (toggle the mirror manually any time).
  • rpcSocketRequireToken — applies to new ht socket connections immediately.
  • terminalRenderer — applies to newly created panes.

τ-mux reads this file at launch and rewrites it whenever settings change; it does not watch it. So edit it while the app is closed, or prefer the settings panel / palette / RPC, which apply immediately. Unknown fields are dropped on load with a logger warning, and invalid values fall back to their default.

Terminal window
$EDITOR ~/Library/Application\ Support/hyperterm-canvas/settings.json