@digital-threads/aimux

aimux

Local AI workspace orchestrator — manage multiple AI CLI subscriptions with shared knowledge and isolated authentication.

Problem

You have multiple Claude Code subscriptions (personal, work, client) each in separate ~/.claude-* directories. You maintain symlinks manually, duplicate settings, and juggle bash functions to switch between them.

Solution

aimux treats your AI CLI configs like tmux treats terminals: one shared brain, multiple isolated sessions.

• Shared layer: agents, skills, commands, rules, memory, plugins, settings — symlinked from a single source of truth
• Private layer: credentials, rate limits, session state — isolated per profile
• Zero duplication: add a skill once, available everywhere

Install

npm install -g @digital-threads/aimux

Getting Started

You have ~/.claude + extra directories (~/.claude-work, etc.)

npm install -g aimux
aimux init              # auto-detects all ~/.claude* dirs
aimux status            # verify profiles, auth, symlinks
aimux run w             # launch work profile (prefix matching)

You have only ~/.claude (one subscription)

npm install -g aimux
aimux init              # creates config with main profile
aimux profile add work  # add a new profile
aimux auth login work   # OAuth for the new account
aimux profile update w -m claude-opus-4-6
aimux run w

You want to connect a 3rd-party / self-hosted API endpoint

aimux profile add myapi --api
# Configure API endpoint (leave blank to use default):
#   Base URL:                          https://api.your-provider.com/v1
#   Auth token:                        [hidden]
#   Default model [claude-sonnet-4-6]:
#   Opus model    [claude-opus-4-6]:
#   Sonnet model  [claude-sonnet-4-6]:
#   Haiku model   [claude-haiku-4-5]:
# ✓ Credentials saved to ~/.aimux/profiles/myapi/.env (chmod 600)
aimux run myapi

See Per-profile environment variables for the declarative alternative (.env file / env: block) used by power users and CI.

Fresh machine (nothing installed)

# Install Claude CLI first, then:
claude auth login       # creates ~/.claude
npm install -g @digital-threads/aimux
aimux init
aimux profile add work
aimux auth login work

Day-to-day usage

aimux run               # interactive picker (↑↓ + Enter)
aimux run w             # prefix match → work
aimux run o -m claude-sonnet-4-6  # one-time model override
aimux run w --resume    # flags pass through to Claude CLI
aimux status            # dashboard
aimux usage             # token usage by profile for the last 7 days
aimux usage --all       # all known transcript usage

# Set default model per profile (quote model names with special chars)
aimux profile update w -m claude-opus-4-6
aimux profile update o -m "claude-opus-4-6[1m]"

# Set a fallback model, tried automatically when the primary is overloaded/unavailable
aimux profile update w --fallback-model claude-sonnet-4-6
aimux profile update w --unset-fallback-model   # remove it

Commands

Command	Description
aimux init	Auto-detect Claude dirs, create config, migrate profiles
aimux init --source <path>	Initialize with explicit source directory
aimux status	TUI dashboard — profiles, auth, auto-mode posture, symlink health
aimux usage	Show token usage by profile from Claude transcript metadata
aimux usage --profile work --since 24h	Show usage for one profile over a recent window
aimux run [profile]	Launch AI CLI with correct env and model
aimux run	Interactive picker — history pre-selects last used profile
aimux run w	Prefix matching — launches work if unambiguous
aimux run work -m claude-sonnet-4-6	Launch with model override
aimux agents	Multi-profile agent view — see and manage claude background sessions across all profiles in one TUI
aimux profile add <name>	Create new profile with symlinks
aimux profile add <name> --api	Create a 3rd-party API profile (interactive endpoint + token prompt)
aimux profile update <name>	Update model/cli settings
aimux profile update <name> --fallback-model <model>	Set a fallback model, used when the primary is overloaded/unavailable
aimux profile update <name> --unset-fallback-model	Remove the fallback model
aimux profile update <name> -e KEY=VALUE	Set an env var in the profile .env file
aimux profile update <name> --unset-env KEY	Remove an env var from the profile .env file
aimux profile list	List all profiles
aimux profile remove <name>	Remove profile and clean up
aimux profile clone <src> <name>	Clone profile with private files
aimux rebuild [profile]	Sync symlinks and surface local shared-file conflicts
aimux doctor	Health check — broken symlinks, missing shared entries, conflicts
aimux auth login <profile>	Launch OAuth flow for a profile
aimux auth status	Show auth file status per profile
aimux setup-shell	Auto-install shell completions (bash/zsh/fish)
aimux migrate isolate	One-time migration: convert per-profile jobs/, daemon/, projects/ symlinks into real private dirs so each profile gets its own supervisor and sessions. Safe — no data is deleted. Add --dry-run to preview.

