@brimveyn/aimux 1.4.0 → 1.5.0

package/README.md

@@ -1,6 +1,8 @@
 # aimux
 
-A terminal multiplexer for AI CLIs. Manage multiple AI assistant sessions (Claude, Codex, OpenCode) side by side in a single terminal with tabbed navigation, split panes, persistent sessions, and fully configurable keybindings.
+A terminal multiplexer for AI CLIs. Run Claude, Codex, OpenCode, and normal
+shell tabs side by side in one TUI with persistent sessions, split panes,
+snippets, themes, and fully configurable keymaps.
 
 ![Built with Bun](https://img.shields.io/badge/runtime-Bun-f9f1e1)
 ![TypeScript](https://img.shields.io/badge/lang-TypeScript-3178c6)
@@ -10,39 +12,16 @@ A terminal multiplexer for AI CLIs. Manage multiple AI assistant sessions (Claud
 
 ## Features
 
-- **Multi-tab sessions** — Run Claude, Codex, and OpenCode in parallel with instant tab switching
-- **Session bar** — Numbered session chips at the top (or bottom) of the screen. Click to switch, drag to reorder, busy spinner for non-focused sessions with live PTY output. Toggle with `<leader>b`; jump with `<leader>1..9`. Position persists via `aimux.config.ts` or `aimux.json`.
-- **Split panes** — Split vertically (`|`) or horizontally (`-`) to view multiple assistants at once
-- **Draggable separators** — Resize split panes by dragging with the mouse
-- **Click-to-focus** — Click any pane or sidebar tab to focus it instantly
-- **Full terminal emulation** — Powered by xterm.js with mouse tracking, alternate buffer, and scrollback
-- **Configurable nvim-style keymaps** — Define keybinds in a typed `aimux.config.ts` with leader keys, multi-key sequences, and a prefix-trie resolver
-- **Text selection** — Double-click for a word, triple-click for a line, drag for a region. Selections copy to system clipboard automatically
-- **Project-scoped sessions** — Associate a git repository with each session; all tabs spawn in that directory
-- **Directory picker** — Fuzzy-search git repos and worktrees from `$HOME` using `fzf`
-- **Session persistence** — Workspace state (tabs, titles, layout) saved and restored on restart
-- **Git status panel** — Branch + diff summary in the sidebar
-- **Seamless daemon updates** — A restartable IPC daemon now reconnects to a long-lived terminal manager, so updates and IPC changes do not kill live tabs
-- **Snippets** — Save and reuse prompt snippets across sessions
-- **Theme picker** — Switch between 11 built-in themes on the fly
-- **Pending-chord indicator** — Bottom-right overlay shows mid-sequence key state (like nvim's `which-key`)
-- **Built-in help** — Press `?` to see all keybindings
-
-### Session Management
-
-![Session management](assets/sessions.gif)
-
-### Multi-Tab Workflow
-
-![Multi-tab workflow](assets/tabs.gif)
-
-### Themes
-
-![Themes](assets/themes.gif)
-
-### Split Panes
-
-![Split panes](assets/splits.gif)
+- multi-session workflow with a dedicated session picker
+- tabs for `claude`, `codex`, `opencode`, and `terminal`
+- split panes with pane focus and resize shortcuts
+- persistent sessions 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 git mode
+- built-in help generated from the resolved keymap
+- theme picker with 11 built-in themes
 
 ## Install
 
@@ -52,178 +31,165 @@ bun install -g @brimveyn/aimux
 
 Requires [Bun](https://bun.sh).
 
-## Usage
-
-```bash
-aimux                  # start the TUI
-aimux version          # print version
-aimux doctor           # check setup
-aimux update           # self-update
-aimux restart-daemon   # restart IPC daemon only
-```
+## Quick Start
 
-`aimux update` and `aimux restart-daemon` restart only the IPC daemon. Live PTYs and headless terminal state stay in the long-lived terminal-manager process, so active tabs can be reattached instead of being restarted.
-
-## Configuration
-
-aimux reads `~/.config/aimux/<profile>/aimux.config.ts` at startup. The default installed profile is `default`, while the repository dev scripts use `dev`. Set up the default profile with:
+Create the default profile and install the typed config package into it:
 
 ```bash
-mkdir -p ~/.config/aimux/default && cd ~/.config/aimux/default
+mkdir -p ~/.config/aimux/default
+cd ~/.config/aimux/default
 bun init -y
 bun add -d @brimveyn/aimux-config
 ```
 
-Then create `~/.config/aimux/default/aimux.config.ts`:
+Create `~/.config/aimux/default/aimux.config.ts`:
 
 ```ts
-import { defineConfig, actions, themes } from '@brimveyn/aimux-config'
+import { defineConfig, actions } from '@brimveyn/aimux-config'
 
 export default defineConfig({
-  theme: themes.extend('tokyo-night', { accent: '#ff9e64' }),
+  sessionBar: {
+    position: 'top',
+    visible: true,
+  },
 
   keymaps: (k) =>
-    k
-      .leader('<Space>')
-      .timeout(300)
-      .mode('navigation', (m) =>
-        m
-          .map('j', actions.nextTab)
-          .map('k', actions.prevTab)
-          .map('<leader>g', actions.sessionPicker)
-          .group('<leader>t', 'tabs', (g) =>
-            g.map('n', actions.newTab).map('r', actions.renameTab).map('x', actions.closeTab)
-          )
-      )
-      .mode('layout', (m) => m.map('|', actions.splitVertical).map('-', actions.splitHorizontal)),
+    k.mode('navigation', (m) => m.map('<C-p>', actions.sessionPicker, 'Session picker')),
 })
 ```
 
-User bindings override defaults. Use `.unmap(keys)` to remove a default. See [`@brimveyn/aimux-config`](packages/aimux-config/README.md) for the full builder API.
-
-### Key notation
-
-| Notation       | Meaning                    |
-| -------------- | -------------------------- |
-| `j`            | Bare character             |
-| `J`            | Shift+J (uppercase letter) |
-| `<C-n>`        | Ctrl+N                     |
-| `<M-x>`        | Meta/Alt+X                 |
-| `<CR>` `<Esc>` | Return / Escape            |
-| `<leader>`     | Configured leader chord    |
-| `dd`           | Multi-key sequence         |
-| `<leader>tn`   | Leader, then t, then n     |
-
-## Default Keymaps
-
-Press `?` in navigation mode for the full, live keybinding list (reflects your config).
-
-### Navigation Mode
-
-| Key                   | Action               |
-| --------------------- | -------------------- |
-| `j` / `k`             | Next / previous tab  |
-| `Shift+J` / `Shift+K` | Reorder tabs         |
-| `i`                   | Enter terminal input |
-| `r`                   | Rename active tab    |
-| `dd`                  | Close active tab     |
-| `Ctrl+N`              | New tab              |
-| `Ctrl+R`              | Restart tab          |
-| `Ctrl+G`              | Session picker       |
-| `Ctrl+B`              | Toggle sidebar       |
-| `Ctrl+H` / `Ctrl+L`   | Resize sidebar       |
-| `Ctrl+S`              | Snippet picker       |
-| `Ctrl+T`              | Theme picker         |
-| `G`                   | Toggle git panel     |
-| `<leader>b`           | Toggle session bar   |
-| `<leader>1..9`        | Switch to session N  |
-| `?`                   | Show help            |
-| `Ctrl+C`              | Quit                 |
-
-### Terminal Input Mode
-
-Keystrokes pass through to the active tab's PTY. Configured shortcuts:
-
-| Key        | Action              |
-| ---------- | ------------------- |
-| `Ctrl+Z`   | Leave to navigation |
-| `<leader>` | Enter layout mode   |
-| `Ctrl+B`   | Toggle sidebar      |
-
-### Layout Mode
-
-| Key                   | Action           |
-| --------------------- | ---------------- |
-| `\|`                  | Split vertical   |
-| `-`                   | Split horizontal |
-| `h` / `j` / `k` / `l` | Focus pane       |
-| `Shift+H/J/K/L`       | Resize pane      |
-| `q`                   | Close pane       |
-| `Esc`                 | Back to input    |
-
-## Architecture
-
-Runtime split:
-
-- `aimux` UI connects to the IPC daemon over the app protocol.
-- The IPC daemon owns the app-facing socket, protocol negotiation, and reconnect behavior.
-- The terminal manager owns PTYs, xterm headless emulators, and live session state.
-
-This split lets the app or IPC daemon change protocols without dropping live shells.
+Then start the app:
 
+```bash
+aimux
 ```
-aimux/
-├── packages/
-│   └── aimux-config/          # published as @brimveyn/aimux-config
-│       └── src/               # types, builder, actions, themes, defaults
-└── src/                       # the CLI (published as @brimveyn/aimux)
-    ├── index.tsx              # entry point + CLI dispatcher
-    ├── app.tsx                # main React app + state wiring
-    ├── config/
-    │   └── loader.ts          # loads aimux.config.ts
-    ├── ui/                    # OpenTUI React components
-    ├── state/                 # reducers + app store
-    ├── pty/                   # PTY and terminal emulation
-    ├── session-backend/       # local and remote backends
-    ├── daemon/                # IPC daemon / broker
-    ├── terminal-manager/      # long-lived PTY/session owner
-    ├── ipc/                   # app and manager protocols
-    └── input/
-        ├── modes/             # mode registry + transitions
-        ├── keymap/            # prefix trie + sequence resolver
-        └── raw-input-handler.ts
+
+On first launch, use the session picker flow to create your first session.
+
+For the full setup path, see [`docs/getting-started.md`](docs/getting-started.md).
+
+## Core Concepts
+
+### Profiles
+
+Profile-managed config and catalogs live under:
+
+```text
+~/.config/aimux/<profile>/
 ```
 
-## Tech Stack
+The active profile is chosen from:
 
-- [Bun](https://bun.sh) — Runtime and toolchain
-- [React](https://react.dev) + [OpenTUI](https://github.com/sst/opentui) — Terminal UI framework
-- [xterm.js](https://xtermjs.org) (headless) — Terminal emulation
-- [bun-pty](https://github.com/nicolo-ribaudo/bun-pty) — Native PTY spawning
-- [Zustand](https://zustand-demo.pmnd.rs/) — State store
+1. `AIMUX_PROFILE`
+2. `AIMUX_RUNTIME_PROFILE`
+3. `default`
 
-## Development
+Runtime sockets live in a separate runtime directory that depends on the active
+profile. See [`docs/concepts/profiles.md`](docs/concepts/profiles.md).
 
-```bash
-git clone https://github.com/BrimVeyn/aimux && cd aimux
-bun install
+### Config vs Runtime State
+
+`aimux` uses multiple files per profile:
+
+- `aimux.config.ts` or `aimux.config.js` - typed user config
+- `aimux.json` - app-managed preferences and runtime state
+- `aimux-sessions.json` - session catalog and workspace snapshots
+- `aimux-snippets.json` - snippet catalog
+
+See [`docs/concepts/config-and-state.md`](docs/concepts/config-and-state.md).
 
-bun run dev              # auto-reload dev mode
-bun run start            # run from source
-bun test                 # run test suite
-bun run check            # typecheck
-bun run lint             # oxlint
+### Sessions
+
+Sessions are named workspaces. A session can have:
+
+- a name
+- an optional project directory
+- a persisted workspace snapshot
+- an order in the session bar and session picker
+
+See [`docs/guide/sessions.md`](docs/guide/sessions.md).
+
+### Keymaps
+
+Keymaps are defined through `@brimveyn/aimux-config` and merged with shipped
+defaults at startup.
+
+Important runtime fact:
+
+- the shipped leader key is `Ctrl+W`
+
+See [`docs/guide/keymaps.md`](docs/guide/keymaps.md).
+
+## Default Everyday Shortcuts
+
+- `?` - open help
+- `i` - focus terminal
+- `Ctrl+Z` - leave terminal-input mode
+- `Ctrl+N` - open new-tab modal
+- `Ctrl+G` - open session picker
+- `Ctrl+S` - open snippet picker
+- `Ctrl+T` - open theme picker
+- `Ctrl+B` - toggle sidebar
+- `Ctrl+W b` - toggle session bar
+- `Ctrl+W 1` through `Ctrl+W 9` - switch sessions by index
+
+The help modal reflects the resolved keymap, so it includes your overrides.
+
+## CLI
+
+```bash
+aimux
+aimux version
+aimux doctor
+aimux update
+aimux restart-daemon
+aimux restart-terminal-manager
 ```
 
-By default the app talks to the background IPC daemon. For explicit single-process debugging only, set `AIMUX_LOCAL_BACKEND=1` before starting aimux.
+See [`docs/reference/cli.md`](docs/reference/cli.md) for behavior details.
+
+## Runtime Model
+
+`aimux` is split into:
+
+- the UI app
+- an IPC daemon
+- a long-lived terminal manager
 
-Profiles live under `~/.config/aimux/<profile>/`. Each profile gets its own config, session catalog, snippet catalog, and matching runtime namespace.
+This split is what allows daemon restarts and some update paths without dropping
+every live PTY immediately.
 
-The repository `bun run dev`, `bun run start`, and `bun run restart-daemon` scripts set `AIMUX_PROFILE=dev`, so source builds use `~/.config/aimux/dev/` and their own IPC daemon / terminal-manager sockets instead of interfering with a globally installed `aimux` instance.
+See [`docs/developer/architecture.md`](docs/developer/architecture.md).
 
-You can override the active profile manually with `AIMUX_PROFILE=<name>` when you need multiple isolated environments on the same machine. `AIMUX_RUNTIME_PROFILE` is still accepted as a fallback alias for runtime compatibility.
+## Documentation Map
+
+- [`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/keymaps.md`](docs/guide/keymaps.md)
+- [`docs/guide/themes.md`](docs/guide/themes.md)
+- [`docs/reference/cli.md`](docs/reference/cli.md)
+- [`docs/reference/config-reference.md`](docs/reference/config-reference.md)
+- [`docs/reference/runtime-paths.md`](docs/reference/runtime-paths.md)
+- [`docs/developer/architecture.md`](docs/developer/architecture.md)
+- [`docs/developer/aimux-config-internals.md`](docs/developer/aimux-config-internals.md)
+
+## Development
+
+```bash
+git clone https://github.com/BrimVeyn/aimux && cd aimux
+bun install
+
+bun run dev
+bun run start
+bun test
+bun run check
+bun run lint
+```
 
-This profile move is intentionally breaking: aimux no longer reads legacy flat config or catalog files once profile directories are enabled.
+The repository dev scripts use `AIMUX_PROFILE=dev`, so local development does
+not collide with a globally installed `aimux` instance.
 
 ## License
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@brimveyn/aimux",
-  "version": "1.4.0",
+  "version": "1.5.0",
   "description": "A terminal multiplexer for AI CLIs. Run Claude, Codex, OpenCode side-by-side with tabbed navigation, split panes, and persistent sessions.",
   "keywords": [
     "ai",
@@ -52,12 +52,15 @@
     "demo:splits": "vhs assets/splits.tape",
     "demo:themes": "vhs assets/themes.tape",
     "restart-daemon": "AIMUX_PROFILE=dev bun run src/index.tsx restart-daemon",
+    "restart-terminal-manager": "AIMUX_PROFILE=dev bun run src/index.tsx restart-terminal-manager",
     "lint": "oxlint .",
     "format": "oxfmt --write .",
-    "format:check": "oxfmt --check ."
+    "format:check": "oxfmt --check .",
+    "knip": "knip-bun",
+    "bump": "bun run scripts/bump.ts"
   },
   "dependencies": {
-    "@brimveyn/aimux-config": "0.3.0",
+    "@brimveyn/aimux-config": "0.3.1",
     "@opentui/core": "^0.1.90",
     "@opentui/react": "^0.1.90",
     "@xterm/headless": "^6.0.0",
@@ -70,6 +73,7 @@
     "@types/node": "^25.5.0",
     "@types/react": "^19.2.14",
     "eslint-plugin-perfectionist": "^5.8.0",
+    "knip": "^6.4.1",
     "lefthook": "^2.1.4",
     "oxfmt": "^0.42.0",
     "oxlint": "^1.57.0",

package/src/app-runtime/use-terminal-resize.ts

@@ -1,4 +1,4 @@
-import { type MutableRefObject, useEffect, useMemo, useRef } from 'react'
+import { type MutableRefObject, useEffect, useLayoutEffect, useMemo, useRef } from 'react'
 
 import type { TerminalContentOrigin } from '../input/raw-input-handler'
 import type { SessionBackend } from '../session-backend/types'
@@ -28,20 +28,21 @@ function resizeSplitTabs(
   tabIds: string[],
   cols: number,
   rows: number,
-  intents: Map<string, ScrollIntent>
+  intents: Map<string, ScrollIntent>,
+  options?: { sync?: boolean }
 ): void {
   const bounds = getTerminalBounds(cols, rows)
   const resizedTabIds = new Set<string>()
 
   forEachSplitPaneRect(Object.values(layoutTrees), bounds, (tabId, rect) => {
     const size = toTerminalContentSize(rect)
-    backend.resizeTab(tabId, size.cols, size.rows, intents.get(tabId))
+    backend.resizeTab(tabId, size.cols, size.rows, intents.get(tabId), options)
     resizedTabIds.add(tabId)
   })
 
   for (const id of tabIds) {
     if (!resizedTabIds.has(id)) {
-      backend.resizeTab(id, cols, rows, intents.get(id))
+      backend.resizeTab(id, cols, rows, intents.get(id), options)
     }
   }
 }
@@ -55,6 +56,50 @@ interface UseTerminalResizeOptions {
   resizingRef: MutableRefObject<boolean>
 }
 
+interface RunResizeCascadeArgs {
+  backend: SessionBackend
+  dispatch: (action: AppAction) => void
+  resizingRef: MutableRefObject<boolean>
+  resizingTimerRef: MutableRefObject<ReturnType<typeof setTimeout> | null>
+  cols: number
+  rows: number
+  layoutTrees: AppState['layoutTrees']
+  stableTabIds: string[]
+  intents: Map<string, ScrollIntent>
+  sync: boolean
+}
+
+function runResizeCascade({
+  backend,
+  cols,
+  dispatch,
+  intents,
+  layoutTrees,
+  resizingRef,
+  resizingTimerRef,
+  rows,
+  stableTabIds,
+  sync,
+}: RunResizeCascadeArgs): void {
+  dispatch({ cols, rows, type: 'set-terminal-size' })
+  resizingRef.current = true
+  if (resizingTimerRef.current) {
+    clearTimeout(resizingTimerRef.current)
+  }
+  const trees = Object.values(layoutTrees)
+  const hasSplits = trees.some((t) => t.type === 'split')
+  const options = sync ? { sync: true } : undefined
+  if (hasSplits) {
+    resizeSplitTabs(backend, layoutTrees, stableTabIds, cols, rows, intents, options)
+  } else {
+    backend.resizeAll(cols, rows, intents, options)
+  }
+  resizingTimerRef.current = setTimeout(() => {
+    resizingRef.current = false
+    resizingTimerRef.current = null
+  }, RESIZE_ACTIVITY_SETTLE_MS)
+}
+
 export function useTerminalResize({
   backend,
   contentOriginRef,
@@ -66,6 +111,8 @@ export function useTerminalResize({
   const resizingTimerRef = useRef<ReturnType<typeof setTimeout> | null>(null)
   const tabIdsRef = useRef<string[]>([])
   const intentsRef = useRef<Map<string, ScrollIntent>>(new Map())
+  const handledBySyncRef = useRef(false)
+  const sidebarMountedRef = useRef(false)
 
   const currentTabIds = state.tabs.map((t) => t.id)
   const tabIdsChanged =
@@ -82,21 +129,31 @@ export function useTerminalResize({
       .map((t) => [t.id, t.scrollIntent])
   )
 
+  const gitPaneInPaneMode = state.gitPane.mode === 'pane' && state.gitPane.visible
   const terminalSize = useMemo(() => {
     const sidebarWidth = state.sidebar.visible ? state.sidebar.width + 1 : 0
+    const sessionBarRows = state.sessionBar.visible ? 1 : 0
+    const sessionBarTopOffset =
+      state.sessionBar.visible && state.sessionBar.position === 'top' ? 1 : 0
     const reservedRows =
-      MAIN_AREA_VERTICAL_PADDING + STATUS_BAR_HEIGHT + TERMINAL_PANE_VERTICAL_CHROME
+      MAIN_AREA_VERTICAL_PADDING +
+      STATUS_BAR_HEIGHT +
+      TERMINAL_PANE_VERTICAL_CHROME +
+      sessionBarRows
+    const gitPaneRaw = gitPaneInPaneMode ? Math.round(state.gitPane.ratio * 80) : 0
+    const gitPaneWidth = gitPaneInPaneMode ? Math.max(20, Math.min(80, gitPaneRaw)) : 0
+    const gitOnLeft = gitPaneInPaneMode && state.gitPane.position === 'left'
     const cols = Math.max(
       MIN_TERMINAL_COLS,
-      Math.floor(dimensions.width - sidebarWidth - MAIN_AREA_HORIZONTAL_CHROME)
+      Math.floor(dimensions.width - sidebarWidth - gitPaneWidth - MAIN_AREA_HORIZONTAL_CHROME)
     )
     const rows = Math.max(MIN_TERMINAL_ROWS, Math.floor(dimensions.height - reservedRows))
 
     contentOriginRef.current = {
       cols,
       rows,
-      x: sidebarWidth + 1,
-      y: 1,
+      x: sidebarWidth + (gitOnLeft ? gitPaneWidth : 0) + 1,
+      y: 1 + sessionBarTopOffset,
     }
 
     return { cols, rows }
@@ -106,36 +163,59 @@ export function useTerminalResize({
     dimensions.width,
     state.sidebar.visible,
     state.sidebar.width,
+    state.sessionBar.visible,
+    state.sessionBar.position,
+    gitPaneInPaneMode,
+    state.gitPane.position,
+    state.gitPane.ratio,
   ])
 
-  useEffect(() => {
-    dispatch({
+  useLayoutEffect(() => {
+    if (!sidebarMountedRef.current) {
+      sidebarMountedRef.current = true
+      return
+    }
+    runResizeCascade({
+      backend,
       cols: terminalSize.cols,
+      dispatch,
+      intents: intentsRef.current,
+      layoutTrees: state.layoutTrees,
+      resizingRef,
+      resizingTimerRef,
       rows: terminalSize.rows,
-      type: 'set-terminal-size',
+      stableTabIds,
+      sync: true,
     })
-    resizingRef.current = true
-    if (resizingTimerRef.current) {
-      clearTimeout(resizingTimerRef.current)
-    }
-    const trees = Object.values(state.layoutTrees)
-    const hasSplits = trees.some((t) => t.type === 'split')
-    if (hasSplits) {
-      resizeSplitTabs(
-        backend,
-        state.layoutTrees,
-        stableTabIds,
-        terminalSize.cols,
-        terminalSize.rows,
-        intentsRef.current
-      )
-    } else {
-      backend.resizeAll(terminalSize.cols, terminalSize.rows, intentsRef.current)
+    handledBySyncRef.current = true
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [
+    state.sidebar.visible,
+    state.sidebar.width,
+    state.sessionBar.visible,
+    state.sessionBar.position,
+    gitPaneInPaneMode,
+    state.gitPane.position,
+    state.gitPane.ratio,
+  ])
+
+  useEffect(() => {
+    if (handledBySyncRef.current) {
+      handledBySyncRef.current = false
+      return
     }
-    resizingTimerRef.current = setTimeout(() => {
-      resizingRef.current = false
-      resizingTimerRef.current = null
-    }, RESIZE_ACTIVITY_SETTLE_MS)
+    runResizeCascade({
+      backend,
+      cols: terminalSize.cols,
+      dispatch,
+      intents: intentsRef.current,
+      layoutTrees: state.layoutTrees,
+      resizingRef,
+      resizingTimerRef,
+      rows: terminalSize.rows,
+      stableTabIds,
+      sync: false,
+    })
   }, [
     backend,
     dispatch,

package/src/app.tsx

@@ -25,6 +25,7 @@ import { useRendererBindings } from './app-runtime/use-renderer-bindings'
 import { useTerminalResize } from './app-runtime/use-terminal-resize'
 import { useWorkspaceAutosave } from './app-runtime/use-workspace-autosave'
 import { loadConfig } from './config'
+import { setActiveKeymap } from './input/keymap/keymap-ref'
 import { deriveModeId } from './input/modes/bridge'
 import { registerAllModes } from './input/modes/handlers'
 import { getHandler, transitionTo } from './input/modes/registry'
@@ -54,7 +55,10 @@ export function App({
   resolvedConfig: ResolvedConfig
 }) {
   const keymapHandlers = useMemo(
-    () => registerAllModes(resolvedConfig.keymaps),
+    () => {
+      setActiveKeymap(resolvedConfig.keymaps)
+      return registerAllModes(resolvedConfig.keymaps)
+    },
     // Registration has side effects in a global mode registry — run once per app instance.
     // eslint-disable-next-line react-hooks/exhaustive-deps
     []
@@ -73,14 +77,27 @@ export function App({
     const sessionBarVisible = resolvedConfig.sessionBar?.visible ?? json.sessionBarVisible ?? true
     const sessionBarPosition =
       resolvedConfig.sessionBar?.position ?? json.sessionBarPosition ?? 'top'
+
+    // Merge config-file gitPane (persisted prefs) with user's resolved gitPane
+    // (programmatic config). User config wins; file provides persisted prior state.
+    const userGitPane = resolvedConfig.gitPane
+    const gitPaneOverrides = {
+      ...json.gitPane,
+      ...(userGitPane?.visible !== undefined ? { visible: userGitPane.visible } : {}),
+      ...(userGitPane?.mode !== undefined ? { mode: userGitPane.mode } : {}),
+      ...(userGitPane?.position !== undefined ? { position: userGitPane.position } : {}),
+      ...(userGitPane?.ratio !== undefined ? { ratio: userGitPane.ratio } : {}),
+      ...(userGitPane?.path !== undefined ? { path: userGitPane.path } : {}),
+      ...(userGitPane?.diffCount !== undefined ? { diffCount: userGitPane.diffCount } : {}),
+    }
+
     return createInitialState(
       json.customCommands,
       loadSessionCatalog(),
       loadSnippetCatalog(),
       true,
       {
-        gitPanelRatio: json.gitPanelRatio,
-        gitPanelVisible: json.gitPanelVisible,
+        gitPane: gitPaneOverrides,
         sessionBarPosition,
         sessionBarVisible,
       }