@brimveyn/aimux-config

Typed configuration package for @brimveyn/aimux.

Use this package to author aimux.config.ts or aimux.config.js inside an aimux profile directory.

What This Package Does

@brimveyn/aimux-config provides:

• defineConfig() for typed config authoring
• the keymap builder API
• the built-in action catalog
• theme helpers and built-in theme IDs
• exported types for config, modes, state, and tooling

It does not launch the app. The aimux runtime loads and consumes the resolved config.

Install

Install it inside an aimux profile directory:

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

If you use another profile, replace default with that profile name.

Minimal Example

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

export default defineConfig({
  sessionBar: {
    position: 'top',
    visible: true,
  },

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

This example only uses surfaces that are wired into the runtime today.

Key Notation

Ambiguous prefixes are resolved after the configured timeout.

Keymap Builder

k.leader(key)
  .timeout(ms)
  .mode(id | ids[], configure)

Mode builder methods:

m.map(keys, action, description?)
  .unmap(keys)
  .group(prefix, name, configure)
  .passthrough()

Example with groups and multi-mode bindings:

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

export default defineConfig({
  keymaps: (k) =>
    k
      .mode('navigation', (m) =>
        m
          .group('<leader>t', 'tabs', (g) =>
            g
              .map('n', actions.newTab, 'New tab')
              .map('r', actions.renameTab, 'Rename tab')
              .map('x', actions.closeTab, 'Close tab')
          )
          .unmap('r')
      )
      .mode(['navigation', 'terminal-input'], (m) =>
        m.map('<C-s>', actions.snippetPicker, 'Snippet picker')
      ),
})

Important Runtime Note About the Leader Key

The shipped runtime defaults use Ctrl+W as the leader key.

The builder itself starts from <Space> internally, but the app merges user config on top of shipped defaults from @brimveyn/aimux. In practice:

• if you omit .leader(...), the shipped leader stays Ctrl+W
• if you set another leader such as <C-a>, it overrides the shipped leader
• do not rely on .leader('<Space>') to switch the runtime leader to Space

See ../../docs/guide/keymaps.md for the full explanation.

Actions

Pre-built actions include:

• tabs: nextTab, prevTab, newTab, renameTab, closeTab, restartTab
• sessions: sessionPicker, switchSessionByIndex(n) and session modal actions
• snippets: snippetPicker, snippet editor and filter actions
• themes: themePicker, previewTheme, confirmTheme, restoreTheme
• panes: splitVertical, splitHorizontal, focusPane, resizePane, closePane
• UI: toggleSidebar, toggleSessionBar, toggleGitPane, resizeGitPane(delta), setGitPaneMode(mode), setGitPanePosition(position)
• modes: enterInsert, leaveTerminalInput, closeModal, helpModal
• git: enter git mode, stage, delete or unstage, commit, push

You can also bind a custom ActionFn for dynamic behavior.

Themes

aimux themes are Shiki themes. Two house themes (aimux, dracula-at-night) ship alongside the full Shiki catalog — 67 themes total. The same Theme object powers UI colors and code highlighting.

Declare your own themes in config:

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

export default defineConfig({
  theme: 'my-neon',
  themes: {
    // Palette shortcut — patch VSCode color keys on top of a base theme.
    'my-neon': themes.define('My Neon', 'aimux', {
      'textLink.foreground': '#ff00aa',
      'terminal.ansiMagenta': '#00ffcc',
    }),
    // Or drop a full VSCode theme JSON verbatim:
    'custom': themes.full({
      name: 'custom',
      displayName: 'Custom',
      type: 'dark',
      fg: '#eee',
      bg: '#1a1a1a',
      colors: {
        /* VSCode workbench keys */
      },
      settings: [
        /* TextMate token rules */
      ],
    }),
  },
})

See ../../docs/guide/themes.md for picker shortcuts, the VSCode color key reference, and migration notes if you're coming from the old palette alias API.

Support Status

Backends Subpath

The package also exports:

@brimveyn/aimux-config/backends

Current helpers:

• claudeBackend()
• codexBackend()

These helpers are documented as stubs. Do not treat them as a fully supported runtime backend override system yet.

More Documentation

• ../../docs/reference/config-reference.md
• ../../docs/guide/keymaps.md
• ../../docs/guide/themes.md
• ../../docs/concepts/config-and-state.md
• ../../docs/concepts/profiles.md

License

MIT