All profile commands support prefix matching: aimux run w → work, aimux profile update o → own.

How It Works

~/.claude/          ← source of truth (your main profile)
  agents/
  skills/
  commands/
  memory/
  settings.json
  .credentials.json  ← private, stays here

~/.aimux/
  config.yaml        ← aimux config
  profiles/
    work/
      agents/ → ~/.claude/agents      ← symlink (shared)
      skills/ → ~/.claude/skills      ← symlink (shared)
      memory/ → ~/.claude/memory      ← symlink (shared)
      plugins/                        ← real dir (shared content, per-profile metadata)
        marketplaces/ → ~/.claude/plugins/marketplaces   ← symlink (shared)
        cache/        → ~/.claude/plugins/cache           ← symlink (shared)
        known_marketplaces.json       ← real file (paths point inside this profile)
        installed_plugins.json        ← real file (paths point inside this profile)
      .credentials.json               ← real file (private)
      .claude.json                    ← real file (private)
    own/
      ...same pattern...

When you run aimux run work, it sets CLAUDE_CONFIG_DIR=~/.aimux/profiles/work and launches the CLI. Claude sees a complete config directory — shared content via symlinks, private auth locally.

Plugins are shared too, but Claude validates that a marketplace's installLocation lives inside the active config directory. So each profile gets a real plugins/ directory: the heavy content (marketplaces/, cache/) is symlinked to the shared ~/.claude/plugins, while known_marketplaces.json and installed_plugins.json are real, path-rewritten copies. ~/.claude stays the source of truth — install or update plugins from your main profile (or with CLAUDE_CONFIG_DIR=~/.claude claude plugin …) and every profile picks them up on its next run. A plugin installed from inside a profile is merged back into the shared source automatically.

Per-profile environment variables

Some Claude Code modes (3rd-party proxies, self-hosted gateways, Bedrock, Vertex) are activated by environment variables rather than OAuth. aimux injects per-profile env into the spawned claude process (and into aimux auth login <profile>) from two sources, merged in this order:

• <profile>/.env — a dotenv file inside the profile directory. Best for secrets. Written with chmod 600 when aimux creates it; aimux run warns if it becomes group/other-readable.
• env: block under the profile in config.yaml — best for non-secret toggles you want versioned. Overrides .env on key conflict.

The fastest way to set up an API profile is the interactive prompt:

aimux profile add myapi --api      # prompts for Base URL, hidden token, models
aimux profile update myapi -e ANTHROPIC_MODEL=claude-opus-4-6   # edit later

…which writes something like:

# ~/.aimux/profiles/myapi/.env — do not commit
ANTHROPIC_BASE_URL=https://api.your-provider.com/v1
ANTHROPIC_AUTH_TOKEN=sk-your-token...
ANTHROPIC_MODEL=claude-sonnet-4-6
ANTHROPIC_DEFAULT_OPUS_MODEL=claude-opus-4-6
ANTHROPIC_DEFAULT_SONNET_MODEL=claude-sonnet-4-6
ANTHROPIC_DEFAULT_HAIKU_MODEL=claude-haiku-4-5

The .env parser supports KEY=value, export KEY=value, comments, and single/double-quoted values (with \n/\t escapes inside double quotes). It does not do ${VAR} interpolation or multi-line values — it's a secrets loader, not a full dotenv-expand. .env is always private (never symlinked to the shared source).

Config

# ~/.aimux/config.yaml
version: 1
shared_source: /home/user/.claude

profiles:
  main:
    cli: claude
    path: /home/user/.claude
    is_source: true
  work:
    cli: claude
    model: claude-opus-4-6
    path: /home/user/.aimux/profiles/work
  myapi:
    cli: claude
    model: claude-sonnet-4-6
    path: /home/user/.aimux/profiles/myapi   # secrets live in this dir's .env
    # Optional non-secret env injected into the spawned CLI (overrides .env).
    # env:
    #   ANTHROPIC_DEFAULT_OPUS_MODEL: claude-opus-4-6

private:
  - .credentials.json
  - .env                  # API credentials — never symlinked, never committed
  - .claude.json
  - policy-limits.json
  - mcp-needs-auth-cache.json
  - remote-settings.json
  - settings.local.json
  - stats-cache.json
  - statsig
  - telemetry

Requirements

• Node.js 22+
• Claude Code CLI installed

License

MIT