Frequently asked questions.

claude-multi is a CLI that lets you run multiple Claude Code instances at the same time, each pointed at a different AI provider. Every instance gets its own config directory under ~/.claude-<name>/, so settings, history, and MCP servers don’t bleed into each other.

The problem it solves

Claude Code keeps everything in one ~/.claude folder: settings, plugins, skills, MCP servers, conversation history. That works fine until you want to try a second provider, or keep a work setup separate from a personal one. Then you’re copying files around by hand, swapping environment variables, and hoping nothing gets overwritten.

claude-multi gives each provider its own alias (claude-glm, claude-deepseek, claude-anthropic), each backed by a real directory you can browse and edit. Instances share no state, so nothing overwrites anything.

What it isn’t

It doesn’t fork or patch Claude Code. It doesn’t run a proxy or daemon, and it doesn’t do model routing. Each instance is a standalone Claude Code environment, claude-multi just manages the plumbing.

What you get

• 8 provider templates with the endpoints and model mappings already set
• Plugin auto-sync via symlinks (update once, all instances get it)
• MCP server management across instances
• Health monitoring that catches broken symlinks, missing dirs, corrupted config
• A terminal UI built with Ink/React, plus a fallback prompts mode

Related questions

• Is it a fork of Claude Code?: how the wrapper mechanism works
• Which providers are supported?: the full template list
• Does it cost anything?: it’s free, you just pay for API usage

More info

• /about/: design principles and how it works
• /docs/getting-started/: install and create your first instance
• /blog/inside-claude-multi-every-menu/: walkthrough of every TUI screen
• /blog/claude-code-mcp-workflow-automation/: how it fits into the Claude Code ecosystem
• src/templates.ts: where provider templates are defined
• src/config.ts: instance creation and plugin management

Pick whichever package manager you already use:

# bun
bun add -g claude-multi

# npm
npm install -g claude-multi

# pnpm
pnpm add -g claude-multi

# Deno
deno install -g npm:claude-multi

Then launch the interactive TUI:

claude-multi

Or create an instance directly:

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

That writes a wrapper script into your PATH, which you then run like any other command. Where it lands depends on your package manager: ~/.bun/bin/, ~/.local/bin/, or somewhere similar.

Before you start

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

Related questions

• How do I create a new instance?: step-by-step after install
• Which providers are supported?: pick the right one

More info

• /docs/getting-started/: full setup walkthrough
• /providers/: pick a provider
• bin/claude-multi.js: the polyglot entry point
• src/util/runtime.ts: package manager detection
• src/wrapper.ts: wrapper script generation
• claude-multi on npm

A provider template is a bundle of environment variables (base URL, model mappings, default settings) that claude-multi merges into a new instance. You bring the API key, the template does the rest. The providers page lists endpoints and model mappings for all eight templates.

Using Anthropic directly

You don’t need a template for Anthropic, that’s Claude Code’s default. Run claude for Anthropic and use claude-multi for everything else. If you want a managed instance for Anthropic anyway, to keep its config isolated, create one without a provider:

claude-multi add anthropic --skip-prompts

It connects to Anthropic’s API using Claude Code’s built-in defaults.

Using a provider that’s not listed

You can create an instance without a template and configure it manually:

claude-multi add my-provider
# Then edit ~/.claude-multi/my-provider/settings.json

Set ANTHROPIC_BASE_URL, ANTHROPIC_MODEL, and ANTHROPIC_SMALL_FAST_MODEL to match your provider’s API.

Related questions

• How do I create a new instance?: the actual setup steps
• Can I use local models like Ollama?: any Anthropic-compatible API works

More info

• /providers/: full template reference with model mappings and endpoints
• /blog/kimi-k27-three-tier-agentic-coding/: Kimi K2.7 Code benchmarks and tier mapping
• src/templates.ts: template definitions

Yes, as long as your local model server exposes an Anthropic-compatible REST endpoint. Claude Code speaks the Anthropic API protocol, so the server on the other end needs to understand that format.

How to set it up

Create an instance without a template:

claude-multi add local

Then edit ~/.claude-multi/local/settings.json and set the env vars to point at your local server:

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

Replace the URL and model names with whatever your local server exposes.

What works and what doesn’t

