Frequently asked questions.

claude-multi is a CLI that runs multiple Claude Code instances at the same time, each with its own AI provider configuration. By default, every instance gets its own config directory under ~/.claude-<name>/, so settings, history, and MCP servers stay separate. Your normal ~/.claude setup is left alone.

The problem it solves

Claude Code keeps settings, plugins, skills, and conversation history in one ~/.claude folder. That works until you want to try a second provider or keep a work setup apart from a personal one. Then you copy files by hand, swap environment variables, and hope nothing gets overwritten.

claude-multi gives each instance its own alias (claude-glm, claude-deepseek, claude-anthropic), backed by a real directory you can browse and edit. The alias is a wrapper that sets CLAUDE_CONFIG_DIR and runs the official claude binary.

What it isn’t

It doesn’t fork or patch Claude Code. It doesn’t run a proxy or daemon, and it doesn’t route between models. Each instance is a standalone Claude Code environment. claude-multi manages the config directories and wrapper scripts.

What you get

• Templates for six providers: GLM, MiniMax, DeepSeek, Xiaomi MiMo, Kimi, and Qwen. There are eight templates because MiMo and Qwen each have two plan variants.
• Plugin auto-sync through plugins/ and skills/ symlinks. Update once, and every synced instance sees it.
• MCP server management across instances.
• Health checks for broken symlinks, missing directories, and corrupted config.
• A terminal UI built with Ink and React, plus a prompts fallback.

The docs cover setup and the full command reference. For the wrapper mechanism, see how it works. Template definitions are in src/templates.ts; instance management is in src/config.ts.

Pick the package manager you use:

# bun
bun add -g claude-multi

# npm
npm install -g claude-multi

# pnpm
pnpm add -g claude-multi

Then run claude-multi to open the TUI, or create an instance directly:

claude-multi add deepseek --provider deepseek --api-key sk-your-key

--api-key is required whenever you pass --provider. Without it, the CLI exits with an error.

The CLI writes a wrapper script for each instance. On macOS and Linux the default is ~/.local/bin/claude-<name>. On Windows it goes to your package manager’s global bin directory, such as %APPDATA%\npm for npm. Pass --binary <path> if you want a different path.

Before you start

You need Claude Code installed (npm install -g @anthropic-ai/claude-code), a runtime (Bun 1+ or Node.js 22+), and an API key for at least one provider.

The getting started guide walks through the first instance. The providers page lists endpoints and model mappings. Wrapper generation lives in src/wrapper.ts.

A provider template bundles environment variables (base URL, model mappings, default settings) that claude-multi merges into a new instance. You bring the API key. There are six providers and eight templates:

• GLM
• MiniMax
• DeepSeek
• Xiaomi MiMo, with pay-as-you-go and Token Plan variants
• Kimi
• Qwen, with pay-as-you-go and Coding Plan variants

The MiMo and Qwen entries are plan variants, not separate providers. The --provider values are glm, minimax, deepseek, mimo, mimo-token, kimi, qwen, and qwen-coding. The providers page lists endpoints and model mappings for all eight.

Using Anthropic directly

You don’t need a template for Anthropic. That is Claude Code’s default. Run claude for Anthropic and use claude-multi for everything else. If you want an isolated config directory for Anthropic anyway:

claude-multi add anthropic --skip-prompts

It uses Claude Code’s default Anthropic endpoint.

Using a provider that’s not listed

Create an instance without a template and configure it yourself:

claude-multi add my-provider --skip-prompts

Then create or edit ~/.claude-my-provider/settings.json and set ANTHROPIC_BASE_URL, ANTHROPIC_MODEL, ANTHROPIC_DEFAULT_FABLE_MODEL, and ANTHROPIC_DEFAULT_HAIKU_MODEL. If the provider supports effort levels, also set CLAUDE_CODE_EFFORT_LEVEL and CLAUDE_CODE_ALWAYS_ENABLE_EFFORT=1. The configuration guide documents the settings format. Template definitions are in src/templates.ts.

Yes, if your local model server exposes an Anthropic-compatible endpoint. Claude Code speaks the Anthropic API protocol.

How to set it up

Create an instance without a template:

claude-multi add local --skip-prompts

Then create or edit ~/.claude-local/settings.json and add the env vars:

