aimux

Run multiple Claude Code / Codex / Gemini / Antigravity subscriptions side by side: one shared brain — skills, agents, memory, settings — separate logins, and every subscription's live 5h/7d limits in a single view.

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 'opus[1m]'
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-5-5]:
#   Opus model    [claude-opus-5-5]:
#   Sonnet model  [claude-sonnet-5-5]:
#   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-5-5  # one-time model override
aimux run w --resume    # flags pass through to Claude CLI
aimux run --auto        # launch whichever subscription has the most headroom left
aimux status            # dashboard
aimux usage             # token usage by profile for the last 7 days
aimux usage --all       # all known transcript usage
aimux memory            # Claude's auto-memory for this folder: notes saved twice, notes MEMORY.md misses
aimux memory export     # copy those notes into the repo (.claude/memory), never overwriting one you changed

# Set a default model per profile. Prefer a family alias: `opus[1m]` always means the
# newest Opus, so a new release is picked up without touching aimux. A full id such
# as `claude-opus-5-5` pins that exact version until you change it. Quote names with
# brackets, or the shell will try to expand them.
aimux profile update w -m 'opus[1m]'
aimux profile update w -m claude-opus-5-5   # pin one version
aimux profile update w --unset-model        # let the CLI choose its own default

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

Switch your shell to a profile (aimux use)

aimux run launches a one-off session. If you'd rather activate a profile so plain claude / codex use it — like nvm use or pyenv shell — enable the shell integration once:

# add to ~/.zshrc or ~/.bashrc (fish: ~/.config/fish/config.fish)
eval "$(aimux shell-init)"

Then:

aimux use work     # activate 'work' in this shell (persistent until you switch)
claude             # runs under 'work', on its model — no `aimux run` needed
codex              # same; the CLI adapter sets CODEX_HOME for you
aimux use api      # switch profiles — stale ANTHROPIC_*/tokens are cleaned up
aimux use          # no name → interactive picker

Each shell is independent, so different terminals can hold different active profiles at once. The switch only exports env vars into the current shell — it never changes global state. aimux run still works for one-off launches, and it always runs the profile you name, whichever one the shell has active.

Several subscriptions side by side (aimux split)

aimux split              # one tmux pane per logged-in claude subscription, in this directory
aimux split work client  # just these two

Each pane runs a full aimux run <profile>, labelled with its profile on the pane border; a pane whose run fails stays open with its error. Closing the window ends the panes, as in any terminal — the conversations are saved, and aimux run <profile> --resume picks one up again. Inside tmux it opens a new window instead of nesting tmux, and that window is yours to keep or close. Needs tmux (sudo apt install tmux, or brew install tmux).

When a subscription runs out mid-session

Transcripts are shared, so a session can carry on under another subscription — only the login changes. When a claude session started with aimux run stops because its window is spent, aimux offers to continue it where there is the most room left:

⚠ work hit its 5-hour limit (resets 23:10).
Continue this session on personal (5h 10%, 7d 16%)? [Y/n]

Press Enter and the same session resumes there, with the flags you started it with. aimux reads the hit from the session's own transcript, so an ordinary exit costs nothing; the other subscriptions are only checked when a limit was actually reached. It works inside aimux split panes too.

Every subscription's usage inside Claude Code

A claude session started with aimux run — or in an aimux split pane — shows every subscription in a band above the prompt, the one it runs on first:

• The band. This session's own subscription updates with every reply; a window close to its limit turns red and says when it resets. The others are refreshed at most every five minutes, and only while you work: an idle session sends nothing, and all open sessions share one reading.
• A warning at 90%, naming the subscription with more room left. A model's own weekly limit (Fable's) shows once it is used and warns at 90% too.
• The end of a login. A claude.ai login now has a hard end that renewing can't move; /aimux, aimux status and the dashboard say when it is a week away, and aimux auth login <profile> once it has passed.
• One Enter to move. Once the window is spent, /exit is already in the prompt: press Enter and aimux carries the conversation over to that subscription without asking again.
• /aimux prints the whole table, each window with its reset time.

It is a Claude Code mod (Claude Code 2.1.287 or newer), loaded only into the sessions aimux starts; AIMUX_NO_MOD=1 turns it off. The same figures are available to scripts as aimux status --json.

The whole picture in the browser (aimux dashboard)

aimux dashboard

opens a page with every subscription in one place:

