@brimveyn/aimux 1.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 BrimVeyn
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,206 @@
+# 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.
+
+![Built with Bun](https://img.shields.io/badge/runtime-Bun-f9f1e1)
+![TypeScript](https://img.shields.io/badge/lang-TypeScript-3178c6)
+![MIT License](https://img.shields.io/badge/license-MIT-blue)
+
+![aimux demo](assets/demo.gif)
+
+## Features
+
+- **Multi-tab sessions** — Run Claude, Codex, and OpenCode in parallel with instant tab switching
+- **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
+- **Daemon mode** — Background daemon keeps sessions alive across terminal restarts
+- **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)
+
+## Install
+
+```bash
+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 background daemon
+```
+
+## Configuration
+
+aimux reads `~/.config/aimux/aimux.config.ts` at startup. Set it up with:
+
+```bash
+mkdir -p ~/.config/aimux && cd ~/.config/aimux
+bun init -y
+bun add -d @brimveyn/aimux-config
+```
+
+Then create `~/.config/aimux/aimux.config.ts`:
+
+```ts
+import { defineConfig, actions, themes } from '@brimveyn/aimux-config'
+
+export default defineConfig({
+  theme: themes.extend('tokyo-night', { accent: '#ff9e64' }),
+
+  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)),
+})
+```
+
+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     |
+| `?`                   | 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
+
+```
+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 daemon backends
+    ├── daemon/                # background session daemon
+    ├── ipc/                   # daemon protocol
+    └── input/
+        ├── modes/             # mode registry + transitions
+        ├── keymap/            # prefix trie + sequence resolver
+        └── raw-input-handler.ts
+```
+
+## Tech Stack
+
+- [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
+
+## Development
+
+```bash
+git clone https://github.com/BrimVeyn/aimux && cd aimux
+bun install
+
+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
+```
+
+## License
+
+MIT © BrimVeyn

package/package.json

@@ -0,0 +1,79 @@
+{
+  "name": "@brimveyn/aimux",
+  "version": "1.1.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",
+    "aimux",
+    "bun",
+    "claude",
+    "cli",
+    "codex",
+    "multiplexer",
+    "opencode",
+    "pty",
+    "terminal",
+    "tui"
+  ],
+  "homepage": "https://github.com/BrimVeyn/aimux#readme",
+  "bugs": {
+    "url": "https://github.com/BrimVeyn/aimux/issues"
+  },
+  "license": "MIT",
+  "author": "BrimVeyn",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/BrimVeyn/aimux.git"
+  },
+  "bin": {
+    "aimux": "src/index.tsx"
+  },
+  "workspaces": [
+    "packages/*"
+  ],
+  "files": [
+    "src",
+    "README.md",
+    "LICENSE"
+  ],
+  "type": "module",
+  "module": "src/index.tsx",
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "dev": "bun --watch src/index.tsx",
+    "start": "bun run src/index.tsx",
+    "test": "bun test",
+    "check": "tsc --noEmit",
+    "demo": "vhs assets/demo.tape",
+    "demo:sessions": "vhs assets/sessions.tape",
+    "demo:tabs": "vhs assets/tabs.tape",
+    "demo:splits": "vhs assets/splits.tape",
+    "demo:themes": "vhs assets/themes.tape",
+    "restart-daemon": "bun run src/index.tsx restart-daemon",
+    "lint": "oxlint .",
+    "format": "oxfmt --write .",
+    "format:check": "oxfmt --check .",
+    "prepare": "lefthook install"
+  },
+  "dependencies": {
+    "@brimveyn/aimux-config": "^0.1.0",
+    "@opentui/core": "^0.1.90",
+    "@opentui/react": "^0.1.90",
+    "@xterm/headless": "^6.0.0",
+    "bun-pty": "^0.4.8",
+    "react": "^19.2.4",
+    "zustand": "^5.0.12"
+  },
+  "devDependencies": {
+    "@types/bun": "latest",
+    "@types/node": "^25.5.0",
+    "@types/react": "^19.2.14",
+    "eslint-plugin-perfectionist": "^5.8.0",
+    "lefthook": "^2.1.4",
+    "oxfmt": "^0.42.0",
+    "oxlint": "^1.57.0",
+    "typescript": "^6.0.2"
+  }
+}

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

