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. Suddenly you’re manually copying files around, 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. No shared state, no accidental overwrites.

What it isn’t

It doesn’t fork or patch Claude Code. It doesn’t run a proxy or daemon. 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 pre-configured endpoints and model mappings
• 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

This generates a wrapper script in your PATH (the exact location depends on your package manager, could be ~/.bun/bin/, ~/.local/bin/, or similar) that you can run like any other command.

Before you start

You’ll 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

Each provider is a template: a bundle of environment variables (base URL, model mappings, default settings) merged into a new instance. You bring the API key; the template handles the rest. The full list, with endpoints and model mappings for all eight templates, lives on the providers page.

Using Anthropic directly

You don’t need a template for Anthropic, that’s Claude Code’s default. Run claude directly for Anthropic, and use claude-multi for everything else. If you still want a managed instance for Anthropic (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 faithfully implements the Anthropic messages API (the /v1/messages endpoint), Claude Code will work with it. Tools like Ollama with an Anthropic-compatible adapter, LiteLLM, or vLLM with the right proxy can bridge the gap.

The further your local setup deviates from the Anthropic API spec, the more likely you are to hit edge cases, especially around streaming, tool use, and extended thinking.

A practical note on cost

Running local models eliminates per-token API costs entirely. You pay in compute (GPU time, electricity) instead. For high-volume tasks like code generation and refactoring, this can be significantly cheaper than any cloud provider, if you have the hardware.

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 walks through instance name, provider template, API key, paths, copy options, plugin selection, and sync mode. The instance is created and you’re back at the menu.

CLI command

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

The add command takes --provider, --api-key, and a set of copy and sync flags (--copy-settings, --copy-plugins, --copy-mcp, --sync-mode). See the CLI reference for the full set.

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 they don’t interfere: separate settings, separate conversation history, separate MCP servers. You can even point two instances at the same provider if you want isolated contexts for different projects.

There’s no shared state between instances (no lock files, no central server, no port conflicts) because 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/). This is intentional, 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.

Everything else (flags, commands, keybindings) works exactly as it does normally, and Claude Code updates land immediately because you’re running the actual binary. Each 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 now has three modes (auto / half-manual / full-manual), and conversions are one-way: you can step down from auto to half-manual to full-manual, but not back up. For the full mechanism, the mode comparison, and collision detection, see the plugins and MCP guide.

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 without making you 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, same format as Claude Code’s native MCP config.

For setup details, edge cases, and the full command reference, see the plugins and MCP guide.

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

Settings files are written using a temp-file-rename pattern with JSON verification. The file gets written to a temp path, verified as valid JSON, then atomically renamed into place. No partial writes, no corrupted configs.

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 (or watch for the warning banner on the main menu), or run claude-multi list. It surfaces 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.

The most common issue is broken symlinks. Repair them across every instance:

claude-multi fix-symlinks

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

For the full set of checks, recovery steps, and how migrations roll back from .bak files, see the troubleshooting guide.

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 actually one of the reasons claude-multi exists, you can A/B providers on the same task and see which gives you the best results per dollar. Some providers like DeepSeek and MiMo are significantly cheaper per token than Anthropic. Others like Kimi or Qwen offer subscription plans with credit pools.

Check the providers page for 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 only difference is the wrapper scripts claude-multi generates for each instance. 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 generates native .cmd wrappers, so calling claude-deepseek from a bash-style shell works because the shell hands off to cmd.exe for .cmd files. If you live entirely inside WSL, you are effectively on Linux, and claude-multi will generate Unix shell wrappers there instead.

CI/CD testing

The project’s CI runs install and execution tests on all three operating systems against all three runtimes (bun, node, deno). Windows is not an afterthought, it is in the matrix on every release. If a Windows-specific regression lands, the tests catch it 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 separate things need updating, and they update independently: the claude-multi tool itself, and the Claude Code binary it wraps. Mixing them up is the most common source of “I updated but nothing changed” confusion.

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 an update to Claude Code nor an update to claude-multi 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 exactly where they were. An instance is just 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 runs a migration on launch when it detects one, and those migrations write .bak files first. If an instance looks wrong after an update, open the TUI and press ! for the health screen, or check for .bak files in ~/.claude-multi/<name>/ and restore manually. See the troubleshooting FAQ for 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