@brimveyn/aimux 1.4.1 → 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.1",
+  "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",
@@ -55,7 +55,9 @@
     "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.1",
@@ -71,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

@@ -129,6 +129,7 @@ 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
@@ -139,16 +140,19 @@ export function useTerminalResize({
       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,
+      x: sidebarWidth + (gitOnLeft ? gitPaneWidth : 0) + 1,
       y: 1 + sessionBarTopOffset,
     }
 
@@ -161,6 +165,9 @@ export function useTerminalResize({
     state.sidebar.width,
     state.sessionBar.visible,
     state.sessionBar.position,
+    gitPaneInPaneMode,
+    state.gitPane.position,
+    state.gitPane.ratio,
   ])
 
   useLayoutEffect(() => {
@@ -187,6 +194,9 @@ export function useTerminalResize({
     state.sidebar.width,
     state.sessionBar.visible,
     state.sessionBar.position,
+    gitPaneInPaneMode,
+    state.gitPane.position,
+    state.gitPane.ratio,
   ])
 
   useEffect(() => {

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,
       }

package/src/config.ts

@@ -9,18 +9,43 @@ import { THEME_IDS, type ThemeId } from './ui/themes'
 
 export const CONFIG_PATH = `${getProfileConfigDir()}/aimux.json`
 
+export interface PersistedGitPane {
+  visible: boolean
+  mode: 'embedded' | 'pane'
+  position: 'top' | 'bottom' | 'left' | 'right'
+  ratio: number
+}
+
 export interface AimuxConfig {
   version: 2
   customCommands: Record<string, string>
   themeId?: ThemeId
-  gitPanelVisible?: boolean
-  gitPanelRatio?: number
+  gitPane?: PersistedGitPane
   sessionBarVisible?: boolean
   sessionBarPosition?: SessionBarPosition
   workspaceSnapshot?: WorkspaceSnapshotV1
   skippedUpdateVersion?: string
 }
 
+function isPersistedGitPane(value: unknown): value is PersistedGitPane {
+  if (typeof value !== 'object' || value === null) return false
+  const v = value as Record<string, unknown>
+  const modeOk = v.mode === 'embedded' || v.mode === 'pane'
+  const positionOk =
+    v.position === 'top' ||
+    v.position === 'bottom' ||
+    v.position === 'left' ||
+    v.position === 'right'
+  const ratioOk =
+    typeof v.ratio === 'number' && Number.isFinite(v.ratio) && v.ratio > 0 && v.ratio < 1
+  const visibleOk = typeof v.visible === 'boolean'
+  if (!modeOk || !positionOk || !ratioOk || !visibleOk) return false
+  // cross-field coherence: embedded => top|bottom; pane => left|right
+  if (v.mode === 'embedded' && v.position !== 'top' && v.position !== 'bottom') return false
+  if (v.mode === 'pane' && v.position !== 'left' && v.position !== 'right') return false
+  return true
+}
+
 const DEFAULT_CONFIG: AimuxConfig = {
   customCommands: {},
   version: 2,
@@ -58,6 +83,7 @@ export function loadConfigResult(): ConfigLoadResult {
       version?: number
       customCommands?: unknown
       themeId?: unknown
+      gitPane?: unknown
       gitPanelVisible?: unknown
       gitPanelRatio?: unknown
       sessionBarVisible?: unknown
@@ -80,21 +106,32 @@ export function loadConfigResult(): ConfigLoadResult {
       issues.push('ignored invalid themeId')
     }
 
-    const validGitPanelVisible =
-      typeof parsed.gitPanelVisible === 'boolean' ? parsed.gitPanelVisible : undefined
-    if (parsed.gitPanelVisible !== undefined && validGitPanelVisible === undefined) {
-      issues.push('ignored invalid gitPanelVisible')
+    let validGitPane = isPersistedGitPane(parsed.gitPane) ? parsed.gitPane : undefined
+    if (parsed.gitPane !== undefined && validGitPane === undefined) {
+      issues.push('ignored invalid gitPane')
     }
 
-    const validGitPanelRatio =
-      typeof parsed.gitPanelRatio === 'number' &&
-      Number.isFinite(parsed.gitPanelRatio) &&
-      parsed.gitPanelRatio > 0 &&
-      parsed.gitPanelRatio < 1
-        ? parsed.gitPanelRatio
-        : undefined
-    if (parsed.gitPanelRatio !== undefined && validGitPanelRatio === undefined) {
-      issues.push('ignored invalid gitPanelRatio')
+    // Legacy migration: previous schema stored gitPanelVisible/gitPanelRatio at
+    // top level. If the new `gitPane` field is absent, synthesize it from legacy
+    // keys so users don't lose their toggle/ratio on upgrade.
+    if (validGitPane === undefined) {
+      const legacyVisible =
+        typeof parsed.gitPanelVisible === 'boolean' ? parsed.gitPanelVisible : undefined
+      const legacyRatio =
+        typeof parsed.gitPanelRatio === 'number' &&
+        Number.isFinite(parsed.gitPanelRatio) &&
+        parsed.gitPanelRatio > 0 &&
+        parsed.gitPanelRatio < 1
+          ? parsed.gitPanelRatio
+          : undefined
+      if (legacyVisible !== undefined || legacyRatio !== undefined) {
+        validGitPane = {
+          mode: 'embedded',
+          position: 'bottom',
+          ratio: legacyRatio ?? 0.5,
+          visible: legacyVisible ?? true,
+        }
+      }
     }
 
     const validSessionBarVisible =
@@ -133,8 +170,7 @@ export function loadConfigResult(): ConfigLoadResult {
     return {
       config: {
         customCommands: isCustomCommandsRecord(parsed.customCommands) ? parsed.customCommands : {},
-        gitPanelRatio: validGitPanelRatio,
-        gitPanelVisible: validGitPanelVisible,
+        gitPane: validGitPane,
         sessionBarPosition: validSessionBarPosition,
         sessionBarVisible: validSessionBarVisible,
         skippedUpdateVersion: validSkippedUpdateVersion,

package/src/input/keymap/build-handlers.ts

@@ -18,6 +18,7 @@ export function buildKeymapHandlers(config: ResolvedKeymapConfig): KeymapModeHan
       const sequence = parseKeyNotation(binding.keys, leaderChord)
       trie.insert(sequence, {
         group: binding.group,
+        repeatable: binding.repeatable,
         result: binding.result,
       })
     }

package/src/input/keymap/help-entries.ts

@@ -0,0 +1,44 @@
+import type { ModeId, ResolvedKeymapConfig } from '@brimveyn/aimux-config'
+
+import { describeBindings, type DescribedBinding } from './describe-bindings'
+
+export interface HelpEntry extends DescribedBinding {
+  mode: ModeId
+  modeLabel: string
+}
+
+export const HELP_MODE_LABELS: { modeId: ModeId; label: string }[] = [
+  { label: 'Navigation', modeId: 'navigation' },
+  { label: 'Terminal input', modeId: 'terminal-input' },
+  { label: 'Git mode', modeId: 'git-mode' },
+  { label: 'Git commit', modeId: 'modal.git-commit' },
+  { label: 'New tab', modeId: 'modal.new-tab' },
+  { label: 'New tab — command', modeId: 'modal.new-tab.command-edit' },
+  { label: 'Session picker', modeId: 'modal.session-picker' },
+  { label: 'Session picker — filter', modeId: 'modal.session-picker.filtering' },
+  { label: 'Session name', modeId: 'modal.session-name' },
+  { label: 'Create session', modeId: 'modal.create-session' },
+  { label: 'Rename tab', modeId: 'modal.rename-tab' },
+  { label: 'Snippet picker', modeId: 'modal.snippet-picker' },
+  { label: 'Snippet picker — filter', modeId: 'modal.snippet-picker.filtering' },
+  { label: 'Snippet editor', modeId: 'modal.snippet-editor' },
+  { label: 'Theme picker', modeId: 'modal.theme-picker' },
+  { label: 'Split picker', modeId: 'modal.split-picker' },
+  { label: 'Help', modeId: 'modal.help' },
+  { label: 'Help — filter', modeId: 'modal.help.filtering' },
+  { label: 'Update available', modeId: 'modal.update-available' },
+]
+
+export function collectHelpEntries(config: ResolvedKeymapConfig): HelpEntry[] {
+  const entries: HelpEntry[] = []
+  for (const { label, modeId } of HELP_MODE_LABELS) {
+    const bindings = describeBindings(config, modeId, {
+      dedupeByDescription: true,
+      withDescriptionOnly: true,
+    })
+    for (const binding of bindings) {
+      entries.push({ ...binding, mode: modeId, modeLabel: label })
+    }
+  }
+  return entries
+}