@@ -0,0 +1,135 @@
+import type { MutableRefObject } from 'react'
+
+import type { SessionBackend } from '../session-backend/types'
+import type { AppAction, LayoutState, WorkspaceSnapshotV1 } from '../state/types'
+
+import { logInputDebug } from '../debug/input-log'
+import {
+  createTerminalBounds,
+  forEachSplitPaneRect,
+  getSnapshotTrees,
+  toTerminalContentSize,
+} from '../state/layout-resize'
+
+export function resizeSnapshotPanes(
+  snapshot: WorkspaceSnapshotV1 | undefined,
+  layoutRef: MutableRefObject<LayoutState>,
+  backend: SessionBackend
+): void {
+  if (!snapshot) {
+    return
+  }
+
+  const trees = getSnapshotTrees(snapshot)
+  const bounds = createTerminalBounds(
+    layoutRef.current.terminalCols,
+    layoutRef.current.terminalRows
+  )
+  forEachSplitPaneRect(trees, bounds, (tabId, rect) => {
+    const size = toTerminalContentSize(rect)
+    backend.resizeTab(tabId, size.cols, size.rows)
+  })
+}
+
+function hydrateAttachedSession(
+  dispatch: (action: AppAction) => void,
+  sessionId: string,
+  workspaceSnapshot: WorkspaceSnapshotV1 | undefined,
+  result: Awaited<ReturnType<SessionBackend['attach']>>,
+  layoutRef: MutableRefObject<LayoutState>,
+  backend: SessionBackend
+): void {
+  if (result) {
+    dispatch({
+      activeTabId: result.activeTabId,
+      layoutTree: workspaceSnapshot?.layoutTree,
+      layoutTrees: workspaceSnapshot?.layoutTrees,
+      tabGroupMap: workspaceSnapshot?.tabGroupMap,
+      tabs: result.tabs,
+      type: 'hydrate-workspace',
+    })
+    resizeSnapshotPanes(workspaceSnapshot, layoutRef, backend)
+    return
+  }
+
+  if (!workspaceSnapshot) {
+    return
+  }
+
+  dispatch({
+    sessionId,
+    type: 'load-session',
+    workspaceSnapshot,
+  })
+  resizeSnapshotPanes(workspaceSnapshot, layoutRef, backend)
+}
+
+interface AttachCurrentSessionOptions {
+  backend: SessionBackend
+  dispatch: (action: AppAction) => void
+  currentSessionId: string
+  currentSessionWorkspaceSnapshot: Parameters<SessionBackend['attach']>[0]['workspaceSnapshot']
+  layoutRef: MutableRefObject<LayoutState>
+  attachRequestIdRef: MutableRefObject<number>
+}
+
+export function attachCurrentSession({
+  attachRequestIdRef,
+  backend,
+  currentSessionId,
+  currentSessionWorkspaceSnapshot,
+  dispatch,
+  layoutRef,
+}: AttachCurrentSessionOptions): () => void {
+  const attachRequestId = attachRequestIdRef.current + 1
+  attachRequestIdRef.current = attachRequestId
+  let cancelled = false
+
+  void backend
+    .attach({
+      cols: layoutRef.current.terminalCols,
+      rows: layoutRef.current.terminalRows,
+      sessionId: currentSessionId,
+      workspaceSnapshot: currentSessionWorkspaceSnapshot,
+    })
+    .then((result) => {
+      if (cancelled || attachRequestIdRef.current !== attachRequestId) {
+        return
+      }
+
+      logInputDebug('app.backend.attachResult', {
+        activeTabId: result?.activeTabId ?? null,
+        hasResult: !!result,
+        tabs: result?.tabs.length ?? 0,
+      })
+      hydrateAttachedSession(
+        dispatch,
+        currentSessionId,
+        currentSessionWorkspaceSnapshot,
+        result,
+        layoutRef,
+        backend
+      )
+    })
+    .catch((error) => {
+      if (cancelled || attachRequestIdRef.current !== attachRequestId) {
+        return
+      }
+
+      logInputDebug('app.backend.attachError', {
+        error: error instanceof Error ? error.message : String(error),
+      })
+      hydrateAttachedSession(
+        dispatch,
+        currentSessionId,
+        currentSessionWorkspaceSnapshot,
+        null,
+        layoutRef,
+        backend
+      )
+    })
+
+  return () => {
+    cancelled = true
+  }
+}

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

