@brimveyn/aimux 1.14.14 → 1.14.15

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@brimveyn/aimux",
-  "version": "1.14.14",
+  "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/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/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 = {
@@ -116,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'
@@ -327,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
@@ -504,6 +505,8 @@ export interface AppState {
   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 --
@@ -517,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>