feat: expose flicker-free mode as a /config toggle (closes #260) (#265)

Add flickerFreeMode to GlobalConfig so external users can enable
fullscreen alt-screen mode via /config instead of having to set
the CLAUDE_CODE_NO_FLICKER=1 env var manually.

Priority order in isFullscreenEnvEnabled():
  CLAUDE_CODE_NO_FLICKER=0  → always off (env wins)
  CLAUDE_CODE_NO_FLICKER=1  → always on (env wins)
  tmux -CC detected         → off (terminal safety guard)
  config flickerFreeMode    → user preference (new)
  USER_TYPE=ant             → internal default

The env var still takes full precedence so existing scripts and
automation are unaffected. The new setting only activates when
flickerFreeMode is explicitly set in config.

src/components/Settings/Config.tsx

@@ -631,7 +631,26 @@ export function Config({
         value: String(copyOnSelect) as AnalyticsMetadata_I_VERIFIED_THIS_IS_NOT_CODE_OR_FILEPATHS
       });
     }
-  }] : []),
+  }] : []), {
+    id: 'flickerFreeMode',
+    label: 'Flicker-free mode',
+    value: globalConfig.flickerFreeMode ?? (process.env.USER_TYPE === 'ant'),
+    type: 'boolean' as const,
+    onChange(flickerFreeMode: boolean) {
+      saveGlobalConfig(current => ({
+        ...current,
+        flickerFreeMode
+      }));
+      setGlobalConfig({
+        ...getGlobalConfig(),
+        flickerFreeMode
+      });
+      logEvent('tengu_config_changed', {
+        setting: 'flickerFreeMode' as AnalyticsMetadata_I_VERIFIED_THIS_IS_NOT_CODE_OR_FILEPATHS,
+        value: String(flickerFreeMode) as AnalyticsMetadata_I_VERIFIED_THIS_IS_NOT_CODE_OR_FILEPATHS
+      });
+    }
+  },
   // autoUpdates setting is hidden - use DISABLE_AUTOUPDATER env var to control
   autoUpdaterDisabledReason ? {
     id: 'autoUpdatesChannel',

src/utils/config.ts

@@ -464,6 +464,11 @@ export type GlobalConfig = {
   // Fullscreen in-app text selection behavior
   copyOnSelect?: boolean // Auto-copy to clipboard on mouse-up (undefined → true; lets cmd+c "work" via no-op)
 
+  // Flicker-free fullscreen mode (equivalent to CLAUDE_CODE_NO_FLICKER=1 env var).
+  // When true, enables alt-screen + virtualized scroll for all users.
+  // Env var still takes precedence: =0 always off, =1 always on.
+  flickerFreeMode?: boolean
+
   // GitHub repo path mapping for teleport directory switching
   // Key: "owner/repo" (lowercase), Value: array of absolute paths where repo is cloned
   githubRepoPaths?: Record<string, string[]>
@@ -659,6 +664,7 @@ export const GLOBAL_CONFIG_KEYS = [
   'lspRecommendationIgnoredCount',
   'copyFullResponse',
   'copyOnSelect',
+  'flickerFreeMode',
   'permissionExplainerEnabled',
   'prStatusFooterEnabled',
   'remoteControlAtStartup',

src/utils/fullscreen.ts

@@ -1,5 +1,6 @@
 import { spawnSync } from 'child_process'
 import { getIsInteractive } from '../bootstrap/state.js'
+import { getGlobalConfig } from './config.js'
 import { logForDebugging } from './debug.js'
 import { isEnvDefinedFalsy, isEnvTruthy } from './envUtils.js'
 import { execFileNoThrow } from './execFileNoThrow.js'
@@ -105,14 +106,21 @@ export function _resetTmuxControlModeProbeForTesting(): void {
 }
 
 /**
- * Runtime env-var check only. Ants default to on (CLAUDE_CODE_NO_FLICKER=0
- * to opt out); external users default to off (CLAUDE_CODE_NO_FLICKER=1 to
- * opt in).
+ * Whether fullscreen (flicker-free) mode is enabled. Env var takes highest
+ * precedence, then the `flickerFreeMode` config setting, then the ant-only
+ * default. External users can enable via `/config` instead of setting the env.
+ *
+ * Priority order:
+ *   CLAUDE_CODE_NO_FLICKER=0  → always off
+ *   CLAUDE_CODE_NO_FLICKER=1  → always on (overrides tmux -CC guard too)
+ *   tmux -CC detected         → off (corrupts terminal state)
+ *   config flickerFreeMode    → on/off per user preference
+ *   USER_TYPE=ant             → on by default for internal users
  */
 export function isFullscreenEnvEnabled(): boolean {
-  // Explicit user opt-out always wins.
+  // Explicit env opt-out always wins.
   if (isEnvDefinedFalsy(process.env.CLAUDE_CODE_NO_FLICKER)) return false
-  // Explicit opt-in overrides auto-detection (escape hatch).
+  // Explicit env opt-in overrides everything including tmux -CC.
   if (isEnvTruthy(process.env.CLAUDE_CODE_NO_FLICKER)) return true
   // Auto-disable under tmux -CC: alt-screen + mouse tracking corrupts
   // terminal state on double-click and mouse wheel is dead.
@@ -125,6 +133,10 @@ export function isFullscreenEnvEnabled(): boolean {
     }
     return false
   }
+  // Config-based toggle: lets external users enable flicker-free mode via
+  // `/config` without having to set an env var.
+  const configValue = getGlobalConfig().flickerFreeMode
+  if (configValue !== undefined) return configValue
   return process.env.USER_TYPE === 'ant'
 }