feat(tui): gate session switching behind OPENCODE_EXPERIMENTAL_SESSION_SWITCHING

nexxeln · nexxeln · commit 6a4ce54d615b · 2026-05-11T22:05:03.000+05:30
the new pinned/recent picker layout, quick-switch hotkeys, cycle-recent hotkeys, in-picker pin/toggle-recent actions, route MRU tracking, and discoverability tips are all gated on Flag.OPENCODE_EXPERIMENTAL_SESSION_SWITCHING. defaults off; opt in with OPENCODE_EXPERIMENTAL_SESSION_SWITCHING=true or the global OPENCODE_EXPERIMENTAL=true. pinned state is still loaded from session.json so toggling the flag is non-destructive.
diff --git a/packages/core/src/flag/flag.ts b/packages/core/src/flag/flag.ts
@@ -96,6 +96,8 @@ export const Flag = {
   OPENCODE_WORKSPACE_ID: process.env["OPENCODE_WORKSPACE_ID"],
   OPENCODE_EXPERIMENTAL_WORKSPACES: OPENCODE_EXPERIMENTAL || truthy("OPENCODE_EXPERIMENTAL_WORKSPACES"),
   OPENCODE_EXPERIMENTAL_EVENT_SYSTEM: OPENCODE_EXPERIMENTAL || truthy("OPENCODE_EXPERIMENTAL_EVENT_SYSTEM"),
+  OPENCODE_EXPERIMENTAL_SESSION_SWITCHING:
+    OPENCODE_EXPERIMENTAL || truthy("OPENCODE_EXPERIMENTAL_SESSION_SWITCHING"),
 
   // Evaluated at access time (not module load) because tests, the CLI, and
   // external tooling set these env vars at runtime.
diff --git a/packages/opencode/src/cli/cmd/tui/app.tsx b/packages/opencode/src/cli/cmd/tui/app.tsx
@@ -473,33 +473,37 @@ function App(props: { onSnapshot?: () => Promise<string[]> }) {
           dialog.clear()
         },
       },
