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.

8.8 KB
Raw Blame
import {
  persistenceDescription,
  sessionBackendNote,
  usePersistenceStatus
} from '../../usePersistenceStatus'
import { useSettings } from '../../../state/settings'
import { SettingsSection } from '../SettingsSection'
import { SearchableRow } from '../SearchableRow'
import { FieldRow } from '../FieldRow'
import { Switch } from '@renderer/ui/Switch'
import { NumberField } from '@renderer/ui/NumberField'
import { Select } from '@renderer/ui/Select'
import { normalizeSessionBackend, ZELLIJ_BACKEND_GAPS } from '@shared/session-backend'
import { XTERM_SCROLLBACK_MAX } from '@shared/scrollback'
import {
  LEAD_PANE_WIDTH_DEFAULT,
  LEAD_PANE_WIDTH_MAX,
  LEAD_PANE_WIDTH_MIN
} from '@shared/tmux-lead-pane'
import {
  PARK_MAX,
  PARK_MAX_LIMIT,
  PARK_MINUTES_DEFAULT,
  PARK_MINUTES_MAX
} from '@renderer/terminal/park-budget'

const ROWS = {
  enabled: {
    title: 'Persistent sessions',
    keywords: ['tmux', 'persistent', 'session', 'continuity', 'protection', 'host']
  },
  backend: {
    title: 'Session backend',
    keywords: ['tmux', 'zellij', 'backend', 'multiplexer', 'session', 'persistent']
  },
  scrollback: { title: 'Scrollback lines', keywords: ['tmux', 'scrollback', 'history', 'lines'] },
  leadPane: {
    title: 'Keep lead pane wide (agent teams)',
    keywords: ['lead', 'pane', 'width', 'agent', 'team', 'teammates', 'split', 'claude', 'resize']
  },
  parkMinutes: {
    title: 'Keep switched-away terminals attached',
    keywords: ['park', 'switch', 'project', 'ssh', 'fast', 'instant', 'reattach', 'minutes', 'memory']
  },
  parkMax: {
    title: 'Max attached terminals in other projects',
    keywords: ['park', 'cap', 'limit', 'switch', 'project', 'ssh', 'reattach', 'memory', 'ram']
  },
  offscreen: {
    title: 'Release offscreen terminals',
    keywords: ['offscreen', 'memory', 'ram', 'release', 'reattach', 'idle', 'minutes']
  }
}
const ENTRIES = Object.values(ROWS)

