feat(tui): group vertical tabs by project with nested children

Author: sharunkumar

PATCH.md

@@ -85,6 +85,10 @@ Session tabs default to vertical in the TUI (`tabs.layout`) and desktop app (`ap
 
 Expanded vertical tab titles word-wrap onto as many rows as they need instead of cropping, and the tab grows to fit; the compact rail and project line still crop.
 
+## Vertical Tab Project Groups (TUI)
+
+The expanded vertical rail groups tabs under project headers and nests child sessions under their parent tab; manual tab reordering is disabled while `tabs.layout` is vertical.
+
 ## Session List Preview (TUI) [NOT MIGRATED]
 
 The session list (`<leader>l`) previews the highlighted session's latest messages on terminals 128 columns or wider.

packages/tui/src/component/session-tabs.tsx

@@ -99,6 +99,33 @@ export function moveSessionTab(tabs: SessionTab[], sessionID: string, index: num
   return next
 }
 
+/** Keeps each group's tabs contiguous, ordering groups by their first tab and tabs by their stored order. */
+export function groupSessionTabs(tabs: SessionTab[], groupOf: (sessionID: string) => string | undefined) {
+  return [...Map.groupBy(tabs, (tab) => groupOf(tab.sessionID) ?? "").values()].flat()
+}
+
+export type SessionTabChild = { sessionID: string; prefix: string }
+
+/** Descendants of a tab's root session in creation order, with tree-guide prefixes such as "│  └─ ". */
+export function sessionTabChildren(
+  rootID: string,
+  sessions: readonly { id: string; parentID?: string; created: number }[],
+) {
+  const byParent = Map.groupBy(
+    sessions.filter((session) => session.parentID).toSorted((a, b) => a.created - b.created),
+    (session) => session.parentID,
+  )
+  const walk = (parentID: string, indent: string): SessionTabChild[] =>
+    (byParent.get(parentID) ?? []).flatMap((child, index, siblings) => {
+      const last = index === siblings.length - 1
+      return [
+        { sessionID: child.id, prefix: indent + (last ? "└─ " : "├─ ") },
+        ...walk(child.id, indent + (last ? "   " : "│  ")),
+      ]
+    })
+  return walk(rootID, "")
+}
+
 export function cycleSessionTab(
   tabs: readonly SessionTab[],
   active: string | undefined,

packages/tui/src/context/session-tabs-model.ts

@@ -18,6 +18,7 @@ import { anchorKey, type AnchorTarget } from "../routes/session/anchors"
 import {
   closeSessionTab,
   cycleSessionTab,
+  groupSessionTabs,
   moveSessionTab,
   moveSessionTabHistory,
   NEW_SESSION_TAB_TITLE,
@@ -136,6 +137,11 @@ export const { use: useSessionTabs, provider: SessionTabsProvider } = createSimp
       unread: {},
     })
     const current = () => (route.data.type === "session" ? root(route.data.sessionID) : undefined)
+    const grouped = () => config.tabs.layout === "vertical"
+    // The vertical rail renders project groups, so numbering, cycling, and selection follow that order.
+    const ordered = createMemo(() =>
+      grouped() ? groupSessionTabs(state().tabs, (id) => data.session.get(id)?.projectID) : state().tabs,
+    )
     createSessionRetention({
       session: data.session,
       current: () =>
@@ -335,7 +341,7 @@ export const { use: useSessionTabs, provider: SessionTabsProvider } = createSimp
       const previous = selected
         ? moveSessionTabHistory(recordSessionTabHistory(history, target), closed.tabs, target, -1)
         : { history, sessionID: undefined }
-      const next = previous.sessionID ?? closed.next
+      const next = previous.sessionID ?? closeSessionTab(ordered(), target).next
       history = previous.history
       update((draft) => {
         draft.tabs = closeSessionTab(draft.tabs, target).tabs
@@ -352,7 +358,14 @@ export const { use: useSessionTabs, provider: SessionTabsProvider } = createSimp
     return {
       enabled,
       tabs() {
-        return state().tabs
+        return ordered()
+      },
+      viewing() {
+        return route.data.type === "session" ? route.data.sessionID : undefined
+      },
+      selectChild(sessionID: string) {
+        if (!enabled()) return
+        route.navigate({ type: "session", sessionID })
       },
       recentlyClosed() {
         return closedTabs()
@@ -445,7 +458,7 @@ export const { use: useSessionTabs, provider: SessionTabsProvider } = createSimp
         route.navigate({ type: "session", sessionID: result.sessionID })
       },
       move(sessionID: string, index: number) {
-        if (!enabled()) return
+        if (!enabled() || grouped()) return
         const session = root(sessionID)
         if (moveSessionTab(state().tabs, session, index) === state().tabs) return
         update((draft) => {
@@ -454,19 +467,19 @@ export const { use: useSessionTabs, provider: SessionTabsProvider } = createSimp
       },
       cycle(direction: 1 | -1) {
         if (!enabled()) return
-        const tab = cycleSessionTab(state().tabs, current(), direction)
+        const tab = cycleSessionTab(ordered(), current(), direction)
         if (tab) route.navigate({ type: "session", sessionID: tab.sessionID })
       },
       cycleUnread(direction: 1 | -1) {
         if (!enabled()) return
-        const tab = cycleSessionTab(state().tabs, current(), direction, (tab) =>
+        const tab = cycleSessionTab(ordered(), current(), direction, (tab) =>
           Boolean(status(tab.sessionID).unread || status(tab.sessionID).attention),
         )
         if (tab) route.navigate({ type: "session", sessionID: tab.sessionID })
       },
       selectIndex(index: number) {
         if (!enabled()) return
-        const tab = state().tabs[index]
+        const tab = ordered()[index]
         if (tab) route.navigate({ type: "session", sessionID: tab.sessionID })
       },
     }

packages/tui/src/context/session-tabs.tsx

@@ -160,6 +160,9 @@ function SessionTabsStory(props: { context: Plugin.Context }) {
     detail(sessionID) {
       return FIXTURE_TABS.find((tab) => tab.sessionID === sessionID)?.project
     },
+    group(sessionID) {
+      return FIXTURE_TABS.find((tab) => tab.sessionID === sessionID)?.project
+    },
     status(sessionID) {
       return statuses()[sessionID] ?? EMPTY_SESSION_TAB_STATUS
     },

packages/tui/src/feature-plugins/system/storybook/session-tabs.tsx

@@ -3,13 +3,15 @@ import {
   adaptiveSessionTabLayout,
   closeSessionTab,
   cycleSessionTab,
+  groupSessionTabs,
   moveSessionTab,
   moveSessionTabHistory,
   openSessionTab,
   recordClosedSessionTab,
   recordSessionTabHistory,
   reopenSessionTab,
   seedSessionTabMotion,
+  sessionTabChildren,
   sessionTabComplete,
   sessionTabDetail,
   sessionTabOverflowWidth,
@@ -25,6 +27,27 @@ describe("session tabs", () => {
     expect(sessionTabDetail("opencode", undefined, "main", true)).toBe("opencode")
   })
 
+  test("groups tabs by project in first-appearance order", () => {
+    const tabs = ["a", "b", "c", "d"].map((sessionID) => ({ sessionID }))
+    const project = { a: "web", b: "api", c: "web" } as Record<string, string>
+    expect(groupSessionTabs(tabs, (id) => project[id]).map((tab) => tab.sessionID)).toEqual(["a", "c", "b", "d"])
+  })
+
+  test("nests session descendants in creation order", () => {
+    expect(
+      sessionTabChildren("root", [
+        { id: "root", created: 0 },
+        { id: "late", parentID: "root", created: 3 },
+        { id: "early", parentID: "root", created: 1 },
+        { id: "grandchild", parentID: "early", created: 2 },
+      ]),
+    ).toEqual([
+      { sessionID: "early", prefix: "├─ " },
+      { sessionID: "grandchild", prefix: "│  └─ " },
+      { sessionID: "late", prefix: "└─ " },
+    ])
+  })
+
   test("labels tabs by ordinal", () => {
     expect(Array.from({ length: 12 }, (_, index) => sessionTabNumberLabel(index))).toEqual([
       "1",

packages/tui/test/context/session-tabs-model.test.ts

@@ -41,6 +41,8 @@ async function renderSessionTabs(
     newLocation?: "launch" | "inherit"
     launchDirectory?: string
     tabsEnabled?: boolean
+    layout?: "horizontal" | "vertical"
+    sessionProjects?: Record<string, string>
     viewFailures?: number
     experimental?: Record<string, boolean>
   },
@@ -120,7 +122,7 @@ async function renderSessionTabs(
       id: sessionID,
       parentID: options?.sessionParents?.[sessionID],
       title: sessionID === initialSessionID ? options?.title : undefined,
-      projectID: "project",
+      projectID: options?.sessionProjects?.[sessionID] ?? "project",
       location: { directory: options?.sessionDirectories?.[sessionID] ?? directory },
       cost: 0,
       tokens: { input: 0, output: 0, reasoning: 0, cache: { read: 0, write: 0 } },
@@ -135,7 +137,10 @@ async function renderSessionTabs(
   let storage!: ReturnType<typeof useStorage>
   let config!: ReturnType<typeof useConfig>
   let configuration = {
-    tabs: { mode: options?.tabsEnabled === false ? ("off" as const) : ("on" as const) },
+    tabs: {
+      mode: options?.tabsEnabled === false ? ("off" as const) : ("on" as const),
+      layout: options?.layout,
+    },
     experimental: options?.experimental,
     session: { new_location: options?.newLocation ?? "launch" },
   }
@@ -266,7 +271,7 @@ test("loads VCS metadata for each persisted tab location", async () => {
 })
 
 test("opens a background tab without changing the current session", async () => {
-  const setup = await renderSessionTabs("first")
+  const setup = await renderSessionTabs("first", { layout: "horizontal" })
 
   try {
     await wait(() => setup.tabs.current() === "first" && setup.tabs.tabs().some((tab) => tab.sessionID === "first"))
@@ -281,6 +286,29 @@ test("opens a background tab without changing the current session", async () =>
   }
 })
 
+test("groups vertical tabs by project and ignores manual moves", async () => {
+  const setup = await renderSessionTabs("first", {
+    persisted: ["first", "second", "third"],
+    sessionProjects: { first: "web", second: "api", third: "web" },
+  })
+
+  try {
+    await wait(() => setup.data.session.get("third") !== undefined && setup.data.session.get("second") !== undefined)
+    await wait(
+      () =>
+        setup.tabs
+          .tabs()
+          .map((tab) => tab.sessionID)
+          .join() === "first,third,second",
+    )
+    setup.tabs.move("second", 0)
+    await Bun.sleep(50)
+    expect(setup.tabs.tabs().map((tab) => tab.sessionID)).toEqual(["first", "third", "second"])
+  } finally {
+    await setup.destroy()
+  }
+})
+
 test("loads location metadata when an open session moves", async () => {
   const destination = `${directory}/moved-worktree`
   const setup = await renderSessionTabs("first")