If your local server implements the Anthropic messages API (the /v1/messages endpoint), Claude Code will work with it. Ollama with an Anthropic-compatible adapter, LiteLLM, or vLLM behind the right proxy can bridge the gap.

The further your local setup drifts from the Anthropic API spec, the more edge cases you hit. Streaming and tool use are usually where it breaks first.

A practical note on cost

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

Related questions

• Which providers are supported?: the built-in templates
• How do I create a new instance?: the full setup walkthrough

More info

• /providers/: template reference and env var details
• src/templates.ts: see how templates set ANTHROPIC_BASE_URL and model mappings for reference

Two ways: the interactive TUI, or a single CLI command.

Interactive TUI

claude-multi

Pick Add new instance. The wizard asks for an instance name, provider template, API key, paths, copy options, plugin selection, and sync mode. When it finishes, you’re back at the menu with the instance created.

CLI command

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

The add command takes --provider, --api-key, and the copy and sync flags (--copy-settings, --copy-plugins, --copy-mcp, --sync-mode). The CLI reference lists all of them.

After that, run claude-<name> (e.g. claude-deepseek) to launch Claude Code with that provider.

Related questions

• How does plugin syncing work?: keep plugins in sync across instances
• How do I manage MCP servers?: copy MCP configs to new instances
• How do I remove an instance?: the reverse of this process

More info

• /blog/inside-claude-multi-every-menu/: detailed walkthrough of the creation wizard
• /docs/getting-started/: first instance setup
• /docs/usage/: full CLI reference and flags

Yes. Open two (or more) 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 even point two instances at the same provider if you want isolated contexts for different projects.

Instances share no state, so there are no lock files or port conflicts to worry about. Each claude-<name> command just sets CLAUDE_CONFIG_DIR and launches the real claude binary. For why that’s safe and the common multi-instance workflows, see how it works.

Related questions

• What is claude-multi?: the full overview
• Which providers are supported?: pick your models

From the CLI:

claude-multi remove deepseek

Or use the alias:

claude-multi rm deepseek

From the TUI, select Remove instance and pick which one.

What gets removed

The remove command does two things:

1. Removes the instance from claude-multi’s registry (~/.claude-multi/config.json)
2. Deletes the wrapper script (e.g. ~/.local/bin/claude-deepseek)

It does not delete the config directory (~/.claude-multi/deepseek/). That’s deliberate. Your conversation history lives there, and you might want to keep it.

Deleting the config directory

After removing the instance, you’ll see a hint:

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

Run that if you’re sure you don’t need the history. Skip it if you might want to recreate the instance later with the same conversation context.

Removing in scripts or CI

Use --force to skip the confirmation prompt:

claude-multi remove deepseek --force

Related questions

• How do I create a new instance?: recreate after removing
• How do I troubleshoot broken instances?: when removal is part of the fix

More info

• /blog/inside-claude-multi-every-menu/: Remove instance section
• src/config.ts: removeInstance() implementation
• src/wrapper.ts: removeWrapper() implementation
• src/ink/screens/RemoveInstance.tsx: TUI remove screen
• Run claude-multi and select Remove instance

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

Flags, commands, and keybindings work exactly as they do normally, and Claude Code updates land immediately because you’re running the actual binary. An instance is also a real directory you can cd into, inspect, or delete with standard tools.

For the wrapper script itself and the full architecture, see how it works.

What’s inside an instance directory

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

Related questions

• What is claude-multi?: the full overview
• How do I create a new instance?: getting started

More info

• /docs/how-it-works/: architecture overview and wrapper script
• /about/: the “wrapper, not a fork” explanation
• src/wrapper.ts: wrapper generation code

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

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

If symlinks break (you moved or deleted ~/.claude), repair them with claude-multi fix-symlinks, or use Re-sync symlinks in the TUI.

Sync has three modes (auto / half-manual / full-manual), and conversions only go one way: you can step down from auto to half-manual to full-manual, but not back up. The plugins and MCP guide has the full mechanism, the mode comparison, and how collision detection works.

Related questions

• How do I manage MCP servers?: MCP configs work independently per instance
• How do I troubleshoot broken instances?: fixing broken symlinks and more

More info

• /docs/plugins-mcp/: plugin and MCP management guide
• /blog/inside-claude-multi-every-menu/: Manage Plugins and Sync mode screens

