@brimveyn/aimux 1.21.0 → 1.22.2

package/README.md

@@ -1,7 +1,7 @@
 # aimux
 
 A terminal multiplexer for AI CLIs. Run Claude, Codex, OpenCode, and normal
-shell tabs side by side in one TUI with persistent workspaces, split panes,
+shell tabs side by side in one TUI with persistent projects, split panes,
 snippets, themes, and fully configurable keymaps.
 
 ![Built with Bun](https://img.shields.io/badge/runtime-Bun-f9f1e1)
@@ -12,19 +12,19 @@ snippets, themes, and fully configurable keymaps.
 
 ## Features
 
-- multi-workspace workflow with a dedicated workspace picker
+- multi-project workflow with a dedicated project picker
 - tabs for `claude`, `codex`, `opencode`, `grok`, `kimi`, and `terminal`
 - split panes with pane focus and resize shortcuts
-- persistent workspaces with saved layout and tab state
+- persistent projects with saved layout and tab state
 - profile-isolated config, catalogs, daemon sockets, and runtime state
 - typed keymap customization through `@brimveyn/aimux-config`
 - snippets catalog and snippet picker
 - configurable git pane (embedded in the sidebar or as a standalone pane) and a
   dedicated [git mode](docs/guide/git-mode.md) for review / stage / commit /
   push with a split or stacked diff view and shiki-powered highlighting
-- [git worktrees](docs/guide/worktrees.md) for running agents on parallel
-  branches — create per-branch worktrees, review each against its base, and
-  squash-move a worktree's work into another
+- [git worktrees](docs/guide/workspaces.md) for running agents on parallel
+  branches — create per-branch workspaces, review each against its base, and
+  squash-move a workspace's work into another
 - built-in help generated from the resolved keymap
 - theme picker with 67 built-in themes (shiki catalog + aimux house themes) and a `/` filter
 
@@ -59,18 +59,18 @@ Create `~/.config/aimux/default/aimux.config.ts`:
 import { defineConfig, actions } from '@brimveyn/aimux-config'
 
 export default defineConfig({
-  sessionBar: {
+  projectBar: {
     initialPosition: 'top',
     initialVisible: true,
   },
 
   keymaps: (k) =>
-    k.mode('navigation', (m) => m.map('<C-p>', actions.sessionPicker, 'Workspace picker')),
+    k.mode('navigation', (m) => m.map('<C-g>', actions.projectPicker, 'Project picker')),
 })
 ```
 
 Typed config is startup intent, not app-managed persisted state. Fields like
-`sessionBar.initialVisible` and `sessionBar.initialPosition` are reapplied on
+`projectBar.initialVisible` and `projectBar.initialPosition` are reapplied on
 every launch, so runtime UI changes for those fields do not stick while the
 config entry remains set.
 
@@ -80,7 +80,7 @@ Then start the app:
 aimux
 ```
 
-On first launch, use the workspace picker flow to create your first workspace.
+On first launch, use the project picker flow to create your first project.
 
 For the full setup path, see [`docs/getting-started.md`](docs/getting-started.md).
 
@@ -109,7 +109,7 @@ profile. See [`docs/concepts/profiles.md`](docs/concepts/profiles.md).
 
 - `aimux.config.ts` or `aimux.config.js` - typed user config
 - `aimux.json` - app-managed preferences and runtime state
-- `aimux-sessions.json` - workspace catalog and workspace snapshots
+- `aimux-projects.json` - project catalog and project snapshots
 - `aimux-snippets.json` - snippet catalog
 
 Rule of thumb:
@@ -120,17 +120,19 @@ Rule of thumb:
 
 See [`docs/concepts/config-and-state.md`](docs/concepts/config-and-state.md).
 
-### Workspaces
+### Projects
 
-Workspaces are the top-level user-facing concept in `aimux`. Internally, the
-runtime still uses `session` naming for compatibility. A workspace can have:
+A project is a repository you add by picking a folder. Inside it live
+workspaces (git worktrees), and inside those live tabs — one creation action
+per level: `Ctrl+G` for a project, `Ctrl+P` for a workspace, `Ctrl+N` for a
+tab. A project can have:
 
 - a name
 - an optional project directory
-- a persisted workspace snapshot
-- an order in the workspace bar and workspace picker
+- a persisted project snapshot
+- an order in the project bar and project picker
 
-See [`docs/guide/sessions.md`](docs/guide/sessions.md).
+See [`docs/guide/projects.md`](docs/guide/projects.md).
 
 ### Keymaps
 
@@ -149,13 +151,13 @@ See [`docs/guide/keymaps.md`](docs/guide/keymaps.md).
 - `i` - focus terminal
 - `Ctrl+Z` - leave terminal-input mode
 - `Ctrl+N` - open new-tab modal
-- `Ctrl+G` - open workspace picker
+- `Ctrl+G` - open project picker
 - `Ctrl+S` - open snippet picker
 - `Ctrl+T` - open theme picker
 - `Ctrl+B` - toggle sidebar
 - `Ctrl+D` - enter git mode
-- `Ctrl+W b` - toggle workspace bar
-- `Ctrl+W 1` through `Ctrl+W 9` - switch workspaces by index
+- `Ctrl+W b` - toggle project bar
+- `Ctrl+W 1` through `Ctrl+W 9` - switch projects by index
 
 The help modal reflects the resolved keymap, so it includes your overrides.
 
@@ -175,10 +177,10 @@ aimux restart-terminal-manager
 See [`docs/reference/cli.md`](docs/reference/cli.md) for behavior details.
 
 For agent orchestration, prefer the named `aimux worker` commands. They combine
-isolated worktree creation, prompt dispatch, authoritative turn waiting, fleet
+isolated workspace creation, prompt dispatch, authoritative turn waiting, fleet
 inspection, and guarded cleanup without shell wrappers or `jq`. Pin the target
-with `--workspace` (or `AIMUX_WORKSPACE`) for anything long-running: the default
-follows whichever workspace the UI opened last.
+with `--project` (or `AIMUX_PROJECT`) for anything long-running: the default
+follows whichever project the UI opened last.
 
 ## Runtime Model
 
@@ -198,7 +200,7 @@ See [`docs/developer/architecture.md`](docs/developer/architecture.md).
 - [`docs/getting-started.md`](docs/getting-started.md)
 - [`docs/concepts/config-and-state.md`](docs/concepts/config-and-state.md)
 - [`docs/concepts/profiles.md`](docs/concepts/profiles.md)
-- [`docs/guide/sessions.md`](docs/guide/sessions.md)
+- [`docs/guide/projects.md`](docs/guide/projects.md)
 - [`docs/guide/keymaps.md`](docs/guide/keymaps.md)
 - [`docs/guide/themes.md`](docs/guide/themes.md)
 - [`docs/reference/cli.md`](docs/reference/cli.md)
@@ -233,7 +235,7 @@ not collide with a globally installed `aimux` instance.
   and the source of the bundled theme catalog.
 - [herdr](https://github.com/ogulcancelik/herdr) by @ogulcancelik — the
   per-CLI assistant status heuristics (working / waiting-input / idle)
-  used in the workspace bar are adapted from herdr's `detect.rs` rule tables.
+  used in the project bar are adapted from herdr's `detect.rs` rule tables.
 
 ## License
 

package/package.json

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

package/src/app-runtime/auto-commit-driver.ts

@@ -1,12 +1,7 @@
 import { $ } from 'bun'
 
-import type {
-  AppAction,
-  AppState,
-  AssistantId,
-  AutoCommitState,
-  GitRefreshPayload,
-} from '../state/types'
+import type { AppAction } from '../state/actions'
+import type { AppState, AssistantId, AutoCommitState, GitRefreshPayload } from '../state/types'
 
 import { buildHeadlessInvocation, isSupportedProvider } from '../auto-commit/headless-commands'
 import { composePromptFromTemplate, loadBriefingTemplate } from '../auto-commit/prompt-loader'
@@ -22,7 +17,7 @@ export interface TriggerInput {
   assistant: AssistantId
   hasProjectPath: boolean
   git: GitRefreshPayload
-  sessionId: string
+  projectId: string
   state: AutoCommitState
   currentHash: string
 }
@@ -33,7 +28,7 @@ export function shouldTriggerAutoCommit(input: TriggerInput): boolean {
   if (!input.hasProjectPath) return false
   if (input.git.files.length === 0) return false
 
-  const existing = input.state.bySession[input.sessionId]
+  const existing = input.state.byProject[input.projectId]
   if (!existing || existing.kind === 'idle') return true
   if (existing.workingTreeHash === input.currentHash) return false
   return true
@@ -61,14 +56,14 @@ async function getTemplate(deps: DriverDeps): Promise<string> {
 }
 
 const UNTRACKED_FILE_BYTES_CAP = 8_000
-const SESSION_TAIL_BYTES_CAP = 8_000
+const PROJECT_TAIL_BYTES_CAP = 8_000
 
 export function extractSessionTail(buffer: string | undefined): string {
   if (!(buffer != null && buffer !== '')) return '[no session tail available]'
   const stripped = stripAnsi(buffer).trimEnd()
   if (stripped.length === 0) return '[no session tail available]'
-  return stripped.length > SESSION_TAIL_BYTES_CAP
-    ? stripped.slice(stripped.length - SESSION_TAIL_BYTES_CAP)
+  return stripped.length > PROJECT_TAIL_BYTES_CAP
+    ? stripped.slice(stripped.length - PROJECT_TAIL_BYTES_CAP)
     : stripped
 }
 
@@ -140,7 +135,7 @@ async function gatherContext(cwd: string, stagedOnly: boolean): Promise<Gathered
 }
 
 export interface ActivityTransitionArgs {
-  sessionId: string
+  projectId: string
   tabId: string
   assistant: AssistantId
   projectPath: string | undefined
@@ -163,7 +158,7 @@ export async function onActivityTransition(
     enabled: config.enabled,
     git: args.git,
     hasProjectPath: !!(args.projectPath != null && args.projectPath !== ''),
-    sessionId: args.sessionId,
+    projectId: args.projectId,
     state: state.autoCommit,
   })
   if (!should) return
@@ -180,15 +175,15 @@ export async function onManualTrigger(
     // Manual auto-commit triggers can fire outside git mode, so surface the
     // reason as a toast rather than an inline git-pane message that's unseen.
     toast.warning(`Auto-commit: ${reason}`)
-    deps.dispatch({ sessionId: args.sessionId, type: 'auto-commit-clear' })
+    deps.dispatch({ projectId: args.projectId, type: 'auto-commit-clear' })
   }
   if (!config.enabled) return fail('disabled in config')
   if (!args.git || args.git.files.length === 0) return fail('no changes to summarise')
   if (!(args.projectPath != null && args.projectPath !== ''))
-    return fail('no project path for current session')
+    return fail('no project path for current project')
 
   const currentHash = workingTreeHash(args.git)
-  const existing = deps.getState().autoCommit.bySession[args.sessionId]
+  const existing = deps.getState().autoCommit.byProject[args.projectId]
   // An in-flight generation will dispatch ready/clear; just wait for it.
   if (existing && existing.kind === 'generating') return
   // Manual trigger is always user-intent to regenerate, even if a ready
@@ -213,11 +208,11 @@ async function runGeneration(
   if (!probe) return
   if (!isCommandAvailable(probe.executable)) return
 
-  // Supersede any in-flight generation for this session. Without this, a
+  // Supersede any in-flight generation for this project. Without this, a
   // rapid sequence of activity transitions (each with a different working
   // tree hash) would leak concurrent headless subprocesses until each hit
   // its 60 s timeout — burning real API credits.
-  const existing = deps.getState().autoCommit.bySession[args.sessionId]
+  const existing = deps.getState().autoCommit.byProject[args.projectId]
   if (existing && existing.kind === 'generating') {
     try {
       existing.abortController.abort()
@@ -229,7 +224,7 @@ async function runGeneration(
   const controller = new AbortController()
   deps.dispatch({
     abortController: controller,
-    sessionId: args.sessionId,
+    projectId: args.projectId,
     startedAt: Date.now(),
     tabId: args.tabId,
     type: 'auto-commit-generation-started',
@@ -240,7 +235,7 @@ async function runGeneration(
   const stagedOnly = args.git ? hasStagedFiles(args.git) : false
   const ctx = await gatherContext(args.projectPath as string, stagedOnly)
   if (!ctx) {
-    deps.dispatch({ sessionId: args.sessionId, type: 'auto-commit-clear' })
+    deps.dispatch({ projectId: args.projectId, type: 'auto-commit-clear' })
     return
   }
   const tab = deps.getState().tabs.find((t) => t.id === args.tabId)
@@ -252,7 +247,7 @@ async function runGeneration(
     config.models[args.assistant]
   )
   if (!finalInvocation) {
-    deps.dispatch({ sessionId: args.sessionId, type: 'auto-commit-clear' })
+    deps.dispatch({ projectId: args.projectId, type: 'auto-commit-clear' })
     return
   }
 
@@ -262,13 +257,13 @@ async function runGeneration(
     timeoutMs: config.timeoutMs,
   })
   if (!parsed) {
-    deps.dispatch({ sessionId: args.sessionId, type: 'auto-commit-clear' })
+    deps.dispatch({ projectId: args.projectId, type: 'auto-commit-clear' })
     return
   }
   deps.dispatch({
     body: parsed.body,
     generatedAt: Date.now(),
-    sessionId: args.sessionId,
+    projectId: args.projectId,
     title: parsed.title,
     type: 'auto-commit-generation-ready',
     workingTreeHash: currentHash,
@@ -277,14 +272,14 @@ async function runGeneration(
 
 export function onGitRefresh(
   deps: DriverDeps,
-  sessionId: string,
+  projectId: string,
   payload: GitRefreshPayload
 ): void {
   const state = deps.getState()
-  const current = state.autoCommit.bySession[sessionId]
+  const current = state.autoCommit.byProject[projectId]
   if (!current || current.kind === 'idle') return
   const newHash = workingTreeHash(payload)
   if (newHash !== current.workingTreeHash) {
-    deps.dispatch({ sessionId, type: 'auto-commit-clear' })
+    deps.dispatch({ projectId, type: 'auto-commit-clear' })
   }
 }

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

@@ -1,7 +1,8 @@
 import type { MutableRefObject } from 'react'
 
 import type { SessionBackend } from '../session-backend/types'
-import type { AppAction, LayoutState, TabSession, WorkspaceSnapshotV1 } from '../state/types'
+import type { AppAction } from '../state/actions'
+import type { LayoutState, ProjectSnapshotV1, TabSession } from '../state/types'
 
 import { logInputDebug } from '../debug/input-log'
 import {
@@ -10,9 +11,10 @@ import {
   getSnapshotTrees,
   toTerminalContentSize,
 } from '../state/layout-resize'
+import { seedTabActivity } from './workspace-activity'
 
 export function resizeSnapshotPanes(
-  snapshot: WorkspaceSnapshotV1 | undefined,
+  snapshot: ProjectSnapshotV1 | undefined,
   layoutRef: MutableRefObject<LayoutState>,
   backend: SessionBackend
 ): void {
@@ -33,64 +35,69 @@ export function resizeSnapshotPanes(
 
 function mergeSnapshotTabMetadata(
   tabs: TabSession[],
-  workspaceSnapshot: WorkspaceSnapshotV1 | undefined
+  projectSnapshot: ProjectSnapshotV1 | undefined
 ): TabSession[] {
-  if (!workspaceSnapshot) return tabs
-  const persistedById = new Map(workspaceSnapshot.tabs.map((tab) => [tab.id, tab]))
+  if (!projectSnapshot) return tabs
+  const persistedById = new Map(projectSnapshot.tabs.map((tab) => [tab.id, tab]))
   return tabs.map((tab) => {
     const persisted = persistedById.get(tab.id)
-    return persisted?.worktreeId != null &&
-      persisted?.worktreeId !== '' &&
-      !(tab.worktreeId != null && tab.worktreeId !== '')
-      ? { ...tab, worktreeId: persisted.worktreeId }
+    return persisted?.workspaceId != null &&
+      persisted?.workspaceId !== '' &&
+      !(tab.workspaceId != null && tab.workspaceId !== '')
+      ? { ...tab, workspaceId: persisted.workspaceId }
       : tab
   })
 }
 
 function hydrateAttachedSession(
   dispatch: (action: AppAction) => void,
-  sessionId: string,
-  workspaceSnapshot: WorkspaceSnapshotV1 | undefined,
+  projectId: string,
+  projectSnapshot: ProjectSnapshotV1 | undefined,
   result: Awaited<ReturnType<SessionBackend['attach']>>,
   layoutRef: MutableRefObject<LayoutState>,
   backend: SessionBackend
 ): void {
   if (result) {
+    const tabs = mergeSnapshotTabMetadata(result.tabs, projectSnapshot)
     dispatch({
       activeTabId: result.activeTabId,
-      layoutTree: workspaceSnapshot?.layoutTree,
-      layoutTrees: workspaceSnapshot?.layoutTrees,
-      tabGroupMap: workspaceSnapshot?.tabGroupMap,
-      tabs: mergeSnapshotTabMetadata(result.tabs, workspaceSnapshot),
-      type: 'hydrate-workspace',
+      layoutTree: projectSnapshot?.layoutTree,
+      layoutTrees: projectSnapshot?.layoutTrees,
+      tabGroupMap: projectSnapshot?.tabGroupMap,
+      tabs,
+      type: 'hydrate-project',
     })
-    // Dispatch the session-status snapshot *after* hydrate-workspace so
-    // sidebar chips reflect per-session state on attach without waiting
+    // Same reason as the project-status snapshot below, one level down: the
+    // per-tab statuses are edge-triggered, so a workspace whose agent has been
+    // waiting since before this client started would otherwise draw nothing.
+    seedTabActivity(tabs)
+    // Dispatch the project-status snapshot *after* hydrate-project so
+    // sidebar chips reflect per-project state on attach without waiting
     // for the next daemon-side status transition.
-    for (const entry of result.initialSessionStatuses) {
-      dispatch({ sessionId: entry.sessionId, status: entry.status, type: 'set-session-status' })
+    for (const entry of result.initialProjectStatuses) {
+      dispatch({ projectId: entry.projectId, status: entry.status, type: 'set-project-status' })
     }
-    resizeSnapshotPanes(workspaceSnapshot, layoutRef, backend)
+    resizeSnapshotPanes(projectSnapshot, layoutRef, backend)
     return
   }
 
-  if (!workspaceSnapshot) {
+  if (!projectSnapshot) {
     return
   }
 
   dispatch({
-    sessionId,
-    type: 'load-session',
-    workspaceSnapshot,
+    projectId,
+    projectSnapshot,
+    type: 'load-project',
   })
-  resizeSnapshotPanes(workspaceSnapshot, layoutRef, backend)
+  resizeSnapshotPanes(projectSnapshot, layoutRef, backend)
 }
 
 interface AttachCurrentSessionOptions {
   backend: SessionBackend
   dispatch: (action: AppAction) => void
-  currentSessionId: string
-  currentSessionWorkspaceSnapshot: Parameters<SessionBackend['attach']>[0]['workspaceSnapshot']
+  currentProjectId: string
+  currentProjectProjectSnapshot: Parameters<SessionBackend['attach']>[0]['projectSnapshot']
   layoutRef: MutableRefObject<LayoutState>
   attachRequestIdRef: MutableRefObject<number>
 }
@@ -98,8 +105,8 @@ interface AttachCurrentSessionOptions {
 export function attachCurrentSession({
   attachRequestIdRef,
   backend,
-  currentSessionId,
-  currentSessionWorkspaceSnapshot,
+  currentProjectId,
+  currentProjectProjectSnapshot,
   dispatch,
   layoutRef,
 }: AttachCurrentSessionOptions): () => void {
@@ -111,9 +118,9 @@ export function attachCurrentSession({
     try {
       const result = await backend.attach({
         cols: layoutRef.current.terminalCols,
+        projectId: currentProjectId,
+        projectSnapshot: currentProjectProjectSnapshot,
         rows: layoutRef.current.terminalRows,
-        sessionId: currentSessionId,
-        workspaceSnapshot: currentSessionWorkspaceSnapshot,
       })
       if (cancelled || attachRequestIdRef.current !== attachRequestId) {
         return
@@ -126,8 +133,8 @@ export function attachCurrentSession({
       })
       hydrateAttachedSession(
         dispatch,
-        currentSessionId,
-        currentSessionWorkspaceSnapshot,
+        currentProjectId,
+        currentProjectProjectSnapshot,
         result,
         layoutRef,
         backend
@@ -142,8 +149,8 @@ export function attachCurrentSession({
       })
       hydrateAttachedSession(
         dispatch,
-        currentSessionId,
-        currentSessionWorkspaceSnapshot,
+        currentProjectId,
+        currentProjectProjectSnapshot,
         null,
         layoutRef,
         backend