{
  "env": {
    "ANTHROPIC_BASE_URL": "http://localhost:11434",
    "ANTHROPIC_MODEL": "your-model-name",
    "ANTHROPIC_DEFAULT_FABLE_MODEL": "your-model-name",
    "ANTHROPIC_DEFAULT_HAIKU_MODEL": "your-fast-model"
  }
}

Replace the URL and model names with what your server exposes. Use the base URL for its Anthropic API. Claude Code appends /v1/messages to it. If the server supports effort levels, also set CLAUDE_CODE_EFFORT_LEVEL and CLAUDE_CODE_ALWAYS_ENABLE_EFFORT=1. Provider templates show how base URLs and model mappings are set in src/templates.ts.

What works

If your server implements the Anthropic messages API, Claude Code can use it. Ollama supports a subset of that API from v0.14.0, so it can serve Claude Code directly. LiteLLM can proxy many backends behind an Anthropic-compatible API. vLLM serves an OpenAI-compatible API, so put a translation proxy in front of it.

The further your setup drifts from the Anthropic API spec, the more edge cases you hit. Streaming and tool use usually break first.

Cost

Local models have no per-token API cost. You pay in compute: GPU time and electricity. If you already own the hardware, that can be cheaper for high-volume work such as code generation and refactoring.

Two ways: the TUI or one CLI command.

Interactive TUI

claude-multi

Pick Add new instance. The wizard asks for a name, provider template, API key, and path confirmation. Depending on the copy option, it also asks which plugins to include and which sync mode to use. When it finishes, you are back at the menu with the instance created.

CLI command

claude-multi add deepseek --provider deepseek --api-key sk-your-key

--api-key is required with --provider. The add command also takes --copy-settings, --copy-all, --copy-mcp, and one sync flag (--auto-sync, --half-manual, --manual, or --sync-mode <mode>). The CLI reference lists every option.

After creation, run claude-deepseek. The wrapper sets CLAUDE_CONFIG_DIR to ~/.claude-deepseek and launches Claude Code.

See plugin syncing for the sync modes and MCP servers for copying MCP configs.

Yes. Open two terminals and run different aliases:

# Terminal 1
claude-deepseek

# Terminal 2
claude-glm

Each instance has its own config directory, so settings, conversation history, and MCP servers stay separate. You can point two instances at the same provider if you want isolated contexts for different projects.

Instances don’t share config or conversation state, so there are no per-instance lock files or port conflicts. Each claude-<name> wrapper sets CLAUDE_CONFIG_DIR and launches the real claude binary. The how it works guide covers the wrapper and common multi-instance workflows.

If you want both instances to share plugins, enable auto-sync on each. If you want them isolated, leave sync in full-manual mode. The plugin syncing answer covers the modes.

From the CLI:

claude-multi remove deepseek

Or the alias:

claude-multi rm deepseek

From the TUI, select Remove instance and pick one.

What gets removed

The command removes the instance from the registry at ~/.claude-multi/config.json and deletes the wrapper script (for example ~/.local/bin/claude-deepseek).

It does not delete the config directory ~/.claude-deepseek/. That is deliberate. Conversation history lives there, and you might want to keep it.

Deleting the config directory

After removal, the CLI prints the exact command:

To remove config files, run: rm -rf ~/.claude-deepseek

Run it only if you do not need the history. Skip it if you might recreate the instance with the same conversation context.

Scripts and CI

--force skips the printed summary:

claude-multi remove deepseek --force

The flag does not delete the config directory either.

The troubleshooting guide covers removal when it is part of a repair. The implementation is in src/config.ts and src/wrapper.ts.

No. claude-multi doesn’t fork, patch, or modify Claude Code. Each instance is a shell wrapper that sets CLAUDE_CONFIG_DIR to an isolated directory and then runs the real claude binary. No proxy, no monkey-patching, no background process.

Flags, commands, and keybindings work as they normally do, and Claude Code updates land immediately because every instance launches the same binary. The instance directory is real, so you can cd into it, inspect it, or delete it with standard tools.

The wrapper is a short script. On macOS and Linux it starts with #!/bin/sh; on Windows it is a .cmd file. The how it works guide shows the script and the rest of the architecture.

What’s inside an instance directory

By default, every instance lives under ~/.claude-<name>/: a settings.json with provider env vars and merged settings, a .claude.json with instance-level Claude config, plugins/ and skills/ directories (symlinked or copied), and a projects/ directory holding conversation history per project.

