ai-profile-switch

Profile switching for Claude Code using CLAUDE_CONFIG_DIR. No runtime dependencies.

한국어 · Full guide

Formerly claude-account-switch. Installed shells move to this name on their next automatic update, and claude-account-switch remains an alias of the same command. See existing users.

Start

Use Node.js 18.19+ (18.x) or 20.10+ and your existing Claude Code installation. If Claude Code is missing, follow its official installation guide.

npx ai-profile-switch@latest init

Choose profile names (for example, work and personal), optionally copy one existing configuration, then open a new terminal. init is first-time setup; running it again only shows your existing setup.

Two commands for everyday use

Run cpf and claude at your terminal's shell prompt (% or $). If you are inside Claude's chat, enter /exit there first and wait for the terminal prompt.

1. At the terminal, run cpf to open the list, switch, add, rename, remove, or exit menu.
2. Choose with ↑/↓ and Enter. When finished, select Exit to return to the terminal without launching Claude.
3. At the terminal, run claude, choose a profile, and sign in if Claude asks.

For a direct action, use:

Replace the example names with yours. A single name always selects that profile, even cpf add, cpf rename, cpf remove, or cpf list; use cpf --list to list profiles.

With multiple profiles, interactive claude launches show a picker, starting on the active profile. In scripts, claude uses the active profile without a picker. Claude arguments, including --help and --version, pass through. Switching affects future launches; already running Claude sessions keep their profile and account.

Add another account

1. At the terminal, create the profile:

   cpf add work2
   

2. Start Claude from the terminal:

   claude
   

3. Select work2 in the picker, then sign in to the intended account when Claude asks.

Creating a profile does not switch to it or sign in for you. The cpf menu can also add a profile without memorizing the command.

Bring in your existing default account

To run the original Claude CLI without importing a profile, use command claude at a Bash/zsh terminal prompt to bypass the wrapper. It uses Claude's normal configuration; if you have set CLAUDE_CONFIG_DIR separately, that path applies.

Your normal ~/.claude configuration is not automatically imported or logged in when you create a profile. First-time init lets you select that source and the destination profile. If profiles already exist, rerunning init only shows a summary; use an explicit migration instead.

1. Enter /exit in every Claude session using the source or destination, then return to the terminal.

2. Choose a destination with cpf --list. If you need a new profile, create it with cpf add work.

3. From this repository's root in the terminal, copy into that profile and confirm the prompt:

   node bin/cli.mjs migrate work --from ~/.claude
   

4. At the terminal, run claude, select work, and sign in if requested. Replace work with your chosen profile name.

The original ~/.claude and ~/.claude.json are preserved. If existing destination data is replaced, its previous copy is also retained at the backup path printed after success. Conflicting data or detected destination changes stop migration. macOS Keychain credentials are not copied, so importing configuration does not guarantee an authenticated session. See migration details.

Fix a profile name

Close every Claude session using the profile before renaming it. For example, to correct wrok2:

cpf rename wrok2 work2

Renaming preserves the profile's history, settings, list position, and active selection. It stops if work2 already exists. The configuration path changes, so macOS may ask you to sign in again. Start a new Claude session after renaming.

Shared and per-profile items

By default only settings.json and commands are shared. Everything else belongs to one profile. Add what you want every profile to use with cpf share add.

cpf share                  # Show what is shared and whether each profile is in sync
cpf share add CLAUDE.md    # Share the active profile's CLAUDE.md with every profile
cpf share add skills       # Share personal skills, linked one by one
cpf share remove skills    # Stop sharing; each profile keeps a copy
cpf share sync             # Link items you just added to _shared

• The shared copy lives in ~/.claude-profiles/_shared/<entry> and each profile gets a link. _shared/CLAUDE.md may itself link to another file.
• The first add copies the active profile's content when _shared has none.
• Links are refreshed when claude launches a profile and when a profile is created. A profile file with different content is never replaced; you get a warning. Move or delete it, then run cpf share sync.
• Settings such as skillOverrides and enabledMcpjsonServers apply to every profile when placed in the shared settings.json. Register MCP servers and sign in per profile with claude mcp add and /mcp.

Existing users

To use changes from this source checkout, run this from the repository root, then open a new terminal:

node bin/cli.mjs install-shell

For the published npm version, use this to install, repair, or refresh the shell commands and local runtime, then open a new terminal:

npx ai-profile-switch@latest install-shell

install-shell does not add profiles or sign in. Existing shells need the refresh before their cpf function can use the new management commands. Users of 1.x also run install-shell once to enable the local runtime. The older claude-pick command remains available for selecting an active profile without launching Claude.

The shell uses ~/.claude-profiles/_runtime, so a global installation and the temporary npx cache are not needed for daily use. Node.js, npm, and Claude Code must remain available.

Interactive Claude launches check for this tool's updates once daily in the background. A verified compatible package becomes active on the next launch. Active sessions keep their existing files; account data, harness hooks, and shell profiles are not rewritten. Offline or failed downloads keep the installed version. Noninteractive launches do not update.

Set CLAUDE_SWITCH_DISABLE_AUTO_UPDATE=1 to disable automatic updates. For an immediate update to the published version, run npx ai-profile-switch@latest update; add --check to check without installing. Global npm installations are independent; the shell runtime updates itself. Previous runtime versions are retained to protect active sessions.

Full CLI reference

These commands run the source checkout from the repository root. For a released version, replace node bin/cli.mjs with npx ai-profile-switch@latest, or ai-profile-switch if globally installed.

Migration preserves the source and stops on conflicting data. Skills, agents, rules, hooks, and CLAUDE.md stay with the selected profile. macOS Keychain credentials are not copied; Claude may require login in the new profile. See migration and compatibility.

Version 2 removes the separate MCP editor and Claude installer. Use official claude mcp and Claude's update mechanism. Existing legacy MCP files remain unchanged. Automatic updates affect only this tool, never Claude Code.

Platform guides: macOS · Linux · Windows

MIT