Package Exports

@brimveyn/aimux
@brimveyn/aimux/src/index.tsx

This package does not declare an exports field, so the exports above have been automatically detected and optimized by JSPM instead. If any package subpath is missing, it is recommended to post an issue to the original package (@brimveyn/aimux) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.

Readme

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, snippets, themes, and fully configurable keymaps.

aimux demo

Features

multi-workspace workflow with a dedicated workspace picker
tabs for claude, codex, opencode, and terminal
split panes with pane focus and resize shortcuts
persistent workspaces 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 for review / stage / commit / push with a split or stacked diff view and shiki-powered highlighting
git worktrees for running agents on parallel branches — create per-branch worktrees, review each against its base, and squash-move a worktree'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

Install

bun install -g @brimveyn/aimux

Requires Bun.

Quick Start

Create the default profile and install the typed config package into it:

mkdir -p ~/.config/aimux/default
cd ~/.config/aimux/default
bun init -y
bun add -d @brimveyn/aimux-config

Create ~/.config/aimux/default/aimux.config.ts:

import { defineConfig, actions } from '@brimveyn/aimux-config'

export default defineConfig({
  sessionBar: {
    initialPosition: 'top',
    initialVisible: true,
  },

  keymaps: (k) =>
    k.mode('navigation', (m) => m.map('<C-p>', actions.sessionPicker, 'Workspace picker')),
})

Typed config is startup intent, not app-managed persisted state. Fields like sessionBar.initialVisible and sessionBar.initialPosition are reapplied on every launch, so runtime UI changes for those fields do not stick while the config entry remains set.

Then start the app:

aimux

On first launch, use the workspace picker flow to create your first workspace.

For the full setup path, see docs/getting-started.md.

Core Concepts

Profiles

Profile-managed config and catalogs live under:

~/.config/aimux/<profile>/

The active profile is chosen from:

AIMUX_PROFILE
AIMUX_RUNTIME_PROFILE
default

Runtime sockets live in a separate runtime directory that depends on the active profile. See docs/concepts/profiles.md.

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 - workspace catalog and workspace snapshots
aimux-snippets.json - snippet catalog

Rule of thumb:

aimux.config.ts declares startup intent
aimux.json stores app-managed runtime preferences
runtime actions never rewrite aimux.config.ts

See docs/concepts/config-and-state.md.

Workspaces

Workspaces are the top-level user-facing concept in aimux. Internally, the runtime still uses session naming for compatibility. A workspace can have:

a name
an optional project directory
a persisted workspace snapshot
an order in the workspace bar and workspace picker

See 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.

Default Everyday Shortcuts

? - open help
i - focus terminal
Ctrl+Z - leave terminal-input mode
Ctrl+N - open new-tab modal
Ctrl+G - open workspace 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

The help modal reflects the resolved keymap, so it includes your overrides.

CLI

aimux
aimux version
aimux doctor
aimux update
aimux restart-daemon
aimux restart-terminal-manager

See docs/reference/cli.md for behavior details.

Runtime Model

aimux is split into:

the UI app
an IPC daemon
a long-lived terminal manager

This split is what allows daemon restarts and some update paths without dropping every live PTY immediately.

See docs/developer/architecture.md.

Documentation Map

Development

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

The repository dev scripts use AIMUX_PROFILE=dev, so local development does not collide with a globally installed aimux instance.

References

Pierre — diffs.com — inspiration for the git-mode diff review experience: the split / stacked layout, progressive context folding, and focusing on the first change rather than the top of the file.
shiki — syntax highlighting for the git diff view and the source of the bundled theme catalog.
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.

@brimveyn/aimux