The registry, backups, health state, and migration lock live separately in ~/.claude-multi/. They are not part of any instance’s config.

Wrapper generation is in src/wrapper.ts.

Auto-sync symlinks each instance’s plugins/ and skills/ directories to your primary ~/.claude, so you install or update a plugin once and every synced instance sees it. Toggle it per instance:

claude-multi auto-sync deepseek on
claude-multi auto-sync deepseek off

on maps to auto-sync. off maps to full-manual.

If a symlink breaks after you move ~/.claude, restore the directory if needed, then repair it with:

claude-multi fix-symlinks --all

You can select instances interactively by running claude-multi fix-symlinks with no arguments, or use Re-sync symlinks in the TUI.

Sync modes

There are three modes: auto, half-manual, and full-manual. Auto symlinks the whole plugins/ and skills/ directories. Half-manual creates real directories and symlinks individual plugins and skills, so new items installed later in ~/.claude do not appear automatically. Full-manual replaces the symlinks with real copies and leaves the instance independent.

Conversions only go one way: auto to half-manual to full-manual. You cannot move back up, because reconciling directories that have diverged can lose data. The plugins and MCP guide covers the modes and collision detection.

MCP servers let Claude Code talk to external tools such as Jira, GitHub, Slack, and databases. Each instance can have its own set. claude-multi has three commands for them:

• claude-multi mcp list: show MCP server configs across all instances
• claude-multi mcp copy <source> <target>: replace the target’s MCP server entries with the source’s
• claude-multi mcp verify: check that each server config has a command (stdio) or a URL (HTTP and SSE)

With no arguments, mcp copy asks for the source and target instances.

When you create an instance through the TUI, the Copy Options step can bring MCP configs over from your primary ~/.claude install. The CLI equivalent is --copy-mcp.

MCP configs live in each instance’s settings.json at ~/.claude-<name>/settings.json, in the same format as Claude Code’s native MCP config. If the instance has no settings.json, claude-multi writes a separate mcp.json.

The plugins and MCP guide covers setup details and edge cases. The implementation is in src/config.ts.

Your API keys stay on your machine. claude-multi has no backend and no telemetry. The tool itself does not send your key anywhere.

Where keys end up

Provider templates store the key in ~/.claude-<name>/settings.json as ANTHROPIC_AUTH_TOKEN in the env block. When you launch that instance, Claude Code reads the key from the config file. claude-multi is not involved at runtime.

Provider setup writes the key once, during instance creation. After that, the key is between you and Claude Code. It is plain text in the file, so normal file permissions are the protection. Keep backups of the instance directory private.

--api-key on the command line is convenient, but the key lands in your shell history. On a shared machine, create the instance through the TUI or edit settings.json after creation.

Atomic config writes

claude-multi writes settings files with a temp-file-rename pattern. It writes to a temp path, checks that the result parses as JSON, then renames it into place. If the write fails partway, the existing config is untouched. The implementation is in src/util/json-file.ts.

Network calls

The update check fetches version metadata from the npm registry. That is the only network request claude-multi makes itself, and it does not include your API key. claude-multi info <name> prints the instance’s config path, binary path, sync mode, version, and provider. It does not print the key.

The configuration guide documents the settings format, and instance creation is in src/config.ts.

claude-multi has a health monitor. Press ! in the TUI when the warning banner appears, or run:

claude-multi doctor check

It reports missing config directories, deleted wrapper scripts, broken symlinks, corrupted settings.json, and failed migrations, each with a suggested fix. It does not change anything unless you run claude-multi doctor fix.

Broken symlinks are a common problem. Repair them across every instance:

claude-multi fix-symlinks --all

To target specific instances:

claude-multi fix-symlinks deepseek glm

With no arguments, fix-symlinks opens a multiselect prompt. Full-manual instances have no symlinks to repair, so the command reports nothing to fix.

The troubleshooting guide covers every check, the recovery steps, and how to restore a migration backup from ~/.claude-multi/backups/. The checks are implemented in src/health.ts.

claude-multi is free. It is MIT-licensed, published on npm, and takes no cut of what you pay your provider. The only cost is what your provider charges for model access.

Where the money goes

When you run claude-deepseek, Claude Code talks to DeepSeek’s API directly. When you run claude-glm, it talks to GLM’s API directly. claude-multi configures which endpoint Claude Code uses. It does not proxy the request.