MCP (Model Context Protocol) servers let Claude Code talk to external tools: Jira, GitHub, Slack, databases, anything you’ve wired up. Each instance can have its own set, and claude-multi manages them so you don’t have to dig through JSON:

• claude-multi mcp list: show MCP server configs across all instances
• claude-multi mcp copy: copy a server config from one instance to another (also available in the TUI under MCP servers)
• claude-multi mcp verify: check that referenced executables and paths still exist

When you create an instance through the TUI, the Copy Options step can bring MCP configs over from your primary ~/.claude install. Configs live in each instance’s settings.json at ~/.claude-multi/<name>/settings.json, in the same format as Claude Code’s native MCP config.

The plugins and MCP guide covers setup details, edge cases, and the full command reference.

Related questions

• How does plugin syncing work?: symlinks, auto-sync, and collision detection

More info

• /docs/plugins-mcp/: plugin and MCP guide
• /blog/claude-code-mcp-workflow-automation/: what MCP buys you in practice
• src/config.ts: copyMcpServersFromDefault(), copyMcpServersBetweenInstances(), listMcpServers()

Your API keys stay on your machine. claude-multi has no backend, no telemetry, and makes no network calls during normal operation.

Where keys end up

Each instance stores its key in ~/.claude-multi/<name>/settings.json as part of the ANTHROPIC_AUTH_TOKEN env var. When you launch that instance, Claude Code reads the key directly from the config file, claude-multi isn’t involved at runtime.

The only time claude-multi touches your key is during instance creation, when it writes it into the settings file. After that, it’s between you and Claude Code.

About those config writes

claude-multi writes settings files with a temp-file-rename pattern. It writes to a temp path, checks the result parses as valid JSON, then renames it into place. If the write fails partway, your existing config is untouched.

Practical tips

• If you use the same key across providers, you can copy settings from ~/.claude during instance creation instead of re-entering it
• For different keys per provider, enter them individually during setup or edit the settings file directly
• Run claude-multi info <name> to see what’s stored for any instance
• The version subcommand checks npm for updates, but that’s the only network call claude-multi ever makes, and it doesn’t involve your API key

Related questions

• What is claude-multi?: the “no telemetry” overview

More info

• /privacy/: data collection policy (website only, the CLI collects nothing)
• /about/: “no daemons, no background services, no telemetry”
• /docs/configuration/: settings.json schema
• src/util/json-file.ts: atomic write implementation
• src/config.ts: how settings are created and stored

claude-multi has a health monitor. Press ! in the TUI, watch for the warning banner on the main menu, or run claude-multi list. It reports missing config directories, deleted wrapper scripts, broken symlinks, corrupted settings.json, and failed migrations, each with a suggested fix. It won’t change anything without asking.

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

claude-multi fix-symlinks

You can also target specific instances: claude-multi fix-symlinks deepseek glm.

The troubleshooting guide covers every check, the recovery steps, and how migrations roll back from .bak files.

Related questions

• How does plugin syncing work?: understanding symlinks and auto-sync
• How do I create a new instance?: recreating a corrupted instance

More info

• /docs/troubleshooting/: full troubleshooting guide
• /blog/inside-claude-multi-every-menu/: health warnings and fix-symlinks sections
• src/health.ts: health check implementation

claude-multi is free. It’s MIT-licensed, published on npm, and takes no commission or cut from your API usage. The only cost is what your provider charges you for tokens.

Where the money goes

When you run claude-deepseek, you’re hitting DeepSeek’s API directly. When you run claude-glm, you’re hitting GLM’s API directly. claude-multi doesn’t sit in the middle, it just configures which endpoint Claude Code talks to.

So your bill depends on:

• Which provider you’re using
• How many tokens you consume
• That provider’s pricing model (pay-per-token vs. subscription)

Comparing providers

That’s one of the reasons claude-multi exists. You can run the same task against two providers and see which gives you better results per dollar. DeepSeek and MiMo are cheaper per token than Anthropic. GLM and Qwen sell subscription plans with credit pools instead.

The providers page has the full list with model details.

What about Claude Code itself?

Claude Code (the @anthropic-ai/claude-code package) is also free. It’s Anthropic’s open-source CLI. You pay for API access, not the tool.

