claude-account-switch

Multi-account profile manager for Claude Code.

한국어

Claude Code doesn't officially support multiple accounts. claude-account-switch uses the CLAUDE_CONFIG_DIR environment variable to manage separate profiles, each with its own OAuth credentials.

Quick Start

npx claude-account-switch init

The interactive wizard will guide you through creating profiles, migrating existing configs, and auto-installing shell integration for all detected shells.

  ╭──────────────────────────────────────╮
  │ Welcome to Claude Switch!            │
  │ Multi-account manager for Claude Code│
  ╰──────────────────────────────────────╯

  How many profiles do you want to set up? 2

  Profile 1 name: work
  Profile 2 name: personal

  Which profile should be active by default?
  ❯ work
    personal

  Share settings across profiles? (recommended) Yes

  Existing ~/.claude detected. Migrate to a profile?
  ❯ Yes, migrate to "work"
    Yes, migrate to "personal"
    No, skip

  ✓ Migrated ~/.claude → profile: work
  ⚠ Original ~/.claude was NOT deleted.
  ✓ Created profile: work
  ✓ Created profile: personal
  ✓ Shared settings linked
  ✓ Shell integration installed (zsh, bash)
  ✓ Active profile: work

  Next steps:
    1. Open a new terminal
    2. Run claude to authenticate your "work" profile
    3. Run cpf personal && claude to authenticate "personal"

Platform guides: macOS · Linux · Windows

Installation

# Use directly with npx (recommended)
npx claude-account-switch init

# Or install globally
npm i -g claude-account-switch

Commands

| Command | Description | |---------|-------------| | claude-account-switch init | Interactive setup wizard | | claude-account-switch add <name> | Create a new profile | | claude-account-switch remove <name> | Remove a profile | | claude-account-switch list | List all profiles | | claude-account-switch use <name> | Switch active profile | | claude-account-switch migrate [name] | Migrate existing ~/.claude data into a profile | | claude-account-switch install-shell | Install shell integration | | claude-account-switch mcp [sub] | Manage MCP servers interactively | | claude-account-switch update [opts] | Update Claude Code and refresh shell integration |

MCP Management

Manage MCP servers per-profile with claude-account-switch mcp.

Interactive TUI

claude-account-switch mcp

Use arrow keys to navigate and Space to toggle. Keys: a add · d delete · q quit.

  MCP Manager

  ↑↓ move   Space toggle   a add   d delete   q quit

  ── Shared (all profiles) ────────────────────────────────
    ● context7     stdio   npx @upstash/context7-mcp@latest
  ❯ ● figma        http    https://mcp.figma.com/mcp

  ── work ────────────────────────────────────────────────
    ● local-db     stdio   node ~/tools/db-mcp.mjs
    ○ figma        (disabled for this profile)

  ── personal ────────────────────────────────────────────
    ○ context7     (disabled for this profile)

How MCP storage works

| Scope | File | Effect | |-------|------|--------| | Shared (all profiles) | _shared/settings.json → mcpServers{} | Applied to every profile via symlink | | Profile-specific | <profile>/settings.local.json → mcpServers{} | Loaded for that profile only | | Disable a shared MCP | <profile>/settings.local.json → disabledMcpServers[] | Hides the shared MCP for that profile |

_shared/settings.json        ← mcpServers: { context7, figma }
work/settings.local.json     ← mcpServers: { local-db }
                                disabledMcpServers: ['figma']

Subcommands

| Command | Description | |---------|-------------| | mcp | Interactive TUI | | mcp add <name> --shared --type http --url <url> | Add HTTP MCP to all profiles | | mcp add <name> --profile <p> --command <cmd> | Add stdio MCP to one profile | | mcp remove <name> --shared | Remove shared MCP | | mcp remove <name> --profile <p> | Remove profile-specific MCP | | mcp disable <name> --profile <p> | Disable shared MCP for a profile | | mcp enable <name> --profile <p> | Re-enable a disabled shared MCP |

HTTP MCPs

After adding an HTTP MCP, run claude in the target profile and use /mcp to complete OAuth authentication.

Updating Claude Code

Keep Claude Code in sync without breaking the shell integration:

claude-account-switch update           # check both packages, install Claude Code after confirm
claude-account-switch update --check   # dry-run; exit 1 if updates are available (CI-friendly)
claude-account-switch update --self    # print the self-update command only
claude-account-switch update --claude-code --yes  # update Claude Code non-interactively

The command will:

• Compare installed versions against the npm registry
• Detect the package manager (npm / yarn / pnpm / bun) from the install path
• Refuse self-update when claude-account-switch is installed via npm link
• Refresh the shell integration so the new binary is picked up on the next terminal
• Skip the install on Windows if claude.exe is currently running (file lock)

  Package                          Installed   Latest    Action
  ─────────────────────────────────────────────────────────────
  claude-account-switch            1.2.2       1.2.2     up to date
  @anthropic-ai/claude-code        2.1.139     2.1.195   update via npm

  ? Update @anthropic-ai/claude-code now?   No / Yes

Shell Integration

Shell integration is auto-installed for all detected shells during init. These commands are available in your terminal:

| Command | Description | |---------|-------------| | claude | Run Claude with the active profile | | cpf <name> | Quick switch to a profile | | claude-pick | Interactive profile selector |

Supported shells:

| Shell | Platform | Config file | |-------|----------|-------------| | zsh | macOS / Linux | ~/.zshrc | | bash | macOS / Linux / Git Bash | ~/.bashrc | | fish | macOS / Linux | ~/.config/fish/config.fish | | PowerShell | Windows | $PROFILE |

How It Works

~/.claude-profiles/
├── meta.json                  ← Profile metadata + active profile
├── .shell-integration.sh      ← bash/zsh integration script
├── .shell-integration.fish    ← fish integration script
├── .shell-integration.ps1     ← PowerShell integration script
├── .picker.mjs                ← Arrow-key picker script
├── _shared/
│   ├── settings.json          ← Shared settings (original)
│   └── commands/               ← Shared custom commands
├── work/
│   ├── .claude.json           ← Work account OAuth
│   ├── settings.local.json    ← Local settings (profile-specific)
│   ├── settings.json          → ../_shared/settings.json (symlink)
│   ├── commands/              → ../_shared/commands/ (symlink)
│   ├── plugins/               ← Installed plugins
│   ├── projects/              ← Project-specific settings
│   └── plans/                 ← Saved plans
└── personal/
    ├── .claude.json           ← Personal account OAuth
    ├── settings.local.json
    ├── settings.json          → ../_shared/settings.json
    ├── commands/              → ../_shared/commands/
    ├── plugins/
    ├── projects/
    └── plans/

• Shared files (settings.json, commands/) are stored in _shared/ and linked into each profile
  • macOS/Linux: symlink
  • Windows: symlinks are attempted first; falls back to copy if Developer Mode is not enabled. Directories always use junctions.
• Profile-specific files (.claude.json, settings.local.json, plugins/, projects/, plans/) are kept independently
• Temporary files (cache/, sessions/, history.jsonl, etc.) are auto-created by Claude Code and not managed

Profile Name Rules

• Lowercase letters, numbers, and hyphens only
• Must start and end with a letter or number
• Max 30 characters
• Reserved names: _shared, default

Requirements

• Node.js 18+
• Claude Code CLI installed
• Supported platforms: macOS, Linux, Windows (native + WSL)

Zero Dependencies

claude-account-switch has no external dependencies — it uses only Node.js built-in modules for instant npx startup.

License

MIT