export function TmuxSection({ isActive }: { isActive: boolean }): React.JSX.Element {
  const status = usePersistenceStatus()
  const settings = useSettings((s) => s.settings)
  const update = useSettings((s) => s.update)
  return (
    <SettingsSection
      id="tmux"
      title="Session protection"
      description="Applies to new terminals / next launch."
      isActive={isActive}
      searchEntries={ENTRIES}
    >
      <SearchableRow {...ROWS.enabled}>
        <FieldRow
          label="Persistent sessions"
          description={persistenceDescription(status)}
          control={
            <Switch
              checked={settings.tmuxEnabled}
              onChange={(v) => update({ tmuxEnabled: v })}
              ariaLabel="Persistent sessions"
            />
          }
        />
      </SearchableRow>
      {status?.zellij ? (
        <SearchableRow {...ROWS.backend}>
          <FieldRow
            label="Session backend"
            description={sessionBackendNote(status.zellij)}
            note={
              normalizeSessionBackend(settings.sessionBackend) === 'zellij'
                ? `Not available with Zellij: ${ZELLIJ_BACKEND_GAPS.join(' ')}`
                : undefined
            }
            control={
              <Select
                aria-label="Session backend"
                value={normalizeSessionBackend(settings.sessionBackend)}
                onChange={(e) => update({ sessionBackend: normalizeSessionBackend(e.target.value) })}
              >
                <option value="tmux">tmux</option>
                <option value="zellij">Zellij</option>
              </Select>
            }
          />
        </SearchableRow>
      ) : null}
      <SearchableRow {...ROWS.scrollback}>
        <FieldRow
          label="Scrollback lines"
          description={
            'tmux’s history-limit for each terminal. ' +
            `Without tmux (Windows), history is capped at ${XTERM_SCROLLBACK_MAX.toLocaleString('en-US')} lines: the app holds it at full width in memory.`
          }
          control={
            <NumberField
              value={settings.tmuxScrollback}
              min={1000}
              max={200000}
              step={1000}
              onChange={(v) => update({ tmuxScrollback: v || 50000 })}
            />
          }
        />
      </SearchableRow>
      <SearchableRow {...ROWS.leadPane}>
        <FieldRow
          label="Keep lead pane wide (agent teams)"
          description={
            'Claude Code agent teams re-apply a hardcoded 70/30 tmux split on every teammate spawn, squeezing the pane you type into. ' +
            'When on, guarded tmux hooks keep the lead pane at the chosen % of the node width (40–90), locally and on SSH hosts (at next connect). ' +
            'Side effect: a manual 50/50 split in a plain terminal is nudged to the same width. ' +
            'Turning it off leaves a running tmux server’s hooks in place until that server exits (close all terminals, or tmux -L node-terminal kill-server).'
          }
          control={
            <div className="flex items-center gap-2">
              {settings.tmuxLeadPaneWidth > 0 ? (
                <NumberField
                  value={settings.tmuxLeadPaneWidth}
                  min={LEAD_PANE_WIDTH_MIN}
                  max={LEAD_PANE_WIDTH_MAX}
                  step={1}
                  ariaLabel="Lead pane width (%)"
                  // Raw value stored; out-of-range hand edits are re-validated where the conf is
                  // generated (sanitizeLeadPaneWidth), so mid-typing values never snap under the
                  // user's cursor.
                  onChange={(v) => update({ tmuxLeadPaneWidth: Number.isFinite(v) ? v : 0 })}
                />
              ) : null}
              <Switch
                checked={settings.tmuxLeadPaneWidth > 0}
                onChange={(v) => update({ tmuxLeadPaneWidth: v ? LEAD_PANE_WIDTH_DEFAULT : 0 })}
                ariaLabel="Keep lead pane wide"
              />
            </div>
          }
        />
      </SearchableRow>
      <SearchableRow {...ROWS.parkMinutes}>
        <FieldRow
          label="Keep switched-away terminals attached"
          description={
            'Minutes a project’s terminals stay attached after you switch to another project, so switching back is instant. ' +
            'After that they reattach on return — seconds per project over SSH. 0 = until the app quits. ' +
            `Default ${PARK_MINUTES_DEFAULT}. Applies from the next switch.`
          }
          control={
            <NumberField
              value={settings.terminalParkMinutes}
              min={0}
              max={PARK_MINUTES_MAX}
              step={1}
              ariaLabel="Park window (minutes)"
              // A cleared field reads back as the DEFAULT, not 0: 0 means "keep forever", the
              // memory-expensive end, and must only ever be typed on purpose.
              onChange={(v) =>
                update({
                  terminalParkMinutes: Number.isFinite(v) ? Math.max(0, v) : PARK_MINUTES_DEFAULT
                })
              }
            />
          }
        />
      </SearchableRow>
      <SearchableRow {...ROWS.parkMax}>
        <FieldRow
          label="Max attached terminals in other projects"
          description={
            'How many switched-away terminals stay attached in total. Beyond this the oldest are released early — local ones before SSH ones, which are slower to reattach. ' +
            'Each costs about 2 MB with tmux (more without tmux: its scrollback lives in the app) and, over SSH, one local ssh client on the project’s connection. ' +
            `Default ${PARK_MAX}.`
          }
          control={
            <NumberField
              value={settings.terminalParkMax}
              min={1}
              max={PARK_MAX_LIMIT}
              step={1}
              ariaLabel="Max parked terminals"
              onChange={(v) =>
                update({ terminalParkMax: Number.isFinite(v) && v >= 1 ? Math.floor(v) : PARK_MAX })
              }
            />
          }
        />
      </SearchableRow>
      <SearchableRow {...ROWS.offscreen}>
        <FieldRow
          label="Release offscreen terminals"
          description="Minutes a terminal may sit offscreen before its view is released (tmux keeps it running; it reattaches on view). 0 = never."
          control={
            <NumberField
              value={settings.offscreenTerminalMinutes}
              min={0}
              max={240}
              step={1}
              // A cleared/invalid field reads back as 0 = "never", the safe end of this setting.
              // Never NaN: `offscreenDisposeMs` would read it as "off" anyway, but NaN does not
              // survive a JSON round-trip to settings.json (it lands as `null`).
              onChange={(v) =>
                update({ offscreenTerminalMinutes: Number.isFinite(v) ? Math.max(0, v) : 0 })
              }
            />
          }
        />
      </SearchableRow>
    </SettingsSection>
  )
}