-      {
-        name: "session.cycle_recent",
-        title: "Cycle to previous recent session",
-        category: "Session",
-        hidden: true,
-        run: () => {
-          local.session.cycleRecent(1)
-        },
-      },
-      {
-        name: "session.cycle_recent_reverse",
-        title: "Cycle to next recent session",
-        category: "Session",
-        hidden: true,
-        run: () => {
-          local.session.cycleRecent(-1)
-        },
-      },
-      ...Array.from({ length: 9 }, (_, i) => ({
-        name: `session.quick_switch.${i + 1}`,
-        title: `Switch to session in quick slot ${i + 1}`,
-        category: "Session",
-        hidden: true,
-        run: () => {
-          local.session.quickSwitch(i + 1)
-        },
-      })),
+      ...(Flag.OPENCODE_EXPERIMENTAL_SESSION_SWITCHING
+        ? [
+            {
+              name: "session.cycle_recent",
+              title: "Cycle to previous recent session",
+              category: "Session",
+              hidden: true,
+              run: () => {
+                local.session.cycleRecent(1)
+              },
+            },
+            {
+              name: "session.cycle_recent_reverse",
+              title: "Cycle to next recent session",
+              category: "Session",
+              hidden: true,
+              run: () => {
+                local.session.cycleRecent(-1)
+              },
+            },
+            ...Array.from({ length: 9 }, (_, i) => ({
+              name: `session.quick_switch.${i + 1}`,
+              title: `Switch to session in quick slot ${i + 1}`,
+              category: "Session",
+              hidden: true,
+              run: () => {
+                local.session.quickSwitch(i + 1)
+              },
+            })),
+          ]
+        : []),
       {
         name: "model.list",
         title: "Switch model",
@@ -814,7 +818,14 @@ function App(props: { onSnapshot?: () => Promise<string[]> }) {
 
   useBindings(() => ({
     enabled: command.matcher,
-    bindings: tuiConfig.keybinds.gather("app", appBindingCommands),
+    bindings: tuiConfig.keybinds.gather(
+      "app",
+      Flag.OPENCODE_EXPERIMENTAL_SESSION_SWITCHING
+        ? appBindingCommands
+        : appBindingCommands.filter(
+            (c) => !c.startsWith("session.cycle_recent") && !c.startsWith("session.quick_switch"),
+          ),
+    ),
   }))
 
   useBindings(() => ({
diff --git a/packages/opencode/src/cli/cmd/tui/component/dialog-session-list.tsx b/packages/opencode/src/cli/cmd/tui/component/dialog-session-list.tsx
@@ -133,6 +133,7 @@ export function DialogSessionList() {
   const RECENT_LIMIT = 5
 
   const options = createMemo(() => {
+    const enabled = Flag.OPENCODE_EXPERIMENTAL_SESSION_SWITCHING
     const today = new Date().toDateString()
     const sessionMap = new Map(
       sessions()
@@ -143,14 +144,16 @@ export function DialogSessionList() {
     const searchResult = searchResults()
     const displayOrder = searchResult ? orderByRecency(searchResult) : browseOrder()
 
-    const dismissed = new Set(local.session.dismissedRecent())
-    const pinned = local.session.pinned().filter((id) => sessionMap.has(id))
+    const dismissed = enabled ? new Set(local.session.dismissedRecent()) : new Set<string>()
+    const pinned = enabled ? local.session.pinned().filter((id) => sessionMap.has(id)) : []
     const pinnedSet = new Set(pinned)
-    const slotByID = new Map(local.session.slots().map((id, i) => [id, i + 1]))
+    const slotByID = enabled
+      ? new Map<string, number>(local.session.slots().map((id, i) => [id, i + 1]))
+      : new Map<string, number>()
 
-    const recent = displayOrder
-      .filter((id) => !pinnedSet.has(id) && !dismissed.has(id))
-      .slice(0, RECENT_LIMIT)
+    const recent = enabled
+      ? displayOrder.filter((id) => !pinnedSet.has(id) && !dismissed.has(id)).slice(0, RECENT_LIMIT)
+      : []
     const recentSet = new Set(recent)
 
     function buildOption(id: string, category: string) {
@@ -233,28 +236,32 @@ export function DialogSessionList() {
         dialog.clear()
       }}
       actions={[
-        {
-          command: "session.pin.toggle",
-          title: "pin/unpin",
-          onTrigger: (option) => {
-            local.session.togglePin(option.value)
-          },
-        },
-        {
-          command: "session.toggle.recent",
-          title: "toggle recent",
-          onTrigger: (option) => {
-            if (local.session.isPinned(option.value)) {
-              toast.show({
-                variant: "info",
-                message: "Unpin the session first to toggle it in Recent",
-                duration: 3000,
-              })
-              return
-            }
-            local.session.toggleRecent(option.value)
-          },
-        },
+        ...(Flag.OPENCODE_EXPERIMENTAL_SESSION_SWITCHING
+          ? [
+              {
+                command: "session.pin.toggle",
+                title: "pin/unpin",
+                onTrigger: (option: { value: string }) => {
+                  local.session.togglePin(option.value)
+                },
+              },
+              {
+                command: "session.toggle.recent",
+                title: "toggle recent",
+                onTrigger: (option: { value: string }) => {
+                  if (local.session.isPinned(option.value)) {
+                    toast.show({
+                      variant: "info",
+                      message: "Unpin the session first to toggle it in Recent",
+                      duration: 3000,
+                    })
+                    return
+                  }
+                  local.session.toggleRecent(option.value)
+                },
+              },
+            ]
+          : []),
         {
           command: "session.delete",
           title: "delete",
diff --git a/packages/opencode/src/cli/cmd/tui/context/local.tsx b/packages/opencode/src/cli/cmd/tui/context/local.tsx
@@ -8,6 +8,7 @@ import { useEvent } from "@tui/context/event"
 import { uniqueBy } from "remeda"
 import path from "path"
 import { Global } from "@opencode-ai/core/global"
+import { Flag } from "@opencode-ai/core/flag/flag"
 import { iife } from "@/util/iife"
 import { useToast } from "../ui/toast"
 import { useArgs } from "./args"
@@ -470,22 +471,24 @@ export const { use: useLocal, provider: LocalProvider } = createSimpleContext({
         prune(evt.properties.info.id)
       })
 
-      createEffect(
-        on(
-          () => (sessionStore.ready && route.data.type === "session" ? route.data.sessionID : undefined),
-          (sessionID) => {
-            if (!sessionID) return
-            if (cycling) {
-              cycling = false
-              return
-            }
-            const filtered = sessionStore.recentOrder.filter((x) => x !== sessionID)
-            const next = [sessionID, ...filtered].slice(0, 20)
-            setSessionStore("recentOrder", next)
-            save()
-          },
-        ),
-      )
+      if (Flag.OPENCODE_EXPERIMENTAL_SESSION_SWITCHING) {
+        createEffect(
+          on(
+            () => (sessionStore.ready && route.data.type === "session" ? route.data.sessionID : undefined),
+            (sessionID) => {
+              if (!sessionID) return
+              if (cycling) {
+                cycling = false
+                return
+              }
+              const filtered = sessionStore.recentOrder.filter((x) => x !== sessionID)
+              const next = [sessionID, ...filtered].slice(0, 20)
+              setSessionStore("recentOrder", next)
+              save()
+            },
+          ),
+        )
+      }
 
       return {
         get ready() {
diff --git a/packages/opencode/src/cli/cmd/tui/feature-plugins/home/tips-view.tsx b/packages/opencode/src/cli/cmd/tui/feature-plugins/home/tips-view.tsx
@@ -1,5 +1,6 @@
 import { createMemo, For } from "solid-js"
 import { DEFAULT_THEMES, useTheme } from "@tui/context/theme"
+import { Flag } from "@opencode-ai/core/flag/flag"
 
 const themeCount = Object.keys(DEFAULT_THEMES).length
 const themeTip = `Use {highlight}/themes{/highlight} or {highlight}Ctrl+X T{/highlight} to switch between ${themeCount} built-in themes`
@@ -66,10 +67,14 @@ const TIPS = [
   themeTip,
   "Press {highlight}Ctrl+X N{/highlight} or {highlight}/new{/highlight} to start a fresh conversation session",
   "Use {highlight}/sessions{/highlight} or {highlight}Ctrl+X L{/highlight} to list and continue previous conversations",
-  "Press {highlight}Ctrl+F{/highlight} in the session list to pin a session so it stays at the top",
-  "Pinned and recent sessions are bound to {highlight}Ctrl+X 1{/highlight} through {highlight}Ctrl+X 9{/highlight} for one-press switching",
-  "Press {highlight}Ctrl+X ]{/highlight} / {highlight}Ctrl+X [{/highlight} to cycle through recently visited sessions",
-  "Press {highlight}Ctrl+H{/highlight} in the session list to show or hide a session in the Recent group",
+  ...(Flag.OPENCODE_EXPERIMENTAL_SESSION_SWITCHING
+    ? [
+        "Press {highlight}Ctrl+F{/highlight} in the session list to pin a session so it stays at the top",
+        "Pinned and recent sessions are bound to {highlight}Ctrl+X 1{/highlight} through {highlight}Ctrl+X 9{/highlight} for one-press switching",
+        "Press {highlight}Ctrl+X ]{/highlight} / {highlight}Ctrl+X [{/highlight} to cycle through recently visited sessions",
+        "Press {highlight}Ctrl+H{/highlight} in the session list to show or hide a session in the Recent group",
+      ]
+    : []),
   "Run {highlight}/compact{/highlight} to summarize long sessions near context limits",
   "Press {highlight}Ctrl+X X{/highlight} or {highlight}/export{/highlight} to save the conversation as Markdown",
   "Press {highlight}Ctrl+X Y{/highlight} to copy the assistant's last message to clipboard",
