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.

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:

1. AIMUX_PROFILE
2. AIMUX_RUNTIME_PROFILE
3. 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

• docs/getting-started.md
• docs/concepts/config-and-state.md
• docs/concepts/profiles.md
• docs/guide/sessions.md
• docs/guide/keymaps.md
• docs/guide/themes.md
• docs/reference/cli.md
• docs/reference/config-reference.md
• docs/reference/runtime-paths.md
• docs/guide/git-mode.md
• docs/developer/architecture.md
• docs/developer/aimux-config-internals.md

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.

License

MIT © BrimVeyn