@@ -0,0 +1,78 @@
+import type { MutableRefObject } from 'react'
+
+import type { SessionBackend } from '../session-backend/types'
+import type { AppAction, TabSession, TerminalModeState } from '../state/types'
+
+import { type TabRuntimeTimeouts } from './tab-runtime-timeouts'
+
+const IDLE_ACTIVITY_TIMEOUT_MS = 2_000
+
+interface BindBackendRuntimeEventsOptions {
+  backend: SessionBackend
+  dispatch: (action: AppAction) => void
+  resizingRef: MutableRefObject<boolean>
+  timeouts: Pick<
+    TabRuntimeTimeouts,
+    | 'clearIdleTimer'
+    | 'clearStartupGrace'
+    | 'isStartupGraceActive'
+    | 'scheduleIdle'
+    | 'clearAllTimers'
+  >
+}
+
+function clearTabRuntimeState(
+  timeouts: Pick<TabRuntimeTimeouts, 'clearIdleTimer' | 'clearStartupGrace'>,
+  tabId: string
+): void {
+  timeouts.clearIdleTimer(tabId)
+  timeouts.clearStartupGrace(tabId)
+}
+
+export function bindBackendRuntimeEvents({
+  backend,
+  dispatch,
+  resizingRef,
+  timeouts,
+}: BindBackendRuntimeEventsOptions): () => void {
+  const handleRender = (
+    tabId: string,
+    viewport: TabSession['viewport'],
+    terminalModes: TerminalModeState
+  ) => {
+    if (!viewport) {
+      return
+    }
+
+    dispatch({ tabId, terminalModes, type: 'replace-tab-viewport', viewport })
+    if (timeouts.isStartupGraceActive(tabId) || resizingRef.current) {
+      return
+    }
+
+    dispatch({ activity: 'busy', tabId, type: 'set-tab-activity' })
+    timeouts.scheduleIdle(tabId, IDLE_ACTIVITY_TIMEOUT_MS)
+  }
+
+  const handleExit = (tabId: string, exitCode: number) => {
+    clearTabRuntimeState(timeouts, tabId)
+    dispatch({ exitCode, status: 'exited', tabId, type: 'set-tab-status' })
+    dispatch({ activity: undefined, tabId, type: 'set-tab-activity' })
+  }
+
+  const handleError = (tabId: string, message: string) => {
+    clearTabRuntimeState(timeouts, tabId)
+    dispatch({ message, tabId, type: 'set-tab-error' })
+  }
+
+  backend.on('render', handleRender)
+  backend.on('exit', handleExit)
+  backend.on('error', handleError)
+
+  return () => {
+    timeouts.clearAllTimers()
+    backend.off('render', handleRender)
+    backend.off('exit', handleExit)
+    backend.off('error', handleError)
+    void backend.destroy(true)
+  }
+}

package/src/app-runtime/click-selection-resolver.ts

