@brimveyn/aimux 1.3.1 → 1.4.0

package/README.md

@@ -11,6 +11,7 @@ A terminal multiplexer for AI CLIs. Manage multiple AI assistant sessions (Claud
 ## Features
 
 - **Multi-tab sessions** — Run Claude, Codex, and OpenCode in parallel with instant tab switching
+- **Session bar** — Numbered session chips at the top (or bottom) of the screen. Click to switch, drag to reorder, busy spinner for non-focused sessions with live PTY output. Toggle with `<leader>b`; jump with `<leader>1..9`. Position persists via `aimux.config.ts` or `aimux.json`.
 - **Split panes** — Split vertically (`|`) or horizontally (`-`) to view multiple assistants at once
 - **Draggable separators** — Resize split panes by dragging with the mouse
 - **Click-to-focus** — Click any pane or sidebar tab to focus it instantly
@@ -134,6 +135,8 @@ Press `?` in navigation mode for the full, live keybinding list (reflects your c
 | `Ctrl+S`              | Snippet picker       |
 | `Ctrl+T`              | Theme picker         |
 | `G`                   | Toggle git panel     |
+| `<leader>b`           | Toggle session bar   |
+| `<leader>1..9`        | Switch to session N  |
 | `?`                   | Show help            |
 | `Ctrl+C`              | Quit                 |
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@brimveyn/aimux",
-  "version": "1.3.1",
+  "version": "1.4.0",
   "description": "A terminal multiplexer for AI CLIs. Run Claude, Codex, OpenCode side-by-side with tabbed navigation, split panes, and persistent sessions.",
   "keywords": [
     "ai",
@@ -57,7 +57,7 @@
     "format:check": "oxfmt --check ."
   },
   "dependencies": {
-    "@brimveyn/aimux-config": "0.2.6",
+    "@brimveyn/aimux-config": "0.3.0",
     "@opentui/core": "^0.1.90",
     "@opentui/react": "^0.1.90",
     "@xterm/headless": "^6.0.0",

package/src/app-runtime/backend-runtime-events.ts

@@ -79,15 +79,21 @@ export function bindBackendRuntimeEvents({
     dispatch({ message, tabId, type: 'set-tab-error' })
   }
 
+  const handleSessionActivity = (sessionId: string, busy: boolean) => {
+    dispatch({ busy, sessionId, type: 'set-session-busy' })
+  }
+
   backend.on('render', handleRender)
   backend.on('exit', handleExit)
   backend.on('error', handleError)
+  backend.on('sessionActivity', handleSessionActivity)
 
   return () => {
     timeouts.clearAllTimers()
     backend.off('render', handleRender)
     backend.off('exit', handleExit)
     backend.off('error', handleError)
+    backend.off('sessionActivity', handleSessionActivity)
     void backend.destroy(true)
   }
 }

package/src/app-runtime/side-effects.ts

@@ -488,11 +488,29 @@ export function executeSideEffect(effect: SideEffect, ctx: SideEffectContext): v
       handleConfirmUpdateSelection(ctx)
       return
     }
+    case 'switch-session-by-index': {
+      handleSwitchSessionByIndex(ctx, effect.index)
+      return
+    }
     default:
       effect satisfies never
   }
 }
 