Your bill depends on the provider, the number of tokens you consume, and that provider’s pricing model (pay per token or subscription).

Comparing providers

That is one reason to use claude-multi: you can run the same task against two providers and compare cost and output. The providers page lists models and current pricing notes. DeepSeek and Xiaomi MiMo publish lower per-token list prices than Anthropic’s Opus models. GLM and Qwen also sell coding plans alongside pay-as-you-go pricing.

What about Claude Code itself?

The @anthropic-ai/claude-code package is free to install. Anthropic charges for model access, either through a subscription or API billing. The CLI is not open source; claude-multi is.

Yes. claude-multi works on Windows, macOS, and Linux. The CLI and TUI are platform-neutral, and instance creation follows the same steps. The wrapper scripts are the main difference.

What’s different on Windows

On Unix the wrappers are shell scripts that start with #!/bin/sh. On Windows they are .cmd batch files:

@echo off

set "CLAUDE_CONFIG_DIR=%USERPROFILE%\.claude-deepseek"
"C:\path\to\claude.cmd" %*

The mechanism is the same: set CLAUDE_CONFIG_DIR so Claude Code reads its config from %USERPROFILE%\.claude-deepseek, then run the unmodified claude binary. On Windows that binary is claude.cmd or claude.exe, whichever Claude Code’s installer put in your PATH. claude-multi finds it with where claude.

Installing on Windows

Use PowerShell or Command Prompt with the runtime you already have:

npm install -g claude-multi

Bun works too:

bun add -g claude-multi

After install, run claude-multi to open the TUI. Instance names become commands such as claude-deepseek.cmd, written to your package manager’s global bin directory.

The claude-multi launcher is a POSIX shell script, so Windows needs an sh on PATH. Git Bash provides one.

claude-<name> not recognized

If Windows cannot find the wrapper after you create an instance, the global bin directory is probably not on PATH. For npm it is usually %APPDATA%\npm. Check it with:

npm config get prefix

Add the returned path to your user PATH, then open a new terminal. The health check (! from the main menu, or claude-multi doctor check) also flags a missing wrapper.

Git Bash, WSL, and Cygwin

claude-multi writes native .cmd wrappers, so calling claude-deepseek from Git Bash or Cygwin still works; the shell hands off to cmd.exe for .cmd files. Inside WSL, claude-multi sees Linux and writes Unix shell wrappers instead.

CI testing

CI runs install and smoke tests on Windows, macOS, and Linux for Bun and Node.js on pull requests that touch the CLI, packaging, or the workflow file.

The cross-platform matrix is in .github/workflows/test-install.yml. Wrapper generation is in src/wrapper.ts.

Two things update independently: the claude-multi tool and the Claude Code binary it wraps.

Updating Claude Code

Claude Code is the @anthropic-ai/claude-code package. Every claude-<name> instance launches the same binary, so you only update it once. Check the installed version against npm:

claude-multi version

It prints the installed Claude Code version and the latest version on npm, and flags an update when they differ. To apply it:

claude-multi update

That upgrades the shared @anthropic-ai/claude-code package. After it finishes, every instance picks up the new binary on its next launch. You do not need to recreate an instance.

Updating claude-multi itself

claude-multi is a separate npm package. Check your own version with claude-multi --version, then update it with the package manager you used to install it:

# bun
bun update -g claude-multi

# npm
npm update -g claude-multi

# pnpm
pnpm update -g claude-multi

With bun, npm, and pnpm, update -g pulls the latest published version.

What happens to instances during updates

Nothing destructive. Neither update command edits your instance directories. The config at ~/.claude-<name>/, the settings.json, plugins, skills, and conversation history under projects/ stay in place. An instance is a config directory plus a wrapper script, and the wrapper only sets CLAUDE_CONFIG_DIR before running claude. None of that depends on a specific version.

Migrations and backups

claude-multi has its own config schema version. When the registry uses an older schema, it migrates on load and copies config.json plus each instance’s settings.json into ~/.claude-multi/backups/ first. It keeps the three most recent backups. claude-multi doctor fix applies any instance migrations that are still pending.

If an instance looks wrong after an update, press ! in the TUI for the health screen. You can also check the newest folder under ~/.claude-multi/backups/ and copy instances/<name>/settings.json back by hand. The troubleshooting guide has the full recovery flow. The version and update logic is in src/version.ts, and release history is on the changelog.