@@ -0,0 +1,130 @@
+import type { MouseEvent as OtuiMouseEvent } from '@opentui/core'
+
+import type { TabSession } from '../state/types'
+
+import { logInputDebug } from '../debug/input-log'
+import { getLineText, getWordAtColumn } from '../input/terminal-text-extraction'
+
+interface PositionedNode {
+  id?: string
+  parent?: unknown
+  selectable?: boolean
+  x: number
+  y: number
+}
+
+export interface ClickSelectionResult {
+  selectedText: string
+  startCol: number
+  endCol: number
+  baseX: number
+  eventY: number
+  target: unknown
+}
+
+export function isPositionedNode(value: unknown): value is PositionedNode {
+  return (
+    typeof value === 'object' &&
+    value !== null &&
+    typeof Reflect.get(value, 'x') === 'number' &&
+    typeof Reflect.get(value, 'y') === 'number'
+  )
+}
+
+export function resolveClickSelection(
+  event: OtuiMouseEvent,
+  targetTabId: string,
+  tab: TabSession | undefined,
+  clickCount: number
+): ClickSelectionResult | null {
+  if (!event.target) {
+    return null
+  }
+
+  const viewportText = event.target
+  if (!isPositionedNode(viewportText)) {
+    return null
+  }
+
+  const col = event.x - viewportText.x
+  const row = event.y - viewportText.y
+  const baseX = viewportText.x
+
+  logInputDebug('click.detect', {
+    clickCount,
+    col,
+    eventX: event.x,
+    eventY: event.y,
+    row,
+    targetId: event.target.id,
+    viewportX: viewportText.x,
+    viewportY: viewportText.y,
+  })
+
+  if (!tab?.viewport?.lines[row]) {
+    logInputDebug('click.noViewportLine', {
+      hasViewport: !!tab?.viewport,
+      lineCount: tab?.viewport?.lines.length ?? 0,
+      row,
+      tabFound: !!tab,
+      targetTabId,
+    })
+    return null
+  }
+
+  const line = tab.viewport.lines[row]
+  const lineText = getLineText(line)
+
+  let selectedText: string
+  let startCol: number
+  let endCol: number
+
+  if (clickCount === 2) {
+    const word = getWordAtColumn(lineText, col)
+    if (word.text.length === 0) {
+      logInputDebug('click.emptyWord', {
+        charAtCol: lineText[col] ?? 'OOB',
+        col,
+        lineText,
+        row,
+      })
+      return null
+    }
+
+    selectedText = word.text
+    startCol = word.startCol
+    endCol = word.endCol
+  } else {
+    selectedText = lineText
+    startCol = 0
+    endCol = lineText.length
+  }
+
+  logInputDebug('click.selection', {
+    baseX,
+    clickCount,
+    endCol,
+    endX: baseX + endCol,
+    lineText,
+    selectedText,
+    spanCount: line.spans.length,
+    spanStyles: line.spans.map((span) => ({
+      bold: span.bold,
+      italic: span.italic,
+      underline: span.underline,
+    })),
+    spanTexts: line.spans.map((span) => span.text),
+    startCol,
+    startX: baseX + startCol,
+    y: event.y,
+  })
+
+  return {
+    baseX,
+    endCol,
+    eventY: event.y,
+    selectedText,
+    startCol,
+    target: event.target,
+  }
+}

package/src/app-runtime/pty-write.ts

@@ -0,0 +1,32 @@
+import type { SessionBackend } from '../session-backend/types'
+import type { TabSession } from '../state/types'
+
+import { buildPtyPastePayload } from '../input/paste'
+
+function shouldScrollViewportToBottom(tab: TabSession): boolean {
+  const viewport = tab.viewport
+  return viewport !== undefined && viewport.viewportY < viewport.baseY
+}
+
+export function writeToTab(
+  backend: SessionBackend,
+  tabId: string,
+  tab: TabSession | undefined,
+  input: string
+): void {
+  if (tab && shouldScrollViewportToBottom(tab)) {
+    backend.scrollViewportToBottom(tabId)
+  }
+
+  backend.write(tabId, input)
+}
+
+export function writePasteToTab(
+  backend: SessionBackend,
+  tabId: string,
+  tab: TabSession | undefined,
+  text: string
+): void {
+  const payload = buildPtyPastePayload(text, tab?.terminalModes.bracketedPasteMode ?? false)
+  writeToTab(backend, tabId, tab, payload)
+}

package/src/app-runtime/render-invalidation.ts

@@ -0,0 +1,20 @@
+export interface RenderableNode {
+  parent?: unknown
+  requestRender(): void
+}
+
+export function isRenderableNode(value: unknown): value is RenderableNode {
+  return (
+    typeof value === 'object' &&
+    value !== null &&
+    typeof Reflect.get(value, 'requestRender') === 'function'
+  )
+}
+
+export function requestRenderUpTree(node: unknown): void {
+  let currentNode = node
+  while (isRenderableNode(currentNode)) {
+    currentNode.requestRender()
+    currentNode = currentNode.parent
+  }
+}