Skip to content

Node-based terminal manager for AI coding agents — tmux-backed terminals and parallel agent sessions as draggable nodes on an infinite pan/zoom canvas. macOS, Linux, and a browser Server Edition.

feat(windows): background-mode setting and hide-to-tray close policy

review3819a6ce65bc
diff --git a/src/core/settings-store.test.ts b/src/core/settings-store.test.ts
index 7b0f6856f..d6a783145 100644
--- a/src/core/settings-store.test.ts
+++ b/src/core/settings-store.test.ts
@@ -194,6 +194,29 @@ describe('SettingsStore nested-default merge', () => {
})
})
+ describe('runInBackgroundOnClose', () => {
+ const load = (saved: Record<string, unknown>): Settings => {
+ writeFileSync(path.join(dir, 'settings.json'), JSON.stringify(saved), 'utf-8')
+ const store = new SettingsStore()
+ store.init()
+ return store.get()
+ }
+
+ it("defaults to 'auto' for a settings.json that predates the key", () => {
+ expect(load({ fontSize: 13 }).runInBackgroundOnClose).toBe('auto')
+ })
+
+ it('keeps the three known values', () => {
+ for (const v of ['auto', 'on', 'off']) expect(load({ runInBackgroundOnClose: v }).runInBackgroundOnClose).toBe(v)
+ })
+
+ it("normalizes a hand-edited garbage value to 'auto'", () => {
+ expect(load({ runInBackgroundOnClose: true }).runInBackgroundOnClose).toBe('auto')
+ expect(load({ runInBackgroundOnClose: 'tray' }).runInBackgroundOnClose).toBe('auto')
+ expect(load({ runInBackgroundOnClose: null }).runInBackgroundOnClose).toBe('auto')
+ })
+ })
+
describe('agent launch mode migration', () => {
const loadWith = (saved: Record<string, unknown>): Settings => {
writeFileSync(path.join(dir, 'settings.json'), JSON.stringify(saved), 'utf-8')
diff --git a/src/core/settings-store.ts b/src/core/settings-store.ts
index 7aea5bf79..f68d6a5f1 100644
--- a/src/core/settings-store.ts
+++ b/src/core/settings-store.ts
@@ -91,6 +91,10 @@ function mergeSettings(saved: Partial<Settings> | null | undefined): Settings {
}
// Keep the mirror in lockstep with the resolved mode so an older build still honors the choice.
merged.vanillaLaunchDefault = merged.agentLaunchMode === "subscription";
+ // Background mode is hand-editable too: anything but the three known values is the default.
+ const bg = merged.runInBackgroundOnClose as unknown;
+ if (bg !== "auto" && bg !== "on" && bg !== "off")
+ merged.runInBackgroundOnClose = DEFAULT_SETTINGS.runInBackgroundOnClose;
// Pre-release switch that became the "Liquid Glass" appearance; honoured once so a tester's
// choice carries over, and only where the appearance still followed the terminal.
const legacyGlass = (saved as { glassTerminals?: unknown } | null | undefined)?.glassTerminals;
diff --git a/src/main/background-mode.test.ts b/src/main/background-mode.test.ts
new file mode 100644
index 000000000..e49ed17c8
--- /dev/null
+++ b/src/main/background-mode.test.ts
@@ -0,0 +1,50 @@
+import { describe, expect, it } from 'vitest'
+import { readFileSync } from 'fs'
+import { join } from 'path'
+import { resolveBackgroundOnClose, shouldShowBackgroundHint } from './background-mode'
+
+describe('resolveBackgroundOnClose', () => {
+ it("'auto' is on for Windows and off for Linux", () => {
+ expect(resolveBackgroundOnClose('auto', 'win32')).toBe(true)
+ expect(resolveBackgroundOnClose('auto', 'linux')).toBe(false)
+ })
+ it('honors an explicit on/off on Windows and Linux', () => {
+ for (const p of ['win32', 'linux']) {
+ expect(resolveBackgroundOnClose('on', p)).toBe(true)
+ expect(resolveBackgroundOnClose('off', p)).toBe(false)
+ }
+ })
+ it('is always false on macOS (it hides on close anyway; no tray)', () => {
+ for (const v of ['auto', 'on', 'off']) expect(resolveBackgroundOnClose(v, 'darwin')).toBe(false)
+ })
+ it("reads an unknown value as 'auto'", () => {
+ expect(resolveBackgroundOnClose('tray', 'win32')).toBe(true)
+ expect(resolveBackgroundOnClose(undefined, 'linux')).toBe(false)
+ expect(resolveBackgroundOnClose(true, 'linux')).toBe(false)
+ })
+})
+
+describe('shouldShowBackgroundHint', () => {
+ it('shows once, only for a background-mode hide off macOS', () => {
+ expect(shouldShowBackgroundHint({ platform: 'win32', backgroundOnClose: true, alreadyShown: false })).toBe(true)
+ expect(shouldShowBackgroundHint({ platform: 'win32', backgroundOnClose: true, alreadyShown: true })).toBe(false)
+ expect(shouldShowBackgroundHint({ platform: 'win32', backgroundOnClose: false, alreadyShown: false })).toBe(false)
+ expect(shouldShowBackgroundHint({ platform: 'darwin', backgroundOnClose: true, alreadyShown: false })).toBe(false)
+ })
+})
+
+describe('main/index.ts background-mode wiring (source guard)', () => {
+ const src = readFileSync(join(__dirname, 'index.ts'), 'utf-8')
+ it('passes the live background flag into closeAction', () => {
+ expect(src).toContain('closeAction(process.platform, quitting, win.isFullScreen(), backgroundOnCloseActive())')
+ })
+ it('tears the tray down in before-quit, right after the quitting flag flips', () => {
+ expect(src).toMatch(/quitting = true \/\/ from here on[^\n]*\n\s*destroyNotchHud\(\)\n\s*backgroundTray\?\.destroy\(\)/)
+ })
+ it('keeps the updater restart flipping `quitting` so a hidden window really closes', () => {
+ expect(src).toMatch(/initUpdater\(\(\) => \{\s*quitting = true/)
+ })
+ it('tray Quit goes through app.quit() (before-quit + confirm), not app.exit()', () => {
+ expect(src).toMatch(/onAction: \(action\) => \(action === 'open' \? showMainWindowFromBackground\(\) : app\.quit\(\)\)/)
+ })
+})
diff --git a/src/main/background-mode.ts b/src/main/background-mode.ts
new file mode 100644
index 000000000..37bb4b136
--- /dev/null
+++ b/src/main/background-mode.ts
@@ -0,0 +1,53 @@
+// Windows/Linux "background mode" — closing the window hides it to the notification-area tray
+// instead of quitting (the analogue of macOS keeping the app alive in the Dock), so the phone relay
+// host, hook server, agent-status notifications and the updater outlive the window.
+//
+// Pure + Electron-free so the policy is pressable on any CI box. The controller is ./tray.ts; the
+// close-event decision is `closeAction` in ./main-window.ts, which takes the resolved flag.
+
+import type { BackgroundOnCloseSetting } from '../shared/types'
+
+/**
+ * Whether a window close should hide to the tray on this platform.
+ *
+ * - macOS: always `false` — it hides on close regardless (main-window.ts), and has no tray to add.
+ * - `'on'` / `'off'`: the user's explicit choice.
+ * - `'auto'`: on for Windows, where the notification area always exists and a running background
+ * app there is the norm; OFF for Linux, whose tray depends on the desktop environment (stock
+ * GNOME has none without an extension) — hiding a window into a tray the user cannot see would
+ * look like a quit that did not happen. A Linux user who has a tray opts in with `'on'`.
+ *
+ * Any value that is not one of the three reads as `'auto'` (settings.json is hand-editable; the
+ * store already normalizes, this is the interpolation-site re-check).
+ */
+export function resolveBackgroundOnClose(
+ setting: BackgroundOnCloseSetting | unknown,
+ platform: NodeJS.Platform | string
+): boolean {
+ if (platform === 'darwin') return false
+ if (setting === 'on') return true
+ if (setting === 'off') return false
+ return platform === 'win32'
+}
+
+/** Marker file (under userData) recording that the one-time "still running in the tray" notice was
+ * shown. A file rather than a settings key: the renderer saves FULL settings snapshots from its own
+ * copy, so a main-side settings write would be overwritten by the next renderer save. */
+export const BACKGROUND_HINT_MARKER = 'background-close-hint-shown'
+
+export const BACKGROUND_HINT = {
+ title: 'nodeterm is still running',
+ body: 'Closing the window keeps nodeterm in the notification area so your phone and agent notifications stay connected. Quit from the tray icon.'
+} as const
+
+/**
+ * Should the first-hide notice show now? Only on an actual background-mode hide (never on macOS,
+ * whose Dock already says the app is running), and only once per install.
+ */
+export function shouldShowBackgroundHint(opts: {
+ platform: NodeJS.Platform | string
+ backgroundOnClose: boolean
+ alreadyShown: boolean
+}): boolean {
+ return opts.platform !== 'darwin' && opts.backgroundOnClose && !opts.alreadyShown
+}
diff --git a/src/main/main-window.test.ts b/src/main/main-window.test.ts
index 80027ba43..a7f786b5e 100644
--- a/src/main/main-window.test.ts
+++ b/src/main/main-window.test.ts
@@ -158,6 +158,12 @@ describe('shouldHideOnClose', () => {
expect(shouldHideOnClose('win32', false)).toBe(false)
expect(shouldHideOnClose('linux', false)).toBe(false)
})
+ it('hides off macOS only in background mode, and never while quitting', () => {
+ expect(shouldHideOnClose('win32', false, true)).toBe(true)
+ expect(shouldHideOnClose('linux', false, true)).toBe(true)
+ expect(shouldHideOnClose('win32', false, false)).toBe(false)
+ expect(shouldHideOnClose('win32', true, true)).toBe(false)
+ })
})
describe('closeAction', () => {
@@ -175,4 +181,20 @@ describe('closeAction', () => {
expect(closeAction('linux', false, true)).toBe('default')
expect(closeAction('win32', false, true)).toBe('default')
})
+ it('hides to the tray off macOS when background mode is on — plain hide, no Space dance', () => {
+ expect(closeAction('win32', false, false, true)).toBe('hide')
+ expect(closeAction('win32', false, true, true)).toBe('hide')
+ expect(closeAction('linux', false, true, true)).toBe('hide')
+ })
+ it('lets the close through when quitting, background mode or not', () => {
+ expect(closeAction('win32', true, false, true)).toBe('default')
+ expect(closeAction('linux', true, true, true)).toBe('default')
+ })
+ it('macOS is unchanged by the background flag (it always hides)', () => {
+ for (const bg of [false, true]) {
+ expect(closeAction('darwin', false, false, bg)).toBe('hide')
+ expect(closeAction('darwin', false, true, bg)).toBe('leave-fullscreen-then-hide')
+ expect(closeAction('darwin', true, true, bg)).toBe('default')
+ }
+ })
})
diff --git a/src/main/main-window.ts b/src/main/main-window.ts
index 8988ae837..d65586cc9 100644
--- a/src/main/main-window.ts
+++ b/src/main/main-window.ts
@@ -69,9 +69,16 @@ export function createCrashReloadPolicy(
// macOS convention: closing the window hides it (the app — and its tmux sessions,
// hook server, updater, license watchers — keeps running); a real close only happens
-// on quit. Other platforms quit on window close, so never intercept there.
-export function shouldHideOnClose(platform: NodeJS.Platform | string, quitting: boolean): boolean {
- return platform === 'darwin' && !quitting
+// on quit. On Windows/Linux the same hide is opt-in "background mode"
+// (`settings.runInBackgroundOnClose`, resolved by `resolveBackgroundOnClose` in
+// ./background-mode): the window hides to the notification-area tray so the phone relay
+// host, hook server and notifications outlive it. Off ⇒ close quits, as it always did.
+export function shouldHideOnClose(
+ platform: NodeJS.Platform | string,
+ quitting: boolean,
+ backgroundOnClose = false
+): boolean {
+ return !quitting && (platform === 'darwin' || backgroundOnClose)
}
export type CloseAction = 'default' | 'hide' | 'leave-fullscreen-then-hide'
@@ -82,12 +89,14 @@ export type CloseAction = 'default' | 'hide' | 'leave-fullscreen-then-hide'
* known Electron behavior electron/electron#20263) — so fullscreen must be exited, the async
* `leave-full-screen` transition awaited, and only THEN the window hidden. The quit path is not
* affected: there the window really closes and the app (and its Space) goes away with it.
+ * Spaces are a macOS concept, so a background-mode hide elsewhere is a plain hide.
*/
export function closeAction(
platform: NodeJS.Platform | string,
quitting: boolean,
- isFullScreen: boolean
+ isFullScreen: boolean,
+ backgroundOnClose = false
): CloseAction {
- if (!shouldHideOnClose(platform, quitting)) return 'default'
- return isFullScreen ? 'leave-fullscreen-then-hide' : 'hide'
+ if (!shouldHideOnClose(platform, quitting, backgroundOnClose)) return 'default'
+ return platform === 'darwin' && isFullScreen ? 'leave-fullscreen-then-hide' : 'hide'
}
diff --git a/src/renderer/components/settings/sections/BehaviorSection.tsx b/src/renderer/components/settings/sections/BehaviorSection.tsx
index 93462c681..5fee12b7a 100644
--- a/src/renderer/components/settings/sections/BehaviorSection.tsx
+++ b/src/renderer/components/settings/sections/BehaviorSection.tsx
@@ -7,7 +7,10 @@ import { NumberField } from '@renderer/ui/NumberField'
import { Select } from '@renderer/ui/Select'
import { SegmentedPill } from '@renderer/ui/SegmentedPill'
import { Input } from '@renderer/ui/Input'
-import { hintLabel } from '@shared/platform-utils'
+import { hintLabel, isMacPlatform, isWindowsPlatform } from '@shared/platform-utils'
+import { isBrowserRuntime } from '@renderer/bridge/runtime'
+import { backgroundCloseDescription, backgroundCloseRowVisible } from '@renderer/lib/backgroundClose'
+import type { BackgroundOnCloseSetting } from '@shared/types'
import { clampWheelZoomSpeed } from '@renderer/canvas/wheel-zoom'
import { DEFAULT_WORKTREE_PATH_TEMPLATE } from '@shared/worktree'
@@ -92,9 +95,16 @@ const ROWS = {
confirmQuit: {
title: 'Confirm before quitting',
keywords: ['quit', 'exit', 'close', 'confirm', 'dialog', 'ask']
+ },
+ backgroundClose: {
+ title: 'Keep running when the window closes',
+ keywords: ['tray', 'background', 'close', 'minimize', 'notification area', 'system tray', 'quit', 'phone']
}
}
-const ENTRIES = Object.values(ROWS)
+// The background-close row only exists for a desktop window off macOS, so search must not offer
+// it anywhere else. Decided once: neither the platform nor the runtime changes under a live page.
+const SHOW_BACKGROUND_CLOSE = backgroundCloseRowVisible(isMacPlatform(), isBrowserRuntime())
+const ENTRIES = Object.values(ROWS).filter((r) => SHOW_BACKGROUND_CLOSE || r !== ROWS.backgroundClose)
export function BehaviorSection({ isActive }: { isActive: boolean }): React.JSX.Element {
const settings = useSettings((s) => s.settings)
@@ -467,6 +477,25 @@ export function BehaviorSection({ isActive }: { isActive: boolean }): React.JSX.
}
/>
</SearchableRow>
+ {SHOW_BACKGROUND_CLOSE && (
+ <SearchableRow {...ROWS.backgroundClose}>
+ <FieldRow
+ label="Keep running when the window closes"
+ description={backgroundCloseDescription(isWindowsPlatform())}
+ control={
+ <Select
+ aria-label="Keep running when the window closes"
+ value={settings.runInBackgroundOnClose}
+ onChange={(e) => update({ runInBackgroundOnClose: e.target.value as BackgroundOnCloseSetting })}
+ >
+ <option value="auto">Automatic</option>
+ <option value="on">Always</option>
+ <option value="off">Never (closing quits)</option>
+ </Select>
+ }
+ />
+ </SearchableRow>
+ )}
</SettingsSection>
)
}
diff --git a/src/renderer/lib/backgroundClose.test.ts b/src/renderer/lib/backgroundClose.test.ts
new file mode 100644
index 000000000..56945970a
--- /dev/null
+++ b/src/renderer/lib/backgroundClose.test.ts
@@ -0,0 +1,24 @@
+import { describe, expect, it } from 'vitest'
+import { backgroundCloseDescription, backgroundCloseRowVisible } from './backgroundClose'
+
+describe('backgroundCloseRowVisible', () => {
+ it('shows only for a desktop window off macOS', () => {
+ expect(backgroundCloseRowVisible(false, false)).toBe(true)
+ expect(backgroundCloseRowVisible(true, false)).toBe(false)
+ expect(backgroundCloseRowVisible(false, true)).toBe(false)
+ expect(backgroundCloseRowVisible(true, true)).toBe(false)
+ })
+})
+
+describe('backgroundCloseDescription', () => {
+ it('names the Windows notification area and its automatic default', () => {
+ const d = backgroundCloseDescription(true)
+ expect(d).toContain('notification area')
+ expect(d).toContain('Automatic keeps it running on Windows')
+ })
+ it('says Automatic quits on Linux (matches resolveBackgroundOnClose)', () => {
+ const d = backgroundCloseDescription(false)
+ expect(d).toContain('system tray')
+ expect(d).toContain('Automatic quits on Linux')
+ })
+})
diff --git a/src/renderer/lib/backgroundClose.ts b/src/renderer/lib/backgroundClose.ts
new file mode 100644
index 000000000..39a44f527
--- /dev/null
+++ b/src/renderer/lib/backgroundClose.ts
@@ -0,0 +1,15 @@
+// Settings → Behavior "Keep running when the window closes" (settings.runInBackgroundOnClose).
+// Pure so the visibility + copy decisions are testable without a DOM. The policy itself is
+// `resolveBackgroundOnClose` in src/main/background-mode.ts — the copy here must describe it.
+
+/** Only a desktop window off macOS has the choice: macOS always keeps running in the Dock, and
+ * the Server Edition has no window to close (its browser tab is not the app). */
+export function backgroundCloseRowVisible(isMac: boolean, isBrowser: boolean): boolean {
+ return !isMac && !isBrowser
+}
+
+export function backgroundCloseDescription(isWindows: boolean): string {
+ const where = isWindows ? 'notification area' : 'system tray'
+ const auto = isWindows ? 'Automatic keeps it running on Windows.' : 'Automatic quits on Linux, where a tray icon depends on your desktop.'
+ return `Closing the window hides nodeterm to the ${where} so phone access, agent notifications and updates keep working. Quit from the tray icon or Ctrl+Q. ${auto}`
+}
diff --git a/src/shared/types.ts b/src/shared/types.ts
index 679d2e87a..91acbbb75 100644
--- a/src/shared/types.ts
+++ b/src/shared/types.ts
@@ -1750,6 +1750,9 @@ export interface ZoomActualSizeModifiers {
}
/** User-configurable application settings (settings.json). */
+/** `settings.runInBackgroundOnClose` — see the field's doc. */
+export type BackgroundOnCloseSetting = 'auto' | 'on' | 'off'
+
export interface Settings {
fontSize: number
fontFamily: string
@@ -2222,6 +2225,14 @@ export interface Settings {
* The auto-update "Restart to update" flow never asks — that decision was already made.
* Settings → Behavior. */
confirmBeforeQuit: boolean
+ /** Windows/Linux "background mode": closing the window hides it to the notification-area tray
+ * instead of quitting, so the phone relay host, hook server, notifications and updater keep
+ * running — the analogue of macOS keeping the app in the Dock. `'auto'` (default) = on for
+ * Windows, off for Linux (whose tray support depends on the desktop environment). Resolved by
+ * `resolveBackgroundOnClose` (src/main/background-mode.ts); ignored on macOS (always hides) and
+ * on the Server Edition (no window). Hand-editable: an unknown value reads as `'auto'`.
+ * Settings → Behavior (Windows/Linux only). */
+ runInBackgroundOnClose: BackgroundOnCloseSetting
/** macOS Notch HUD (docs/notch-hud.md): a transparent always-on-top strip by the notch showing
* walking agent mascots while agents work, expanding into a mini session panel. Default on;
* macOS + desktop only (ignored on other platforms / Server Edition). */
@@ -2434,6 +2445,8 @@ export const DEFAULT_SETTINGS: Settings = {
// Confirm-before-quit default ON: sessions survive a quit anyway, but an accidental ⌘Q
// tears down every window at once; the toggle is one switch away for who finds it noisy.
confirmBeforeQuit: true,
+ // Background mode 'auto' = on for Windows (the tray is always there), off for Linux.
+ runInBackgroundOnClose: 'auto',
// macOS Notch HUD default ON (guarded to darwin at runtime; a no-op elsewhere).
notchHud: true,
notchWidth: 168,