@brimveyn/aimux 1.14.13 → 1.14.15

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@brimveyn/aimux",
-  "version": "1.14.13",
+  "version": "1.14.15",
   "description": "A terminal multiplexer for AI CLIs. Run Claude, Codex, OpenCode side-by-side with tabbed navigation, split panes, and persistent sessions.",
   "keywords": [
     "ai",
@@ -60,7 +60,7 @@
     "bump": "bun run scripts/bump.ts"
   },
   "dependencies": {
-    "@brimveyn/aimux-config": "0.6.8",
+    "@brimveyn/aimux-config": "0.6.9",
     "@opentui/core": "^0.1.90",
     "@opentui/react": "^0.1.90",
     "@resvg/resvg-wasm": "^2.6.2",

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

@@ -16,7 +16,7 @@ import type { SessionBackend } from '../session-backend/types'
 import type { AppAction, AppState, AssistantId, TabSession, WorktreeRecord } from '../state/types'
 import type { ThemeId } from '../ui/themes'
 
-import { loadConfig, saveConfig } from '../config'
+import { loadConfig, saveConfig, type WorktreeTemplate, type WorktreeTemplatePane } from '../config'
 import { logInputDebug } from '../debug/input-log'
 import { enqueueGitOp } from '../git/command-queue'
 import { moveWorktree } from '../git/move-worktree'
@@ -54,7 +54,12 @@ import {
   type SplitDirection,
   splitNode,
 } from '../state/layout-tree'
-import { filterAssistants, filterSessions, filterSnippets } from '../state/selectors'
+import {
+  filterAssistants,
+  filterSessions,
+  filterSnippets,
+  getTemplateNoneOffset,
+} from '../state/selectors'
 import { saveSessionCatalog } from '../state/session-catalog'
 import { pruneSnapshotOfWorktree } from '../state/session-persistence'
 import {
@@ -73,6 +78,7 @@ import { filterThemeIds } from '../ui/filter-themes'
 import { scrollGitDiff } from '../ui/git-view-controls'
 import { applyTheme, getCurrentMode, getTransparent, setMode, setTransparent } from '../ui/theme'
 import { triggerAutoCommitNow } from './auto-commit-ref'
+import { writeToTab } from './pty-write'
 import {
   handleCreateSessionEffect,
   handleDeleteSessionEffect,
@@ -88,6 +94,15 @@ import {
 } from './snippet-actions'
 
 const STARTUP_GRACE_MS = 5_000
+/**
+ * Delay before injecting a template pane's `send` payload into its PTY.
+ * Short enough that shells (which print a prompt within ~100 ms) receive the
+ * command after their prompt is drawn; long enough to clear most PTY init
+ * races. Not tied to STARTUP_GRACE_MS because that is the assistant timeout,
+ * not a readiness signal. See review note: a `tab.status === 'running'`
+ * subscription would be more robust and is the planned follow-up.
+ */
+const TEMPLATE_SEND_DELAY_MS = 600
 
 export interface SideEffectContext {
   state: AppState
@@ -403,7 +418,8 @@ async function launchAssistantInNewWorktree(
   assistant: AssistantId,
   worktreeName: string,
   branchName?: string,
-  sourceWorktreeId?: string
+  sourceWorktreeId?: string,
+  templateId?: string
 ): Promise<void> {
   const sessionId = ctx.state.currentSessionId
   if (!(sessionId != null && sessionId !== '')) return
@@ -416,10 +432,23 @@ async function launchAssistantInNewWorktree(
     sourceWorktreeId
   )
   if (!worktree) return
+
+  const template =
+    templateId != null && templateId !== ''
+      ? ctx.state.worktreeTemplates.find((entry) => entry.id === templateId)
+      : undefined
+
+  ctx.dispatch({ type: 'close-modal' })
+
+  if (template) {
+    applyWorktreeTemplate(ctx, template, worktree.id, worktree.path)
+    ctx.dispatch({ focusMode: 'terminal-input', type: 'set-focus-mode' })
+    return
+  }
+
   const customCommand = ctx.state.customCommands[assistant]
   const tab = createTabSession(assistant, customCommand, ctx.state.customCommands, worktree.id)
   ctx.dispatch({ tab, type: 'add-tab' })
-  ctx.dispatch({ type: 'close-modal' })
   ctx.dispatch({ focusMode: 'terminal-input', type: 'set-focus-mode' })
   startTabSession(
     ctx.backend,
@@ -433,6 +462,126 @@ async function launchAssistantInNewWorktree(
   )
 }
 
+function applyWorktreeTemplate(
+  ctx: SideEffectContext,
+  template: WorktreeTemplate,
+  worktreeId: string,
+  worktreePath: string
+): void {
+  let firstTabId: string | null = null
+
+  for (const templateTab of template.tabs) {
+    const localToTabId = new Map<string, string>()
+
+    for (let i = 0; i < templateTab.panes.length; i++) {
+      const pane = templateTab.panes[i]
+      if (!pane) continue
+      const tab = createPaneTab(ctx, pane, worktreeId)
+      localToTabId.set(pane.id, tab.id)
+
+      if (i === 0) {
+        if (firstTabId == null) firstTabId = tab.id
+        ctx.dispatch({ tab, type: 'add-tab' })
+        startTabSession(
+          ctx.backend,
+          ctx.dispatch,
+          ctx.clearStartupGrace,
+          (tabId) => ctx.startStartupGrace(tabId, STARTUP_GRACE_MS),
+          tab,
+          ctx.state.layout.terminalCols,
+          ctx.state.layout.terminalRows,
+          worktreePath
+        )
+      } else {
+        const splitFromId =
+          pane.splitFrom != null && pane.splitFrom !== ''
+            ? localToTabId.get(pane.splitFrom)
+            : undefined
+        const direction: SplitDirection = pane.direction ?? 'vertical'
+        if (splitFromId == null || splitFromId === '') {
+          logInputDebug('template.splitFrom.unresolved', {
+            paneId: pane.id,
+            splitFrom: pane.splitFrom ?? null,
+            templateId: template.id,
+          })
+          continue
+        }
+        splitFromTab(ctx, splitFromId, direction, tab, worktreePath)
+        if (pane.ratio != null) {
+          const sourceRatio = clampSplitRatio(1 - pane.ratio)
+          ctx.dispatch({
+            axis: direction,
+            ratio: sourceRatio,
+            tabId: tab.id,
+            type: 'set-split-ratio',
+          })
+        }
+      }
+
+      if (pane.send != null && pane.send !== '') {
+        const payload = `${pane.send}\n`
+        const targetTabId = tab.id
+        setTimeout(() => {
+          const latest = ctx.getState()
+          const latestTab = latest.tabs.find((entry) => entry.id === targetTabId)
+          writeToTab(ctx.backend, targetTabId, latestTab, payload)
+        }, TEMPLATE_SEND_DELAY_MS)
+      }
+    }
+  }
+
+  if (firstTabId != null) {
+    ctx.dispatch({ tabId: firstTabId, type: 'set-active-tab' })
+  }
+}
+
+function createPaneTab(
+  ctx: SideEffectContext,
+  pane: WorktreeTemplatePane,
+  worktreeId: string
+): TabSession {
+  // Accept `'shell'` as an alias for the registered `'terminal'` assistant so
+  // template examples using the more intuitive name don't silently fall back
+  // to Claude (createTabSession's unknown-id fallback resolves to index 0).
+  const assistantId = (pane.assistant === 'shell' ? 'terminal' : pane.assistant) as AssistantId
+  const customCommand = ctx.state.customCommands[assistantId]
+  return createTabSession(assistantId, customCommand, ctx.state.customCommands, worktreeId)
+}
+
+function splitFromTab(
+  ctx: SideEffectContext,
+  baseTabId: string,
+  direction: SplitDirection,
+  newTab: TabSession,
+  cwd?: string
+): void {
+  ctx.dispatch({ tabId: baseTabId, type: 'set-active-tab' })
+
+  const latest = ctx.getState()
+  const existingTree = getTreeForTab(latest.layoutTrees, latest.tabGroupMap, baseTabId)
+  const baseTree = existingTree ?? createLeaf(baseTabId)
+  const newTree = splitNode(baseTree, baseTabId, direction, newTab.id)
+  const bounds = createTerminalBounds(latest.layout.terminalCols, latest.layout.terminalRows)
+  const paneRect = computePaneRects(newTree, bounds).get(newTab.id)
+
+  ctx.dispatch({ direction, newTab, type: 'split-pane' })
+  startTabSession(
+    ctx.backend,
+    ctx.dispatch,
+    ctx.clearStartupGrace,
+    (tabId) => ctx.startStartupGrace(tabId, STARTUP_GRACE_MS),
+    newTab,
+    Math.max(1, (paneRect?.cols ?? latest.layout.terminalCols) - PANE_BORDER * 2),
+    Math.max(1, (paneRect?.rows ?? latest.layout.terminalRows) - PANE_BORDER * 2),
+    cwd
+  )
+}
+
+function clampSplitRatio(value: number): number {
+  if (!Number.isFinite(value)) return 0.5
+  return Math.min(0.85, Math.max(0.15, value))
+}
+
 function getTabProjectPath(
   ctx: SideEffectContext,
   tab: Pick<TabSession, 'worktreeId'>
@@ -504,11 +653,27 @@ export function executeSideEffect(effect: SideEffect, ctx: SideEffectContext): v
       return
     }
     case 'launch-selected-assistant': {
+      if (
+        state.modal.type === 'new-tab' &&
+        state.modal.step === 'worktree-create' &&
+        state.worktreeTemplates.length > 0
+      ) {
+        dispatch({ type: 'enter-new-tab-template-pick' })
+        return
+      }
       const option = getSelectedAssistantOption(state)
       if (state.modal.type === 'new-tab' && state.modal.createWorktree) {
         const worktreeName = state.modal.worktreeName
         const branchName = state.modal.branchName
         const sourceWorktreeId = getNewTabTargetWorktreeId(state)
+        let templateId: string | undefined
+        if (state.modal.step === 'template') {
+          const templateIndex =
+            state.modal.selectedIndex - getTemplateNoneOffset(state.modal.selectedAssistantId)
+          if (templateIndex >= 0) {
+            templateId = state.worktreeTemplates[templateIndex]?.id
+          }
+        }
         void (async () => {
           try {
             await enqueueGitOp(async () =>
@@ -517,7 +682,8 @@ export function executeSideEffect(effect: SideEffect, ctx: SideEffectContext): v
                 option.id,
                 worktreeName,
                 branchName,
-                sourceWorktreeId
+                sourceWorktreeId,
+                templateId
               )
             )
           } catch (error) {

package/src/app.tsx

@@ -152,6 +152,10 @@ export function App({
         gitPane: gitPaneOverrides,
         sessionBarVisible,
         sidebar: sidebarOverrides,
+        worktreeTemplates:
+          resolvedConfig.worktreeTemplates.length > 0
+            ? resolvedConfig.worktreeTemplates
+            : json.worktreeTemplates,
       }
     )
     // Replace the module-level default with the fully-resolved initial state.

package/src/config.ts

@@ -1,5 +1,6 @@
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs'
 
+import type { SplitDirection } from './state/layout-tree'
 import type { GitFileListMode, WorkspaceSnapshotV1 } from './state/types'
 
 import { logDebug } from './debug/input-log'
@@ -32,6 +33,26 @@ export interface PersistedSidebar {
   width: number
 }
 
+export interface WorktreeTemplatePane {
+  id: string
+  assistant: string
+  splitFrom?: string
+  direction?: SplitDirection
+  ratio?: number
+  send?: string
+}
+
+export interface WorktreeTemplateTab {
+  panes: WorktreeTemplatePane[]
+}
+
+export interface WorktreeTemplate {
+  id: string
+  name: string
+  description?: string
+  tabs: WorktreeTemplateTab[]
+}
+
 export interface AimuxConfig {
   version: 2
   customCommands: Record<string, string>
@@ -43,6 +64,7 @@ export interface AimuxConfig {
   sessionBarVisible?: boolean
   workspaceSnapshot?: WorkspaceSnapshotV1
   skippedUpdateVersion?: string
+  worktreeTemplates?: WorktreeTemplate[]
 }
 
 function isPersistedGitPane(value: unknown): value is PersistedGitPane {
@@ -105,6 +127,77 @@ function isPersistedGitPane(value: unknown): value is PersistedGitPane {
   return true
 }
 
+function isRatioValid(value: unknown): boolean {
+  return typeof value === 'number' && Number.isFinite(value) && value > 0.15 && value < 0.85
+}
+
+function isWorktreeTemplateTab(value: unknown): value is WorktreeTemplateTab {
+  if (typeof value !== 'object' || value === null) return false
+  const v = value as Record<string, unknown>
+  if (!Array.isArray(v.panes) || v.panes.length === 0) return false
+  const seenIds = new Set<string>()
+  for (let i = 0; i < v.panes.length; i++) {
+    const rawPane = v.panes[i]
+    if (typeof rawPane !== 'object' || rawPane === null) return false
+    const pane = rawPane as Record<string, unknown>
+    if (typeof pane.id !== 'string' || pane.id.length === 0) return false
+    if (seenIds.has(pane.id)) return false
+    seenIds.add(pane.id)
+    if (typeof pane.assistant !== 'string' || pane.assistant.length === 0) return false
+    if (i === 0) {
+      if (pane.splitFrom !== undefined) return false
+      if (pane.direction !== undefined) return false
+      if (pane.ratio !== undefined) return false
+    } else {
+      if (typeof pane.splitFrom !== 'string' || !seenIds.has(pane.splitFrom)) return false
+      if (pane.splitFrom === pane.id) return false
+      if (pane.direction !== 'horizontal' && pane.direction !== 'vertical') return false
+      if (pane.ratio !== undefined && !isRatioValid(pane.ratio)) return false
+    }
+    if (pane.send !== undefined && typeof pane.send !== 'string') return false
+  }
+  return true
+}
+
+export function isWorktreeTemplate(value: unknown): value is WorktreeTemplate {
+  if (typeof value !== 'object' || value === null) return false
+  const v = value as Record<string, unknown>
+  if (typeof v.id !== 'string' || v.id.length === 0) return false
+  if (typeof v.name !== 'string' || v.name.length === 0) return false
+  if (v.description !== undefined && typeof v.description !== 'string') return false
+  if (!Array.isArray(v.tabs) || v.tabs.length === 0) return false
+  for (const tab of v.tabs) {
+    if (!isWorktreeTemplateTab(tab)) return false
+  }
+  return true
+}
+
+export function parseWorktreeTemplates(
+  value: unknown,
+  issues: string[]
+): WorktreeTemplate[] | undefined {
+  if (value === undefined) return undefined
+  if (!Array.isArray(value)) {
+    issues.push('ignored invalid worktreeTemplates (not an array)')
+    return undefined
+  }
+  const seen = new Set<string>()
+  const valid: WorktreeTemplate[] = []
+  for (const entry of value) {
+    if (!isWorktreeTemplate(entry)) {
+      issues.push('ignored invalid worktreeTemplate entry')
+      continue
+    }
+    if (seen.has(entry.id)) {
+      issues.push(`ignored duplicate worktreeTemplate id "${entry.id}"`)
+      continue
+    }
+    seen.add(entry.id)
+    valid.push(entry)
+  }
+  return valid.length > 0 ? valid : undefined
+}
+
 function isPersistedSidebar(value: unknown): value is PersistedSidebar {
   if (typeof value !== 'object' || value === null) return false
   const v = value as Record<string, unknown>
@@ -162,6 +255,7 @@ export function loadConfigResult(): ConfigLoadResult {
       sessionBarVisible?: unknown
       workspaceSnapshot?: unknown
       skippedUpdateVersion?: unknown
+      worktreeTemplates?: unknown
     }
 
     const issues: string[] = []
@@ -246,6 +340,8 @@ export function loadConfigResult(): ConfigLoadResult {
       issues.push('ignored invalid skippedUpdateVersion')
     }
 
+    const validWorktreeTemplates = parseWorktreeTemplates(parsed.worktreeTemplates, issues)
+
     if (issues.length > 0) {
       logDebug('config.load.validationIssue', { issues, path: CONFIG_PATH })
     }
@@ -264,6 +360,7 @@ export function loadConfigResult(): ConfigLoadResult {
         workspaceSnapshot: isWorkspaceSnapshotV1(parsed.workspaceSnapshot)
           ? parsed.workspaceSnapshot
           : undefined,
+        worktreeTemplates: validWorktreeTemplates,
       },
       issues,
       source: 'file',

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

@@ -6,7 +6,12 @@ import { collectHelpEntries } from '../../input/keymap/help-entries'
 import { getActiveKeymap } from '../../input/keymap/keymap-ref'
 import { getAllAssistantOptions } from '../../pty/command-registry'
 import { filterThemeIds } from '../../ui/filter-themes'
-import { filterAssistants, filterSessions, filterSnippets } from '../selectors'
+import {
+  filterAssistants,
+  filterSessions,
+  filterSnippets,
+  getTemplateNoneOffset,
+} from '../selectors'
 import { reduceAutoCommitState } from './auto-commit-state'
 
 function emptyModal() {
@@ -90,6 +95,36 @@ export function reduceModalState(state: AppState, action: AppAction): AppState |
         },
       }
     }
+    case 'enter-new-tab-template-pick': {
+      if (state.modal.type !== 'new-tab') return state
+      return {
+        ...state,
+        modal: {
+          ...state.modal,
+          activeField: 'target-worktree',
+          cursorPos: 0,
+          selectedIndex: 0,
+          step: 'template',
+        },
+      }
+    }
+    case 'enter-new-tab-template-shortcut': {
+      if (state.modal.type !== 'new-tab') return state
+      const defaultName = state.modal.worktreeName || 'wt-template'
+      return {
+        ...state,
+        modal: {
+          ...state.modal,
+          activeField: 'worktree-name',
+          createWorktree: true,
+          cursorPos: defaultName.length,
+          selectedAssistantId: null,
+          selectedIndex: 0,
+          step: 'worktree-create',
+          worktreeName: defaultName,
+        },
+      }
+    }
     case 'set-new-tab-worktree-delete-state': {
       if (state.modal.type !== 'new-tab') return state
       return {
@@ -115,6 +150,32 @@ export function reduceModalState(state: AppState, action: AppAction): AppState |
     }
     case 'select-new-tab-assistant': {
       if (state.modal.type !== 'new-tab' || state.modal.editingCommand !== null) return state
+      if (
+        action.assistantId === undefined &&
+        state.modal.step === 'assistant' &&
+        state.worktreeTemplates.length > 0
+      ) {
+        const filtered = filterAssistants(
+          getAllAssistantOptions(state.customCommands),
+          state.modal.editBuffer
+        )
+        if (state.modal.selectedIndex >= filtered.length) {
+          const defaultName = state.modal.worktreeName || 'wt-template'
+          return {
+            ...state,
+            modal: {
+              ...state.modal,
+              activeField: 'worktree-name',
+              createWorktree: true,
+              cursorPos: defaultName.length,
+              selectedAssistantId: null,
+              selectedIndex: 0,
+              step: 'worktree-create',
+              worktreeName: defaultName,
+            },
+          }
+        }
+      }
       const option = getSelectedNewTabAssistant(state, action.assistantId)
       if (!option) return state
       const targetWorktreeIndex = getCurrentWorktreeIndex(state)
@@ -562,11 +623,13 @@ export function reduceModalState(state: AppState, action: AppAction): AppState |
         if (state.modal.step === 'worktree') {
           if (state.modal.activeField === 'worktree-name') return state
           optionCount = getCurrentWorktreeCount(state) + 1
+        } else if (state.modal.step === 'template') {
+          optionCount =
+            state.worktreeTemplates.length + getTemplateNoneOffset(state.modal.selectedAssistantId)
         } else {
-          optionCount = filterAssistants(
-            getAllAssistantOptions(state.customCommands),
-            state.modal.editBuffer
-          ).length
+          optionCount =
+            filterAssistants(getAllAssistantOptions(state.customCommands), state.modal.editBuffer)
+              .length + (state.worktreeTemplates.length > 0 ? 1 : 0)
         }
       } else if (state.modal.type === 'split-picker') {
         optionCount = getAllAssistantOptions(state.customCommands).length
@@ -626,11 +689,16 @@ export function reduceModalState(state: AppState, action: AppAction): AppState |
       if (state.modal.type === 'help') {
         optionCount = state.modal.entryCount
       } else if (state.modal.type === 'new-tab') {
-        optionCount =
-          state.modal.step === 'worktree'
-            ? getCurrentWorktreeCount(state) + 1
-            : filterAssistants(getAllAssistantOptions(state.customCommands), state.modal.editBuffer)
-                .length
+        if (state.modal.step === 'worktree') {
+          optionCount = getCurrentWorktreeCount(state) + 1
+        } else if (state.modal.step === 'template') {
+          optionCount =
+            state.worktreeTemplates.length + getTemplateNoneOffset(state.modal.selectedAssistantId)
+        } else {
+          optionCount =
+            filterAssistants(getAllAssistantOptions(state.customCommands), state.modal.editBuffer)
+              .length + (state.worktreeTemplates.length > 0 ? 1 : 0)
+        }
       } else if (state.modal.type === 'split-picker') {
         optionCount = getAllAssistantOptions(state.customCommands).length
       } else if (state.modal.type === 'create-session') {
@@ -677,8 +745,8 @@ export function reduceModalState(state: AppState, action: AppAction): AppState |
       if (
         state.modal.type === 'new-tab' &&
         state.modal.editingCommand === null &&
-        state.modal.step === 'worktree' &&
-        state.modal.activeField === 'target-worktree'
+        (state.modal.step === 'template' ||
+          (state.modal.step === 'worktree' && state.modal.activeField === 'target-worktree'))
       ) {
         return state
       }
@@ -707,8 +775,8 @@ export function reduceModalState(state: AppState, action: AppAction): AppState |
       if (
         state.modal.type === 'new-tab' &&
         state.modal.editingCommand === null &&
-        state.modal.step === 'worktree' &&
-        state.modal.activeField === 'target-worktree'
+        (state.modal.step === 'template' ||
+          (state.modal.step === 'worktree' && state.modal.activeField === 'target-worktree'))
       ) {
         return state
       }
@@ -785,6 +853,18 @@ export function reduceModalState(state: AppState, action: AppAction): AppState |
         }
       }
       if (state.modal.type === 'new-tab') {
+        if (state.modal.step === 'template') {
+          return {
+            ...state,
+            modal: {
+              ...state.modal,
+              activeField: 'worktree-name',
+              cursorPos: state.modal.worktreeName.length,
+              selectedIndex: 0,
+              step: 'worktree-create',
+            },
+          }
+        }
         if (state.modal.step === 'worktree-create') {
           const optionCount = getCurrentWorktreeCount(state) + 1
           return {

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

@@ -28,12 +28,24 @@ export function reduceSessionState(state: AppState, action: AppAction): AppState
       // honor the patched worktree by filtering the restored tab list.
       const loadedSession = state.sessions.find((entry) => entry.id === action.sessionId)
       const visible = filterTabsForActiveWorktree(restored.tabs, loadedSession)
-      const activeTabId =
+      // Prefer the snapshot's tab; if it isn't visible under the active
+      // worktree (e.g. a multi-worktree session restored onto a different
+      // worktree), fall back to the last tab we viewed in that worktree,
+      // then to the first visible tab.
+      const rememberedForWorktree =
+        loadedSession?.activeWorktreeId != null && loadedSession.activeWorktreeId !== ''
+          ? state.lastActiveTabByWorktree[loadedSession.activeWorktreeId]
+          : undefined
+      const snapshotTabVisible =
         restored.activeTabId != null &&
         restored.activeTabId !== '' &&
         visible.some((t) => t.id === restored.activeTabId)
-          ? restored.activeTabId
-          : (visible[0]?.id ?? null)
+      const rememberedTabVisible =
+        rememberedForWorktree != null &&
+        rememberedForWorktree !== '' &&
+        visible.some((t) => t.id === rememberedForWorktree)
+      const fallbackTabId = rememberedTabVisible ? rememberedForWorktree : (visible[0]?.id ?? null)
+      const activeTabId = snapshotTabVisible ? restored.activeTabId : fallbackTabId
       return {
         ...state,
         ...restored,
@@ -196,15 +208,29 @@ export function reduceSessionState(state: AppState, action: AppAction): AppState
       const sessions = state.sessions.map((session) =>
         session.id === action.sessionId ? withActiveWorktree(session, action.worktreeId) : session
       )
+      // Remember the tab we're leaving so coming back to this worktree later
+      // restores it instead of snapping to the first tab. Keyed by the
+      // worktree we're departing (the current session's active one).
+      const leavingSession = state.sessions.find((s) => s.id === action.sessionId)
+      const leavingWorktreeId = leavingSession?.activeWorktreeId
+      const lastActiveTabByWorktree =
+        action.sessionId === state.currentSessionId &&
+        leavingWorktreeId != null &&
+        leavingWorktreeId !== '' &&
+        state.activeTabId != null &&
+        state.activeTabId !== ''
+          ? { ...state.lastActiveTabByWorktree, [leavingWorktreeId]: state.activeTabId }
+          : state.lastActiveTabByWorktree
       // Changing the worktree of a non-current session has no effect on
       // which tab the user is looking at — leave activeTabId alone.
       if (action.sessionId !== state.currentSessionId) {
-        return { ...state, sessions }
+        return { ...state, lastActiveTabByWorktree, sessions }
       }
       // For the current session: if the existing activeTabId belongs to
-      // the new worktree, keep it. Otherwise hop to the first tab visible
-      // under that worktree (or clear it if the worktree is empty — the
-      // pane then renders the "this worktree has no tabs" placeholder).
+      // the new worktree, keep it. Otherwise restore the last tab we viewed
+      // in that worktree, falling back to the first visible tab (or clearing
+      // it if the worktree is empty — the pane then renders the "this
+      // worktree has no tabs" placeholder).
       const updated = sessions.find((s) => s.id === action.sessionId)
       const visible = filterTabsForActiveWorktree(state.tabs, updated)
       const currentStillVisible =
@@ -212,9 +238,14 @@ export function reduceSessionState(state: AppState, action: AppAction): AppState
         state.activeTabId !== '' &&
         visible.some((t) => t.id === state.activeTabId)
       if (currentStillVisible) {
-        return { ...state, sessions }
+        return { ...state, lastActiveTabByWorktree, sessions }
       }
-      return { ...state, activeTabId: visible[0]?.id ?? null, sessions }
+      const remembered = lastActiveTabByWorktree[action.worktreeId]
+      const nextActiveTabId =
+        remembered != null && remembered !== '' && visible.some((t) => t.id === remembered)
+          ? remembered
+          : (visible[0]?.id ?? null)
+      return { ...state, activeTabId: nextActiveTabId, lastActiveTabByWorktree, sessions }
     }
     case 'update-worktree-record':
       return {

package/src/state/selectors.ts

@@ -1,5 +1,15 @@
 import type { AssistantOption } from '../pty/command-registry'
-import type { SessionRecord, SnippetRecord } from './types'
+import type { AssistantId, SessionRecord, SnippetRecord } from './types'
+
+/**
+ * 0 when the template picker should NOT show the "None" fallback (no assistant
+ * was picked — typical for the template shortcut path), 1 otherwise. Shared
+ * by the modal reducer, the side-effect that resolves templateId, and the
+ * picker UI so the three stay in sync.
+ */
+export function getTemplateNoneOffset(selectedAssistantId: AssistantId | null): 0 | 1 {
+  return selectedAssistantId == null ? 0 : 1
+}
 
 export function filterAssistants(
   options: AssistantOption[],

package/src/state/session-persistence.ts

@@ -15,6 +15,15 @@ export function createEmptyWorkspaceSnapshot(): WorkspaceSnapshotV1 {
   }
 }
 
+/**
+ * The per-worktree last-tab memory is serialized into every snapshot now so the
+ * data accrues across sessions, but restoring it at startup stays dormant until
+ * a future (non-breaking) change is ready to consume it. Flipping this to true
+ * makes restart restore the last-viewed tab per worktree; until then restart
+ * behavior is unchanged and the live in-memory map is never clobbered on switch.
+ */
+const RESTORE_LAST_ACTIVE_TAB_BY_WORKTREE: boolean = false
+
 function getDisconnectedStatus(status: TabStatus): TabStatus {
   if (status === 'running' || status === 'starting') {
     return 'disconnected'
@@ -26,6 +35,10 @@ function getDisconnectedStatus(status: TabStatus): TabStatus {
 export function serializeWorkspace(state: AppState): WorkspaceSnapshotV1 {
   return {
     activeTabId: state.activeTabId,
+    lastActiveTabByWorktree:
+      Object.keys(state.lastActiveTabByWorktree).length > 0
+        ? state.lastActiveTabByWorktree
+        : undefined,
     layoutTree: Object.values(state.layoutTrees)[0] ?? undefined,
     layoutTrees: Object.keys(state.layoutTrees).length > 0 ? state.layoutTrees : undefined,
     savedAt: new Date().toISOString(),
@@ -241,7 +254,8 @@ export function restoreWorkspaceState(
 ): Pick<
   AppState,
   'tabs' | 'activeTabId' | 'focusMode' | 'sidebar' | 'layoutTrees' | 'tabGroupMap'
-> {
+> &
+  Partial<Pick<AppState, 'lastActiveTabByWorktree'>> {
   const tabs = restoreTabsFromWorkspace(workspaceSnapshot, options)
   const activeTabId =
     workspaceSnapshot?.activeTabId != null &&
@@ -253,6 +267,14 @@ export function restoreWorkspaceState(
   const { layoutTrees, tabGroupMap } = restoreLayoutTrees(workspaceSnapshot, tabs)
   const orderedTabs = normalizeGroupedTabOrder(tabs, layoutTrees, tabGroupMap)
 
+  // Dormant until the gate flips: merge the persisted per-worktree memory over
+  // the live in-memory map. While off, the key is omitted entirely so callers
+  // that spread the result never overwrite their existing map on a switch.
+  const persistedLastActiveTab =
+    RESTORE_LAST_ACTIVE_TAB_BY_WORKTREE && workspaceSnapshot?.lastActiveTabByWorktree
+      ? { ...state.lastActiveTabByWorktree, ...workspaceSnapshot.lastActiveTabByWorktree }
+      : undefined
+
   return {
     activeTabId,
     focusMode: 'navigation',
@@ -260,5 +282,6 @@ export function restoreWorkspaceState(
     sidebar: state.sidebar,
     tabGroupMap,
     tabs: orderedTabs,
+    ...(persistedLastActiveTab ? { lastActiveTabByWorktree: persistedLastActiveTab } : {}),
   }
 }

package/src/state/store.ts

@@ -1,3 +1,5 @@
+import type { WorktreeTemplate } from '../config'
+
 import { reduceAutoCommit } from './reducers/auto-commit-state'
 import { emptyGitMode, reduceGitModeState } from './reducers/git-mode-state'
 import { emptyGitPanel, reduceGitPanelState } from './reducers/git-panel-state'
@@ -31,6 +33,7 @@ export interface InitialStateOverrides {
   gitPane?: Partial<GitPaneState>
   sidebar?: Pick<AppState['sidebar'], 'visible' | 'width'>
   sessionBarVisible?: boolean
+  worktreeTemplates?: WorktreeTemplate[]
 }
 
 const DEFAULT_GIT_PANE: GitPaneState = {
@@ -84,6 +87,7 @@ export function createInitialState(
       position: gitPanePosition,
     },
     gitPanel: emptyGitPanel(),
+    lastActiveTabByWorktree: {},
     layout: {
       terminalCols: DEFAULT_TERMINAL_COLS,
       terminalRows: DEFAULT_TERMINAL_ROWS,
@@ -115,6 +119,7 @@ export function createInitialState(
     tabGroupMap: {},
     tabs: [],
     worktreeDivergence: {},
+    worktreeTemplates: overrides.worktreeTemplates ?? [],
   }
 }
 

package/src/state/types.ts

@@ -1,6 +1,7 @@
 import type { ModeId, SnippetVar } from '@brimveyn/aimux-config'
 import type { ThemedToken } from 'shiki'
 
+import type { WorktreeTemplate } from '../config'
 import type { LayoutNode, SplitDirection } from './layout-tree'
 
 export type BuiltinAssistantId = 'claude' | 'codex' | 'opencode' | 'terminal' | 'antigravity'
@@ -117,6 +118,13 @@ export interface WorkspaceSnapshotV1 {
   layoutTree?: LayoutNode
   layoutTrees?: Record<string, LayoutNode>
   tabGroupMap?: Record<string, string>
+  /**
+   * Last viewed tab per worktree, keyed by worktree id. Optional and additive
+   * (no version bump): older builds ignore it, newer builds tolerate its
+   * absence. Written now so the data accrues, but restoring it at startup is
+   * gated off until a future change flips RESTORE_LAST_ACTIVE_TAB_BY_WORKTREE.
+   */
+  lastActiveTabByWorktree?: Record<string, string>
 }
 
 export type WorktreeSource = 'primary' | 'aimux-temp' | 'external'
@@ -320,7 +328,7 @@ export interface ModalNewTab extends ModalBase {
   branchName: string
   createWorktree: boolean
   selectedAssistantId: AssistantId | null
-  step: 'assistant' | 'worktree' | 'worktree-create'
+  step: 'assistant' | 'worktree' | 'worktree-create' | 'template'
   targetWorktreeIndex: number
   worktreeDeleteConfirmId: string | null
   worktreeDeleteMessage: string | null
@@ -489,8 +497,16 @@ export interface AppState {
    * keyed by worktree id. Ephemeral (polled); not persisted to the catalog.
    */
   worktreeDivergence: Record<string, BranchDivergence>
+  /**
+   * Last active tab a user viewed within each worktree, keyed by worktree id.
+   * Lets switching back to a worktree restore its last-viewed tab instead of
+   * snapping to the first one. Ephemeral (in-memory); not persisted to the catalog.
+   */
+  lastActiveTabByWorktree: Record<string, string>
   /** Chord prefix the sequence resolver is currently waiting on, or null when idle. */
   pendingChords: string[] | null
+  /** User-defined templates applied at worktree creation. Loaded from aimux.json. */
+  worktreeTemplates: WorktreeTemplate[]
 }
 
 // -- Modal actions --
@@ -504,6 +520,8 @@ export type ModalAction =
       message: string | null
     }
   | { type: 'enter-new-tab-worktree-create' }
+  | { type: 'enter-new-tab-template-pick' }
+  | { type: 'enter-new-tab-template-shortcut' }
   | { type: 'select-new-tab-assistant'; assistantId?: AssistantId }
   | { type: 'toggle-new-tab-worktree'; assistantId?: AssistantId }
   | { type: 'open-edit-custom-command'; assistantId: AssistantId }

package/src/ui/components/modals/tabs/new-tab-modal.tsx

@@ -1,10 +1,11 @@
 import { useCallback, useMemo } from 'react'
 
+import type { WorktreeTemplate } from '../../../../config'
 import type { AssistantId, WorktreeRecord } from '../../../../state/types'
 
 import { getAllAssistantOptions, getAssistantOption } from '../../../../pty/command-registry'
 import { dispatchGlobal, runSideEffectGlobal } from '../../../../state/dispatch-ref'
-import { filterAssistants } from '../../../../state/selectors'
+import { filterAssistants, getTemplateNoneOffset } from '../../../../state/selectors'
 import { useTheme } from '../../../theme'
 import { uiTokens } from '../../../ui-tokens'
 import { Form, TextField } from '../shared/form'
@@ -23,13 +24,22 @@ interface NewTabModalProps {
   branchName: string
   createWorktree: boolean
   selectedAssistantId: AssistantId | null
-  step: 'assistant' | 'worktree' | 'worktree-create'
+  step: 'assistant' | 'worktree' | 'worktree-create' | 'template'
   worktreeDeleteConfirmId: string | null
   worktreeDeleteMessage: string | null
   worktrees: WorktreeRecord[]
   worktreeName: string
+  worktreeTemplates: WorktreeTemplate[]
+  /**
+   * True when this modal is the worktree-aware new-tab flow. False when the
+   * component is reused for `split-picker`, which can only choose an
+   * assistant — the template shortcut entry must be hidden there.
+   */
+  allowTemplateShortcut: boolean
 }
 
+const TEMPLATE_SHORTCUT_KEY = '__template-shortcut__'
+
 function getDeleteBlockedReason({
   currentSessionId,
   worktree,
@@ -52,6 +62,7 @@ function getDeleteBlockedReason({
 
 export function NewTabModal({
   activeField,
+  allowTemplateShortcut,
   branchError,
   branchName,
   createWorktree,
@@ -68,6 +79,7 @@ export function NewTabModal({
   worktreeDeleteMessage,
   worktreeName,
   worktrees,
+  worktreeTemplates,
 }: NewTabModalProps) {
   const t = useTheme()
   const options = useMemo(() => getAllAssistantOptions(customCommands), [customCommands])
@@ -123,30 +135,86 @@ export function NewTabModal({
     [createWorktree, currentSessionId, selectedIndex, t, worktreeDeleteConfirmId, worktrees]
   )
 
-  const items = useMemo<PickerItem[]>(
-    () =>
-      filtered.map((option, index) => {
-        const active = index === selectedIndex
-        const customCmd = customCommands[option.id]
+  const noneOffset = getTemplateNoneOffset(selectedAssistantId)
+  const showNoneOption = noneOffset === 1
+  const templateItems = useMemo<PickerItem[]>(() => {
+    const noneItem: PickerItem[] = showNoneOption
+      ? [
+          {
+            key: '__none__',
+            onClick: () => {
+              dispatchGlobal({ index: 0, type: 'set-modal-selection-index' })
+              runSideEffectGlobal({ type: 'launch-selected-assistant' })
+            },
+            subtitle: <text fg={t.textMuted}>Single pane — current assistant only</text>,
+            title: <text fg={selectedIndex === 0 ? t.text : t.textMuted}>None</text>,
+          },
+        ]
+      : []
+    return [
+      ...noneItem,
+      ...worktreeTemplates.map((template, idx) => {
+        const itemIndex = idx + noneOffset
+        const active = itemIndex === selectedIndex
+        const tabCount = template.tabs.length
+        const paneCount = template.tabs.reduce((sum, tab) => sum + tab.panes.length, 0)
         return {
-          key: option.id,
-          onClick: () =>
-            dispatchGlobal({ assistantId: option.id, type: 'select-new-tab-assistant' }),
-          onEdit: () =>
-            dispatchGlobal({ assistantId: option.id, type: 'open-edit-custom-command' }),
-          subtitle: (
-            <box flexDirection="column">
-              <text fg={t.textMuted}>{option.description}</text>
-              {customCmd != null && customCmd !== '' ? (
-                <text fg={t.primary}>{customCmd}</text>
-              ) : null}
-            </box>
-          ),
-          title: <text fg={active ? t.text : t.textMuted}>{option.label}</text>,
+          key: template.id,
+          onClick: () => {
+            dispatchGlobal({ index: itemIndex, type: 'set-modal-selection-index' })
+            runSideEffectGlobal({ type: 'launch-selected-assistant' })
+          },
+          subtitle:
+            template.description != null && template.description !== '' ? (
+              <text fg={t.textMuted}>{template.description}</text>
+            ) : (
+              <text fg={t.textMuted}>
+                {tabCount} tab{tabCount === 1 ? '' : 's'}, {paneCount} pane
+                {paneCount === 1 ? '' : 's'}
+              </text>
+            ),
+          title: <text fg={active ? t.text : t.textMuted}>{template.name}</text>,
         }
       }),
-    [customCommands, filtered, selectedIndex, t]
-  )
+    ]
+  }, [noneOffset, selectedIndex, showNoneOption, t, worktreeTemplates])
+
+  const showShortcutEntry = allowTemplateShortcut && worktreeTemplates.length > 0
+  const items = useMemo<PickerItem[]>(() => {
+    const assistantItems: PickerItem[] = filtered.map((option, index) => {
+      const active = index === selectedIndex
+      const customCmd = customCommands[option.id]
+      return {
+        key: option.id,
+        onClick: () => dispatchGlobal({ assistantId: option.id, type: 'select-new-tab-assistant' }),
+        onEdit: () => dispatchGlobal({ assistantId: option.id, type: 'open-edit-custom-command' }),
+        subtitle: (
+          <box flexDirection="column">
+            <text fg={t.textMuted}>{option.description}</text>
+            {customCmd != null && customCmd !== '' ? <text fg={t.primary}>{customCmd}</text> : null}
+          </box>
+        ),
+        title: <text fg={active ? t.text : t.textMuted}>{option.label}</text>,
+      }
+    })
+    if (!showShortcutEntry) return assistantItems
+    const shortcutIndex = filtered.length
+    const shortcutActive = shortcutIndex === selectedIndex
+    return [
+      ...assistantItems,
+      {
+        key: TEMPLATE_SHORTCUT_KEY,
+        onClick: () => {
+          dispatchGlobal({ index: shortcutIndex, type: 'set-modal-selection-index' })
+          dispatchGlobal({ type: 'enter-new-tab-template-shortcut' })
+        },
+        subtitle: (
+          <text fg={t.textMuted}>Create a worktree and pick a template — no assistant step</text>
+        ),
+        title: <text fg={shortcutActive ? t.text : t.textMuted}>Worktree from template…</text>,
+      },
+    ]
+  }, [customCommands, filtered, showShortcutEntry, selectedIndex, t])
 
   if (editingCommand !== null) {
     const option = options.find((o) => o.id === editingCommand) ?? getAssistantOption(0)
@@ -167,6 +235,28 @@ export function NewTabModal({
     )
   }
 
+  if (step === 'template') {
+    return (
+      <Picker
+        title="Pick worktree template"
+        keybindsModeId="modal.new-tab.command-edit"
+        width={uiTokens.modalWidth.md}
+        gap={1}
+        filter={null}
+        items={templateItems}
+        selectedIndex={selectedIndex}
+        emptyState={<text fg={t.textMuted}>No templates configured.</text>}
+        onHover={handleHover}
+        footer={
+          <box flexDirection="column">
+            <text fg={t.textMuted}>Step 4/4: choose template</text>
+            <text fg={t.textMuted}>Enter launches, Esc returns to worktree settings</text>
+          </box>
+        }
+      />
+    )
+  }
+
   if (step === 'worktree-create') {
     const selectedAssistant =
       options.find((option) => option.id === selectedAssistantId) ?? options[0]

package/src/ui/root.tsx

@@ -3,6 +3,7 @@ import type { MouseEvent } from '@opentui/core'
 import { useCallback, useMemo } from 'react'
 
 import type { MeasuredPaneRect } from '../app-runtime/use-pane-size-report'
+import type { WorktreeTemplate } from '../config'
 import type { TerminalContentOrigin } from '../input/raw-input-handler'
 import type {
   FocusMode,
@@ -92,6 +93,7 @@ function renderModal(
     activeAssistant?: string
     autoCommitModel?: string
     worktreeDivergence: Record<string, { ahead: number; behind: number }>
+    worktreeTemplates: WorktreeTemplate[]
   }
 ) {
   switch (modal.type) {
@@ -121,6 +123,8 @@ function renderModal(
               : EMPTY_WORKTREES
           }
           worktreeName={modal.type === 'new-tab' ? modal.worktreeName : ''}
+          worktreeTemplates={options.worktreeTemplates}
+          allowTemplateShortcut={modal.type === 'new-tab'}
         />
       )
     case 'session-picker':
@@ -316,6 +320,7 @@ export function RootView({
   const sessions = useAppStore((s) => s.sessions)
   const currentSessionId = useAppStore((s) => s.currentSessionId)
   const worktreeDivergence = useAppStore((s) => s.worktreeDivergence)
+  const worktreeTemplates = useAppStore((s) => s.worktreeTemplates)
   const gitPaneMode = useAppStore((s) => s.gitPane.mode)
   const gitPaneVisible = useAppStore((s) => s.gitPane.visible)
   const gitPanePosition = useAppStore((s) => s.gitPane.position)
@@ -410,6 +415,7 @@ export function RootView({
           snippets,
           themeId,
           worktreeDivergence,
+          worktreeTemplates,
         })}
         <ToastViewport />
       </box>
@@ -507,6 +513,7 @@ export function RootView({
         snippets,
         themeId,
         worktreeDivergence,
+        worktreeTemplates,
       })}
       <ToastViewport />
     </box>