More info

• /providers/: full provider comparison
• /blog/llm-cost-optimization-routing/: cost optimization with LLM routing

Yes. claude-multi works on Windows, macOS, and Linux. The CLI commands, the TUI, plugin and MCP management, and instance creation all behave the same across the three platforms.

What’s different on Windows

The wrapper scripts are the only difference. On Unix they are plain shell scripts starting with #!/bin/sh. On Windows they are .cmd batch files that do the same job:

@echo off
REM Claude Multi - Wrapper for deepseek
set "CLAUDE_CONFIG_DIR=%USERPROFILE%\.claude-multi\deepseek"
"C:\path\to\claude.exe" %*

The mechanism is identical: set CLAUDE_CONFIG_DIR so Claude Code reads its config from the instance directory, then run the unmodified claude binary. On Windows that binary is claude.cmd or claude.exe, whichever Claude Code’s installer placed in your PATH. claude-multi finds it the same way your terminal does.

Installing on Windows

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

npm install -g claude-multi

If you use Bun for Windows or Deno, those work too:

bun add -g claude-multi
deno install -g -A -n claude-multi npm:claude-multi

After install, run claude-multi to open the TUI. The instance names you pick become commands like claude-deepseek.cmd, written to the global bin directory your package manager manages.

claude-<name> not recognized

If Windows can’t find the wrapper after you create an instance, the package manager’s global bin directory is probably not on your PATH. For npm that directory is usually %APPDATA%\npm. Check it with:

npm config get prefix

Make sure the returned path is in your user PATH environment variable, then open a new terminal. The health check (! from the main menu, or claude-multi list) will also flag a missing wrapper and tell you what’s wrong.

A note on line endings and shells

Git Bash, WSL, and Cygwin are common on Windows. claude-multi writes native .cmd wrappers, so calling claude-deepseek from a bash-style shell still works: the shell hands off to cmd.exe for .cmd files. If you live entirely inside WSL, you are on Linux as far as claude-multi is concerned, and it writes Unix shell wrappers there instead.

CI/CD testing

CI runs install and execution tests on all three operating systems against all three runtimes (bun, node, deno) on every release, so a Windows-specific regression gets caught before publish.

More info

• .github/workflows/test-install.yml: cross-platform test matrix
• src/wrapper.ts: generateWindowsWrapperScript() implementation
• src/util/runtime.ts: platform-aware package manager detection

Two things update independently: the claude-multi tool, and the Claude Code binary it wraps. Mixing them up is the usual reason people say “I updated but nothing changed”.

Updating Claude Code

Claude Code is the @anthropic-ai/claude-code package. Every claude-<name> instance launches the same shared binary, so you only update it once. Check what you have versus what’s published:

claude-multi version

This prints three things: the version of claude-multi you are running, the installed version of Claude Code, and the latest Claude Code available on npm, with a flag if an update is pending. To apply it:

claude-multi update

That runs the upgrade for 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 or touch any instance.

Updating claude-multi itself

claude-multi is a separate npm package. Update it with whatever you installed it with:

# bun
bun update -g claude-multi

# npm
npm update -g claude-multi

# pnpm
pnpm update -g claude-multi

# Deno
deno install -g -A -n claude-multi npm:claude-multi

Deno’s install command reinstalls, which is how you get the new version under Deno. With bun, npm, and pnpm, the update -g flag pulls the latest.

What happens to instances during updates

Nothing destructive. Neither update touches your instance directories. The config at ~/.claude-multi/<name>/, the settings.json, the plugins, the skills, and the conversation history under projects/ all stay where they were. An instance is a config directory plus a wrapper script, and the wrapper only sets CLAUDE_CONFIG_DIR before exec’ing claude. None of that depends on a specific version.

After a major Claude Code release

Occasionally Claude Code ships a breaking change to its config schema. claude-multi detects that on launch and runs a migration, writing a .bak file first. If an instance looks wrong after an update, open the TUI and press ! for the health screen, or look for .bak files in ~/.claude-multi/<name>/ and restore one by hand. The troubleshooting FAQ has the full recovery flow.

More info

• src/version.ts: checkForUpdates() and updateClaudeCode() implementation
• /changelog/: release history
• claude-multi on npm: check the latest published version