+function handleSwitchSessionByIndex(ctx: SideEffectContext, index: number): void {
+  const { backend, dispatch, state } = ctx
+  const ordered = state.sessions
+    .slice()
+    .sort((a, b) => (a.order ?? Number.MAX_SAFE_INTEGER) - (b.order ?? Number.MAX_SAFE_INTEGER))
+  const target = ordered[index - 1]
+  if (!target) {
+    logInputDebug('app.sessionBar.switchOutOfRange', { index, total: ordered.length })
+    return
+  }
+  if (target.id === state.currentSessionId) return
+  handleSwitchSessionEffect(state, backend, dispatch, target)
+}
+
 function handleConfirmUpdateSelection(ctx: SideEffectContext): void {
   const { state } = ctx
   if (state.modal.type !== 'update-available') {

package/src/app.tsx

@@ -31,7 +31,7 @@ import { getHandler, transitionTo } from './input/modes/registry'
 import { type TerminalContentOrigin } from './input/raw-input-handler'
 import { getProfileName } from './profile-paths'
 import { appStore } from './state/app-store'
-import { setActiveDispatch } from './state/dispatch-ref'
+import { setActiveDispatch, setActiveSideEffectRunner } from './state/dispatch-ref'
 import { loadSessionCatalog } from './state/session-catalog'
 import { loadSnippetCatalog } from './state/snippet-catalog'
 import { appReducer, createInitialState } from './state/store'
@@ -69,11 +69,22 @@ export function App({
     return config.themeId ?? 'aimux'
   })
   const [state, dispatch] = useReducer(appReducer, undefined, () => {
-    const { customCommands, gitPanelRatio, gitPanelVisible } = loadConfig()
-    return createInitialState(customCommands, loadSessionCatalog(), loadSnippetCatalog(), true, {
-      gitPanelRatio,
-      gitPanelVisible,
-    })
+    const json = loadConfig()
+    const sessionBarVisible = resolvedConfig.sessionBar?.visible ?? json.sessionBarVisible ?? true
+    const sessionBarPosition =
+      resolvedConfig.sessionBar?.position ?? json.sessionBarPosition ?? 'top'
+    return createInitialState(
+      json.customCommands,
+      loadSessionCatalog(),
+      loadSnippetCatalog(),
+      true,
+      {
+        gitPanelRatio: json.gitPanelRatio,
+        gitPanelVisible: json.gitPanelVisible,
+        sessionBarPosition,
+        sessionBarVisible,
+      }
+    )
   })
 
   useLayoutEffect(() => {
@@ -82,7 +93,10 @@ export function App({
 
   useLayoutEffect(() => {
     setActiveDispatch(dispatch)
-    return () => setActiveDispatch(null)
+    return () => {
+      setActiveDispatch(null)
+      setActiveSideEffectRunner(null)
+    }
   }, [dispatch])
 
   useEffect(() => {
@@ -251,6 +265,9 @@ export function App({
 
   // Keep the ref pointing at the latest closure so stable callbacks can invoke it
   processKeyResultRef.current = processKeyResult
+  // Expose the side-effect runner so non-keyboard call sites (mouse, IPC) can
+  // invoke the same effect pipeline with the current context.
+  setActiveSideEffectRunner((effect) => executeSideEffect(effect, sideEffectCtx))
 
   useLayoutEffect(() => {
     for (const handler of keymapHandlers) {

package/src/config.ts

@@ -1,6 +1,6 @@
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs'
 
-import type { WorkspaceSnapshotV1 } from './state/types'
+import type { SessionBarPosition, WorkspaceSnapshotV1 } from './state/types'
 
 import { logDebug } from './debug/input-log'
 import { getProfileConfigDir } from './profile-paths'
@@ -15,6 +15,8 @@ export interface AimuxConfig {
   themeId?: ThemeId
   gitPanelVisible?: boolean
   gitPanelRatio?: number
+  sessionBarVisible?: boolean
+  sessionBarPosition?: SessionBarPosition
   workspaceSnapshot?: WorkspaceSnapshotV1
   skippedUpdateVersion?: string
 }
@@ -58,6 +60,8 @@ export function loadConfigResult(): ConfigLoadResult {
       themeId?: unknown
       gitPanelVisible?: unknown
       gitPanelRatio?: unknown
+      sessionBarVisible?: unknown
+      sessionBarPosition?: unknown
       workspaceSnapshot?: unknown
       skippedUpdateVersion?: unknown
     }
@@ -93,6 +97,20 @@ export function loadConfigResult(): ConfigLoadResult {
       issues.push('ignored invalid gitPanelRatio')
     }
 
+    const validSessionBarVisible =
+      typeof parsed.sessionBarVisible === 'boolean' ? parsed.sessionBarVisible : undefined
+    if (parsed.sessionBarVisible !== undefined && validSessionBarVisible === undefined) {
+      issues.push('ignored invalid sessionBarVisible')
+    }
+
+    const validSessionBarPosition =
+      parsed.sessionBarPosition === 'top' || parsed.sessionBarPosition === 'bottom'
+        ? parsed.sessionBarPosition
+        : undefined
+    if (parsed.sessionBarPosition !== undefined && validSessionBarPosition === undefined) {
+      issues.push('ignored invalid sessionBarPosition')
+    }
+
     if (
       parsed.workspaceSnapshot !== undefined &&
       !isWorkspaceSnapshotV1(parsed.workspaceSnapshot)
@@ -117,6 +135,8 @@ export function loadConfigResult(): ConfigLoadResult {
         customCommands: isCustomCommandsRecord(parsed.customCommands) ? parsed.customCommands : {},
         gitPanelRatio: validGitPanelRatio,
         gitPanelVisible: validGitPanelVisible,
+        sessionBarPosition: validSessionBarPosition,
+        sessionBarVisible: validSessionBarVisible,
         skippedUpdateVersion: validSkippedUpdateVersion,
         themeId: isThemeId(parsed.themeId) ? parsed.themeId : undefined,
         version: 2,

package/src/input/modes/types.ts

@@ -53,6 +53,7 @@ export type SideEffect =
   | { type: 'git-commit'; title: string; body: string }
   | { type: 'git-push' }
   | { type: 'confirm-update-selection' }
+  | { type: 'switch-session-by-index'; index: number }
 
 export interface KeyResult {
   actions: AppAction[]

package/src/session-backend/local-session-backend.ts

@@ -12,12 +12,16 @@ import {
   toTerminalContentSize,
 } from '../state/layout-resize'
 
+const SESSION_IDLE_TIMEOUT_MS = 2_000
+
 export class LocalSessionBackend
   extends EventEmitter<SessionBackendEvents>
   implements SessionBackend
 {
   private readonly sessionManager = new SessionManager()
   private currentSessionId: string | null = null
+  private readonly sessionIdleTimers = new Map<string, ReturnType<typeof setTimeout>>()
+  private readonly sessionBusy = new Map<string, boolean>()
 
   constructor() {
     super()
@@ -25,6 +29,7 @@ export class LocalSessionBackend
       if (sessionId === this.currentSessionId) {
         this.emit('render', tabId, viewport, terminalModes)
       }
+      this.markSessionBusy(sessionId)
     })
     this.sessionManager.on('exit', (sessionId, tabId, exitCode) => {
       if (sessionId === this.currentSessionId) {
@@ -38,6 +43,23 @@ export class LocalSessionBackend
     })
   }
 
+  private markSessionBusy(sessionId: string): void {
+    if (this.sessionBusy.get(sessionId) !== true) {
+      this.sessionBusy.set(sessionId, true)
+      this.emit('sessionActivity', sessionId, true)
+    }
+    const existing = this.sessionIdleTimers.get(sessionId)
+    if (existing) clearTimeout(existing)
+    const timer = setTimeout(() => {
+      this.sessionIdleTimers.delete(sessionId)
+      if (this.sessionBusy.get(sessionId) === true) {
+        this.sessionBusy.set(sessionId, false)
+        this.emit('sessionActivity', sessionId, false)
+      }
+    }, SESSION_IDLE_TIMEOUT_MS)
+    this.sessionIdleTimers.set(sessionId, timer)
+  }
+
   async attach(options: {
     sessionId: string
     cols: number
@@ -166,6 +188,11 @@ export class LocalSessionBackend
         this.sessionManager.disposeSession(this.currentSessionId)
       }
     }
+    for (const timer of this.sessionIdleTimers.values()) {
+      clearTimeout(timer)
+    }
+    this.sessionIdleTimers.clear()
+    this.sessionBusy.clear()
     this.currentSessionId = null
   }
 }

package/src/session-backend/types.ts

@@ -12,6 +12,7 @@ export type SessionBackendEvents = {
   render: [tabId: string, viewport: TerminalSnapshot, terminalModes: TerminalModeState]
   exit: [tabId: string, exitCode: number]
   error: [tabId: string, message: string]
+  sessionActivity: [sessionId: string, busy: boolean]
 }
 
 export interface BackendAttachResult {

package/src/state/dispatch-ref.ts

@@ -1,8 +1,11 @@
+import type { SideEffect } from '../input/modes/types'
 import type { AppAction } from './types'
 
 type DispatchFn = (action: AppAction) => void
+type SideEffectFn = (effect: SideEffect) => void
 
 let activeDispatch: DispatchFn | null = null
+let activeSideEffect: SideEffectFn | null = null
 
 export function setActiveDispatch(dispatch: DispatchFn | null): void {
   activeDispatch = dispatch
@@ -11,3 +14,11 @@ export function setActiveDispatch(dispatch: DispatchFn | null): void {
 export function dispatchGlobal(action: AppAction): void {
   activeDispatch?.(action)
 }
+
+export function setActiveSideEffectRunner(runner: SideEffectFn | null): void {
+  activeSideEffect = runner
+}
+
+export function runSideEffectGlobal(effect: SideEffect): void {
+  activeSideEffect?.(effect)
+}

package/src/state/reducers/session-state.ts

@@ -64,6 +64,8 @@ export function reduceSessionState(state: AppState, action: AppAction): AppState
       const filteredNew = filterSessions(newSessions, state.modal.editBuffer)
       const maxIndex = filteredNew.length
       const clampedIndex = Math.min(state.modal.selectedIndex, maxIndex)
+      const nextBusy = { ...state.sessionsBusy }
+      delete nextBusy[action.sessionId]
       return {
         ...state,
         activeTabId: action.sessionId === state.currentSessionId ? null : state.activeTabId,
@@ -77,9 +79,35 @@ export function reduceSessionState(state: AppState, action: AppAction): AppState
           type: 'session-picker',
         },
         sessions: newSessions,
+        sessionsBusy: nextBusy,
         tabs: action.sessionId === state.currentSessionId ? [] : state.tabs,
       }
     }
+    case 'reorder-sessions': {
+      const byId = new Map(state.sessions.map((s) => [s.id, s]))
+      const ordered: typeof state.sessions = []
+      let idx = 0
+      for (const id of action.orderedIds) {
+        const s = byId.get(id)
+        if (s) {
+          ordered.push({ ...s, order: idx })
+          byId.delete(id)
+        }
+        idx++
+      }
+      let nextOrder = ordered.length
+      for (const s of byId.values()) {
+        ordered.push({ ...s, order: nextOrder++ })
+      }
+      return { ...state, sessions: ordered }
+    }
+    case 'set-session-busy': {
+      if ((state.sessionsBusy[action.sessionId] ?? false) === action.busy) return state
+      return {
+        ...state,
+        sessionsBusy: { ...state.sessionsBusy, [action.sessionId]: action.busy },
+      }
+    }
     default:
       return null
   }

package/src/state/reducers/ui-state.ts

@@ -23,6 +23,14 @@ export function reduceUIState(state: AppState, action: AppAction): AppState | nu
         return state
       }
       return { ...state, pendingChords: action.chords }
+    case 'toggle-session-bar':
+      return {
+        ...state,
+        sessionBar: { ...state.sessionBar, visible: !state.sessionBar.visible },
+      }
+    case 'set-session-bar-position':
+      if (state.sessionBar.position === action.position) return state
+      return { ...state, sessionBar: { ...state.sessionBar, position: action.position } }
     default:
       return null
   }

package/src/state/session-catalog.ts

@@ -46,7 +46,7 @@ export function loadSessionCatalog(): SessionRecord[] {
   const { file, issue } = readCatalogFile()
   if (file) {
     logDebug('sessions.catalog.load', { sessionCount: file.sessions.length })
-    return file.sessions
+    return normalizeOrder(file.sessions)
   }
 
   if (issue) {
@@ -95,3 +95,24 @@ export function saveSessionCatalog(sessions: SessionRecord[]): void {
 export function getSessionCatalogPath(): string {
   return SESSIONS_PATH
 }
+
+/**
+ * Assign a stable `order` to every session. Records with an existing numeric
+ * `order` keep their slot (sorted ascending); the rest are appended by
+ * createdAt ascending so older sessions come first.
+ */
+function normalizeOrder(sessions: SessionRecord[]): SessionRecord[] {
+  const withOrder: SessionRecord[] = []
+  const withoutOrder: SessionRecord[] = []
+  for (const s of sessions) {
+    if (typeof s.order === 'number' && Number.isFinite(s.order)) {
+      withOrder.push(s)
+    } else {
+      withoutOrder.push(s)
+    }
+  }
+  withOrder.sort((a, b) => (a.order ?? 0) - (b.order ?? 0))
+  withoutOrder.sort((a, b) => a.createdAt.localeCompare(b.createdAt))
+  const merged = [...withOrder, ...withoutOrder]
+  return merged.map((s, i) => (s.order === i ? s : { ...s, order: i }))
+}

package/src/state/store.ts

@@ -1,4 +1,4 @@
-import type { AppAction, AppState, SessionRecord, SnippetRecord } from './types'
+import type { AppAction, AppState, SessionBarPosition, SessionRecord, SnippetRecord } from './types'
 
 import { emptyGitMode, reduceGitModeState } from './reducers/git-mode-state'
 import { emptyGitPanel, reduceGitPanelState } from './reducers/git-panel-state'
@@ -17,6 +17,8 @@ const DEFAULT_TERMINAL_ROWS = 24
 export interface InitialStateOverrides {
   gitPanelVisible?: boolean
   gitPanelRatio?: number
+  sessionBarVisible?: boolean
+  sessionBarPosition?: SessionBarPosition
 }
 
 export function createInitialState(
@@ -42,7 +44,12 @@ export function createInitialState(
       ? { editBuffer: null, selectedIndex: 0, sessionTargetId: null, type: 'session-picker' }
       : emptyModal(),
     pendingChords: null,
+    sessionBar: {
+      position: overrides.sessionBarPosition ?? 'top',
+      visible: overrides.sessionBarVisible ?? true,
+    },
     sessions,
+    sessionsBusy: {},
     sidebar: {
       gitPanelRatio: overrides.gitPanelRatio ?? 0.5,
       gitPanelVisible: overrides.gitPanelVisible ?? true,

package/src/state/types.ts

@@ -105,9 +105,17 @@ export interface SessionRecord {
   createdAt: string
   updatedAt: string
   lastOpenedAt: string
+  order?: number
   workspaceSnapshot?: WorkspaceSnapshotV1
 }
 
+export type SessionBarPosition = 'top' | 'bottom'
+
+export interface SessionBarState {
+  visible: boolean
+  position: SessionBarPosition
+}
+
 export interface TabSession {
   id: string
   assistant: AssistantId
@@ -287,6 +295,8 @@ export interface AppState {
   tabGroupMap: Record<string, string>
   sessions: SessionRecord[]
   currentSessionId: string | null
+  sessionsBusy: Record<string, boolean>
+  sessionBar: SessionBarState
   snippets: SnippetRecord[]
   focusMode: FocusMode
   sidebar: SidebarState
@@ -332,6 +342,8 @@ export type SessionAction =
   | { type: 'create-session-record'; session: SessionRecord }
   | { type: 'rename-session-record'; sessionId: string; name: string }
   | { type: 'delete-session-record'; sessionId: string }
+  | { type: 'reorder-sessions'; orderedIds: string[] }
+  | { type: 'set-session-busy'; sessionId: string; busy: boolean }
 
 // -- Tab actions --
 export type TabAction =
@@ -398,6 +410,8 @@ export type UIAction =
   | { type: 'toggle-git-panel' }
   | { type: 'resize-git-panel'; delta: number }
   | { type: 'set-pending-chords'; chords: string[] | null }
+  | { type: 'toggle-session-bar' }
+  | { type: 'set-session-bar-position'; position: SessionBarPosition }
 
 // -- Git panel actions --
 export interface GitRefreshPayload {

package/src/state/validation.ts

@@ -151,6 +151,8 @@ export function isSessionRecord(value: unknown): value is SessionRecord {
     isString(value.createdAt) &&
     isString(value.updatedAt) &&
     isString(value.lastOpenedAt) &&
+    (value.order === undefined ||
+      (typeof value.order === 'number' && Number.isFinite(value.order))) &&
     (value.workspaceSnapshot === undefined || isWorkspaceSnapshotV1(value.workspaceSnapshot))
   )
 }

package/src/state/workspace-save.ts

@@ -26,6 +26,8 @@ export function saveCurrentWorkspace(state: AppState): void {
     customCommands: state.customCommands,
     gitPanelRatio: state.sidebar.gitPanelRatio,
     gitPanelVisible: state.sidebar.gitPanelVisible,
+    sessionBarPosition: state.sessionBar.position,
+    sessionBarVisible: state.sessionBar.visible,
   })
   saveSessionCatalog(
     buildSessionsWithCurrentSnapshot(state.sessions, state.currentSessionId, state)

package/src/ui/components/session-bar.tsx

@@ -0,0 +1,208 @@
+import type { BoxRenderable, MouseEvent as OtuiMouseEvent } from '@opentui/core'
+
+import { useMemo, useRef, useState } from 'react'
+
+import type { SessionRecord } from '../../state/types'
+
+import { useAppStore } from '../../state/app-store'
+import { dispatchGlobal, runSideEffectGlobal } from '../../state/dispatch-ref'
+import { useBusySpinner } from '../hooks/use-busy-spinner'
+import { moveIdToIdPosition, orderSessionsForDisplay } from '../session-ordering'
+import { theme } from '../theme'
+
+export function SessionBar() {
+  const sessions = useAppStore((s) => s.sessions)
+  const currentId = useAppStore((s) => s.currentSessionId)
+  const bar = useAppStore((s) => s.sessionBar)
+  const busyMap = useAppStore((s) => s.sessionsBusy)
+
+  const [draggingId, setDraggingId] = useState<string | null>(null)
+  const [dragOrder, setDragOrder] = useState<string[] | null>(null)
+  // Hysteresis: the id of the chip we most recently swapped with. While the
+  // cursor remains over that chip we refuse to swap back (prevents oscillation
+  // when a long chip's new bounds still cover the cursor after a swap).
+  const lastSwapWithRef = useRef<string | null>(null)
+  // Live bounds of each chip after render, keyed by session id.
+  const chipRefs = useRef(new Map<string, BoxRenderable>())
+
+  const ordered = useMemo(() => orderSessionsForDisplay(sessions), [sessions])
+  if (!bar.visible || ordered.length === 0) return null
+
+  const visibleSessions =
+    dragOrder !== null
+      ? dragOrder
+          .map((id) => ordered.find((s) => s.id === id))
+          .filter((s): s is SessionRecord => !!s)
+      : ordered
+
+  const baselineOrder = ordered.map((s) => s.id)
+
+  function setChipRef(id: string, ref: BoxRenderable | null): void {
+    if (ref) chipRefs.current.set(id, ref)
+    else chipRefs.current.delete(id)
+  }
+
+  function findChipAtX(x: number): string | null {
+    for (const [id, ref] of chipRefs.current) {
+      if (x >= ref.x && x < ref.x + ref.width) return id
+    }
+    return null
+  }
+
+  const handleMouseDown = (id: string) => {
+    setDraggingId(id)
+    setDragOrder(baselineOrder)
+    lastSwapWithRef.current = null
+  }
+
+  const handleMouseDrag = (event: OtuiMouseEvent) => {
+    if (!draggingId) return
+    const hit = findChipAtX(event.x)
+    if (hit === null) {
+      // Cursor left the bar entirely — allow the next hit to re-trigger a swap.
+      lastSwapWithRef.current = null
+      return
+    }
+    if (hit === draggingId) {
+      // Over the dragged chip itself — reset hysteresis so re-entering a
+      // neighbour can swap again.
+      lastSwapWithRef.current = null
+      return
+    }
+    if (hit === lastSwapWithRef.current) return
+    setDragOrder((prev) => (prev ? moveIdToIdPosition(prev, draggingId, hit) : prev))
+    lastSwapWithRef.current = hit
+  }
+
+  const commitDrop = () => {
+    const source = draggingId
+    const finalOrder = dragOrder
+    setDraggingId(null)
+    setDragOrder(null)
+    lastSwapWithRef.current = null
+
+    if (!source || !finalOrder) return
+
+    const changed = !arraysEqual(finalOrder, baselineOrder)
+    if (changed) {
+      dispatchGlobal({ orderedIds: finalOrder, type: 'reorder-sessions' })
+      return
+    }
+
+    // Drag did not change anything → treat as click, switch to that session.
+    const idx = baselineOrder.indexOf(source)
+    if (idx >= 0) {
+      runSideEffectGlobal({ index: idx + 1, type: 'switch-session-by-index' })
+    }
+  }
+
+  const cancelDrag = () => {
+    setDraggingId(null)
+    setDragOrder(null)
+    lastSwapWithRef.current = null
+  }
+
+  return (
+    <box
+      width="100%"
+      flexDirection="row"
+      paddingLeft={1}
+      paddingRight={1}
+      backgroundColor={theme.panelMuted}
+    >
+      {visibleSessions.map((session) => {
+        const displayIndex = baselineOrder.indexOf(session.id) + 1
+        return (
+          <SessionChip
+            key={session.id}
+            session={session}
+            index={displayIndex}
+            active={session.id === currentId}
+            busy={busyMap[session.id] ?? false}
+            dragging={draggingId === session.id}
+            onRef={(r) => setChipRef(session.id, r)}
+            onMouseDown={() => handleMouseDown(session.id)}
+            onMouseDrag={handleMouseDrag}
+            onMouseUp={commitDrop}
+            onMouseDragEnd={cancelDrag}
+          />
+        )
+      })}
+    </box>
+  )
+}
+
+function arraysEqual(a: string[], b: string[]): boolean {
+  if (a.length !== b.length) return false
+  for (let i = 0; i < a.length; i++) {
+    if (a[i] !== b[i]) return false
+  }
+  return true
+}
+
+interface SessionChipProps {
+  session: SessionRecord
+  index: number
+  active: boolean
+  busy: boolean
+  dragging: boolean
+  onRef: (ref: BoxRenderable | null) => void
+  onMouseDown: (event: OtuiMouseEvent) => void
+  onMouseDrag: (event: OtuiMouseEvent) => void
+  onMouseUp: (event: OtuiMouseEvent) => void
+  onMouseDragEnd: (event: OtuiMouseEvent) => void
+}
+
+function SessionChip({
+  active,
+  busy,
+  dragging,
+  index,
+  onMouseDown,
+  onMouseDrag,
+  onMouseDragEnd,
+  onMouseUp,
+  onRef,
+  session,
+}: SessionChipProps) {
+  const showSpinner = busy && !active
+  const spinner = useBusySpinner(showSpinner)
+  const indicator = showSpinner ? spinner : '●'
+  const indicatorColor = active || showSpinner ? theme.accent : theme.success
+  const labelColor = active ? theme.text : theme.textMuted
+  const bgColor = dragging || active ? theme.panelHighlight : undefined
+
+  return (
+    <box
+      ref={onRef}
+      flexDirection="row"
+      paddingLeft={1}
+      paddingRight={1}
+      backgroundColor={bgColor}
+      onMouseDown={(e) => {
+        e.preventDefault()
+        onMouseDown(e)
+      }}
+      onMouseDrag={(e) => {
+        onMouseDrag(e)
+      }}
+      onMouseUp={(e) => {
+        e.preventDefault()
+        onMouseUp(e)
+      }}
+      onMouseDragEnd={(e) => {
+        onMouseDragEnd(e)
+      }}
+    >
+      <text fg={indicatorColor} selectable={false}>
+        {indicator}{' '}
+      </text>
+      <text fg={labelColor} selectable={false}>
+        [{index}] {session.name}
+      </text>
+      <text fg={theme.dim} selectable={false}>
+        {' '}
+      </text>
+    </box>
+  )
+}

package/src/ui/components/tab-item.tsx

@@ -1,7 +1,6 @@
-import { useEffect, useState } from 'react'
-
 import type { TabSession } from '../../state/types'
 
+import { useBusySpinner } from '../hooks/use-busy-spinner'
 import { theme } from '../theme'
 
 interface TabItemProps {
@@ -28,9 +27,6 @@ function getStatusColor(status: TabSession['status']): string {
   }
 }
 
-const BUSY_FRAMES = ['⠋', '⠙', '⠹', '⠸', '⠼', '⠴', '⠦', '⠧', '⠇', '⠏']
-const BUSY_FRAME_INTERVAL_MS = 80
-
 function getIndicator(active: boolean, focused: boolean, inLayout: boolean): string {
   if (active) {
     return focused ? '›' : '•'
@@ -48,16 +44,8 @@ function getIndicatorColor(active: boolean, focused: boolean, inLayout: boolean)
 }
 
 function BusyIndicator() {
-  const [frame, setFrame] = useState(0)
-
-  useEffect(() => {
-    const interval = setInterval(() => {
-      setFrame((prev) => (prev + 1) % BUSY_FRAMES.length)
-    }, BUSY_FRAME_INTERVAL_MS)
-    return () => clearInterval(interval)
-  }, [])
-
-  return <text fg={theme.accent}>{BUSY_FRAMES[frame]} busy</text>
+  const frame = useBusySpinner()
+  return <text fg={theme.accent}>{frame} busy</text>
 }
 
 function ActivityIndicator({ isFocusedInput, tab }: { tab: TabSession; isFocusedInput: boolean }) {

package/src/ui/hooks/use-busy-spinner.ts

@@ -0,0 +1,18 @@
+import { useEffect, useState } from 'react'
+
+export const BUSY_FRAMES = ['⠋', '⠙', '⠹', '⠸', '⠼', '⠴', '⠦', '⠧', '⠇', '⠏']
+export const BUSY_FRAME_INTERVAL_MS = 80
+
+export function useBusySpinner(enabled = true): string {
+  const [frame, setFrame] = useState(0)
+
+  useEffect(() => {
+    if (!enabled) return
+    const interval = setInterval(() => {
+      setFrame((prev) => (prev + 1) % BUSY_FRAMES.length)
+    }, BUSY_FRAME_INTERVAL_MS)
+    return () => clearInterval(interval)
+  }, [enabled])
+
+  return BUSY_FRAMES[frame] ?? BUSY_FRAMES[0] ?? ''
+}

package/src/ui/root.tsx

@@ -12,6 +12,7 @@ import { GitView } from './components/git-view'
 import { HelpModal } from './components/help-modal'
 import { NewTabModal } from './components/new-tab-modal'
 import { PendingChordOverlay } from './components/pending-chord-overlay'
+import { SessionBar } from './components/session-bar'
 import { SessionNameModal } from './components/session-name-modal'
 import { SessionPickerModal } from './components/session-picker-modal'
 import { Sidebar } from './components/sidebar'
@@ -213,6 +214,7 @@ export function RootView({
   const customCommands = useAppStore((s) => s.customCommands)
   const sessions = useAppStore((s) => s.sessions)
   const currentSessionId = useAppStore((s) => s.currentSessionId)
+  const sessionBarPosition = useAppStore((s) => s.sessionBar.position)
 
   const activeTab = tabs.find((tab) => tab.id === activeTabId)
   const activeTree = activeTabId ? getTreeForTab(layoutTrees, tabGroupMap, activeTabId) : null
@@ -243,6 +245,7 @@ export function RootView({
 
   return (
     <box flexDirection="column" width="100%" height="100%" backgroundColor={theme.background}>
+      {sessionBarPosition === 'top' && <SessionBar />}
       <box flexDirection="row" gap={0} padding={0} flexGrow={1}>
         <Sidebar onTabActivate={onPaneActivate} />
         {activeTree && activeTree.type === 'split' ? (
@@ -290,6 +293,7 @@ export function RootView({
           />
         )}
       </box>
+      {sessionBarPosition === 'bottom' && <SessionBar />}
       <StatusBar />
       <PendingChordOverlay />
       {renderModal(modal, {

package/src/ui/session-ordering.ts

@@ -0,0 +1,34 @@
+import type { SessionRecord } from '../state/types'
+
+/**
+ * Return sessions in user-facing display order: persisted `order` ascending,
+ * with any missing `order` falling back to `createdAt` ascending.
+ */
+export function orderSessionsForDisplay(sessions: SessionRecord[]): SessionRecord[] {
+  return sessions.slice().sort((a, b) => {
+    const ao = a.order ?? Number.MAX_SAFE_INTEGER
+    const bo = b.order ?? Number.MAX_SAFE_INTEGER
+    if (ao !== bo) return ao - bo
+    return a.createdAt.localeCompare(b.createdAt)
+  })
+}
+
+/**
+ * Move `moveId` to the slot currently held by `intoPositionOfId`, shifting the
+ * displaced id in the opposite direction. Pure; returns a new array. Returns
+ * the input unchanged if either id is missing or both refer to the same slot.
+ */
+export function moveIdToIdPosition(
+  ids: string[],
+  moveId: string,
+  intoPositionOfId: string
+): string[] {
+  if (moveId === intoPositionOfId) return ids
+  const from = ids.indexOf(moveId)
+  const to = ids.indexOf(intoPositionOfId)
+  if (from < 0 || to < 0) return ids
+  const next = ids.slice()
+  next.splice(from, 1)
+  next.splice(to, 0, moveId)
+  return next
+}