• Limits right now. Each subscription's 5-hour and weekly window, when it resets, and a verdict on the pace: on pace, tight (on course for 85% or more), over pace (it runs out before the reset, and the page says when) or spent. A tick on each bar marks how much of the window's time has passed, so a bar ahead of its tick is burning too fast. The page leads with one sentence — who is in trouble, or that nobody is — and three figures: who has the most room, who is closest to a limit, what resets next.
• Where the tokens went. For the last 24 hours, 7 days, 30 days or all time: cost, tokens or requests over time by subscription, a table per subscription (input, cache write, cache read, output), the models and projects that took the most, and the heaviest sessions.
• How the week has been filling. The readings of the limits are kept (~/.aimux/limits-history.jsonl, a megabyte at most), and each card draws them.

The page speaks English and Russian — it follows the browser, with a switch in the corner — and has a light and a dark theme.

aimux serves the page itself, on http://localhost:4747 and to this machine only. The address it prints works until you stop it, and the figures answer only to a page opened through it: not to another program, another user of the machine, or another web page open in the browser. It reads the transcripts on this machine — the ones aimux usage reads — and asks each provider for the limits the way aimux status does. --port <n> picks another port, --no-open prints the address without opening a browser. Dollar figures are list-price estimates, what the same tokens would cost through the API: good for comparing subscriptions, not what a subscription bills.

The same figures for an AI client (aimux mcp)

aimux mcp is a read-only MCP server over stdio. It has three tools: aimux_limits (the limits with the verdicts on the pace), aimux_usage (where the tokens went in a window) and aimux_limits_history. To add it to Claude Code:

claude mcp add aimux -- aimux mcp

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, live 5h/7d limit usage and reset times (claude + codex), auto-mode rules when any are set, symlink health. --watch [s] keeps it on screen and re-reads the limits; --json prints them for scripts; --max-age <s> reuses a reading that recent
aimux status --no-limits	Same dashboard without the rate-limit probe (offline / faster)
aimux usage	Show token usage by profile (Claude transcripts + codex rollouts), including sessions started outside aimux. A └ background line under a profile is the part its subagents and plugins' own claude runs spent
aimux usage --profile work --since 24h	Show usage for one profile over a recent window. --json prints the full report: per profile, day, model, project and the heaviest sessions
aimux memory	Claude's auto-memory notes for the current folder (shared by every profile): notes saved twice, notes MEMORY.md doesn't list, index lines pointing at nothing. --all lists every project with notes; aimux memory export [dir] copies them into the repo (default .claude/memory), leaving any file you changed there alone
aimux dashboard	Open a page in the browser: every subscription's limits and pace, and where the tokens went. --port <n>, --no-open
aimux mcp	Serve the same figures to an AI client over MCP (stdio): claude mcp add aimux -- aimux mcp
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-5-5	Launch with model override
aimux run --auto	Probe every subscription's live limits and launch the one with the most headroom (stays within the same CLI)
aimux split [profiles...]	Open several subscriptions side by side, one tmux pane each (default: every logged-in claude subscription)
aimux use [profile]	Switch the current shell to a profile (persistent) — plain claude/codex then use it. Requires eval "$(aimux shell-init)" in your rc
aimux shell-init	Print the shell function that enables aimux use (add to ~/.zshrc/~/.bashrc/fish config)
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 add <name> --cli codex	Create a profile for another AI CLI (e.g. Codex)
aimux handoff <sessionId> --to <profile>	Continue a session under another profile/CLI via summary handoff
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-model	Remove the default model, so the CLI uses its own (newest) default
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 (same table as aimux status; --no-limits skips the probe)
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.

Multiple AI CLIs (Codex, Gemini, Antigravity)

aimux isn't claude-only. A profile's cli field selects which AI CLI it runs, so you can keep claude, Codex, Gemini and Antigravity subscriptions side by side — same shared brain, isolated auth — and even hand a live conversation from one to the other when a limit hits.

aimux profile add codework --cli codex   # a Codex profile
aimux profile add gem --cli gemini       # a Gemini profile (~/.gemini)
aimux profile add ag --cli agy           # an Antigravity CLI profile (~/.gemini/antigravity-cli)
aimux auth login codework                # runs `codex login` under an isolated CODEX_HOME
aimux run codework                        # launches Codex with the right model flag
aimux agents                              # claude + codex sessions in one view (CLI-badged)

• Isolation per CLI. Each CLI gets its own config-dir env (CLAUDE_CONFIG_DIR / CODEX_HOME / GEMINI_CLI_HOME), so subscriptions never collide.
• Per-CLI source-of-truth. shared_sources maps each CLI to its source (claude → ~/.claude, codex → ~/.codex); the legacy shared_source stays as the claude alias.
• Per-CLI sharing. claude shares everything except private; Codex shares a knowledge allowlist (skills, rules, memories) and keeps auth.json / config.toml / sessions/ private; Gemini shares GEMINI.md / skills / commands / extensions / memories and keeps auth + settings.json + history private.
• Gemini specifics. Gemini has no direct config-dir override, so aimux points GEMINI_CLI_HOME at the profile's parent and the profile dir IS gemini's .gemini. Gemini resumes by per-project index (-r latest), not by session id, so cross-Gemini native resume isn't wired into the session list yet.
• Antigravity specifics. agy reads ~/.gemini/antigravity-cli from the home and has no variable to move it, so an agy profile runs with a stand-in home (HOME, or USERPROFILE on Windows): the profile's own dir. Every sync links the rest of your real home into it, so the tools the agent runs still find .gitconfig, .ssh and the rest, and skills, plugins and MCP servers in ~/.gemini/config are shared. Settings and conversations stay private. The login does only where agy keeps it in a file, as it does with no system keychain (WSL, a headless Linux). On Windows, macOS or a Linux desktop agy keeps it in the keychain (Credential Manager, Keychain, Secret Service), one for the whole user: every agy profile then shares your usual login, and signing in or out in one does it for all; aimux auth login says so when it happens. aimux auth login ag starts agy, which asks you to sign in. An agy profile can't be switched into a shell with aimux use: start it with aimux run ag.
• claude is untouched. Multi-CLI is strictly opt-in — without a non-claude profile nothing changes.

Cross-CLI handoff (limit failover)

Hit a subscription limit mid-session? Continue it under another CLI:

aimux handoff <sessionId> --to codework

The two CLIs' transcripts are mutually unreadable, so this is a summary handoff, not a native resume: aimux reads the source transcript, summarizes it with the target profile (self-contained — the target CLI does the summarizing), then launches the target seeded with that summary. Same-CLI continuation (claude↔claude, codex↔codex) still uses native resume (aimux run <profile> --resume <id>). Note: the conversation context carries over, not the model — the target continues with its own model.

Other models via a provider preset

Many providers expose an Anthropic-compatible endpoint, so they run on the claude CLI itself — just a different base URL + token. A provider profile is therefore a claude profile: it shares the full claude brain (skills, plugins, settings, memory, transcripts) and you can even --resume a claude session under it natively (same CLI, same model swap).

One command, prompts only for the token:

aimux profile add ds --provider deepseek   # fills base URL + model mapping
aimux run ds

Built-in presets: deepseek, kimi, glm, qwen, minimax, mimo. Base URLs are verified; model names drift — update with aimux profile update <name> -e ANTHROPIC_MODEL=….

For anything else (local models via Ollama/LM Studio, a proxy, Bedrock/Vertex), use the generic aimux profile add <name> --api and point ANTHROPIC_BASE_URL at it (see below). Costs shown by aimux usage are list-price estimates (Claude, codex/gpt-5, and the Anthropic-compatible providers) and will drift as prices change.

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:

1. <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.
2. 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-5-5   # 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-5-5
ANTHROPIC_DEFAULT_OPUS_MODEL=claude-opus-5-5
ANTHROPIC_DEFAULT_SONNET_MODEL=claude-sonnet-5-5
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: opus[1m]            # follows the newest Opus
    path: /home/user/.aimux/profiles/work
  myapi:
    cli: claude
    model: claude-sonnet-5-5
    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-5-5

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
  - state                 # MCP protocol verdicts, per install
  - session-env           # per-session environment
  - backups               # copies of the private .claude.json
  - remote                # Remote Control daemon + its binaries
  - security              # Agent SDK venv and logs
  - shell-snapshots
  - cache                 # fetched model catalog, per account

The defaults above are always applied — listing extra entries adds to them. Claude Code keeps growing new runtime directories, so if aimux doctor reports a conflict on one, add it here and run aimux rebuild.

Works with aimux

Third-party tools that read aimux profiles:

• Claude Code Stats: macOS menu bar app showing each Claude profile's 5h/7d limits.

Requirements

• Node.js 22+
• Claude Code CLI installed

License

MIT. The dashboard page ships the Geist and Geist Mono typefaces, © The Geist Project Authors, under the SIL Open Font License 1.1 (dashboard/fonts/).