You have a personal Claude Code subscription and a work one. Or you freelance for two clients who each provide their own API key. Or you want a sandboxed account for experiments that won't pollute your main config.

Whatever the reason, Claude Code doesn't ship with a built-in "switch account" command. But the architecture makes it straightforward: everything lives in a single config directory, and you can redirect it.

How Claude Code stores state

Claude Code keeps all its state in ~/.claude by default. That includes:

• Authentication tokens
• Project-level settings (.claude/ inside each repo)
• Conversation history
• Memory files
• MCP server configs

The key insight: the CLAUDE_CONFIG_DIR environment variable overrides where Claude Code looks for all of this. Point it somewhere else, and you get a completely independent instance.

Basic setup: shell aliases

Create one config directory per account:

mkdir -p ~/.claude-personal
mkdir -p ~/.claude-work

Find your Claude binary path:

which claude
# e.g. /Users/you/.nvm/versions/node/v22.15.0/bin/claude

Add aliases to your ~/.zshrc (or ~/.bashrc):

alias claude-personal='CLAUDE_CONFIG_DIR=~/.claude-personal claude'
alias claude-work='CLAUDE_CONFIG_DIR=~/.claude-work claude'

Reload your shell:

source ~/.zshrc

Then authenticate each one separately:

claude-personal   # run /login inside the session
claude-work       # run /login inside the session

Each alias now opens Claude Code with its own auth, memory, and settings.

What the alias approach misses

The alias trick works, but it has gaps that will bite you in production use.

Problem 1: NVM version upgrades break absolute paths

If you hardcode the binary path in your alias (as many guides suggest), upgrading Node via NVM silently breaks it. Use just claude instead of the absolute path, and let $PATH resolve it:

# fragile
alias claude-work='CLAUDE_CONFIG_DIR=~/.claude-work /Users/you/.nvm/versions/node/v22.15.0/bin/claude'

# resilient
alias claude-work='CLAUDE_CONFIG_DIR=~/.claude-work claude'

Problem 2: project-level config leaks between accounts

Claude Code creates a .claude/ directory inside your project repo. That directory stores project settings, CLAUDE.md, and settings.json. These are shared across all your aliases because they live in the repo, not in the config dir.

This means your work account and personal account see the same project-level instructions. That's usually fine, but if you need different MCP servers or permissions per account per project, you'll need to handle it differently (see the wrapper script section below).

Problem 3: hooks and MCP servers are per-config-dir

If you've configured custom hooks or MCP servers in ~/.claude/settings.json, those won't exist in your new config directories. You'll need to copy or symlink the parts you want shared:

# share hooks across accounts
ln -s ~/.claude/settings.json ~/.claude-work/settings.json

Or, if you want different hooks per account, copy and customize:

cp ~/.claude/settings.json ~/.claude-work/settings.json

Problem 4: memory doesn't transfer

Each config directory has its own memory system. Your personal account won't remember what your work account learned. If you use memory-heavy workflows, that isolation is sometimes a feature, sometimes a problem.

Better approach: a wrapper script

Instead of simple aliases, a small wrapper gives you account switching with validation:

#!/usr/bin/env bash
# Save as ~/bin/claude-switch and chmod +x

ACCOUNT="${1:?Usage: claude-switch <account-name> [claude args...]}"
shift

CONFIG_DIR="$HOME/.claude-$ACCOUNT"

if [ ! -d "$CONFIG_DIR" ]; then
  echo "Account '$ACCOUNT' not found. Available accounts:"
  ls -d ~/.claude-* 2>/dev/null | sed 's|.*/.claude-||'
  exit 1
fi

CLAUDE_CONFIG_DIR="$CONFIG_DIR" exec claude "$@"

Usage:

claude-switch work
claude-switch personal --resume
claude-switch work -p "fix the login bug"

This passes all arguments through, so flags like --resume, --print, and -p all work.

Per-project account defaults

If a specific repo should always use a specific account, you can set it in a .envrc file (if you use direnv):

# /path/to/work-project/.envrc
export CLAUDE_CONFIG_DIR="$HOME/.claude-work"

Now every time you cd into that project and run claude, it automatically uses the work account. No alias needed.

Without direnv, you can add it to the project's shell history or a local .env file that your shell sources.

API key accounts vs OAuth accounts

There are two authentication modes in Claude Code, and they interact differently with multi-account setups:

OAuth (default): You run /login and authenticate through Anthropic's web flow. The token is stored in the config directory. This is what most people use with Claude Pro/Max subscriptions.

API key: You set ANTHROPIC_API_KEY as an environment variable. This bypasses the config directory's auth entirely.

For API key setups, you don't even need separate config directories for auth. You can just switch the key:

alias claude-client-a='ANTHROPIC_API_KEY=$CLIENT_A_KEY claude'
alias claude-client-b='ANTHROPIC_API_KEY=$CLIENT_B_KEY claude'

But you'll still want separate config directories if you need isolated memory, hooks, or MCP servers.

Combining both: API key + config isolation

The most robust setup for freelancers or consultants:

# ~/.zshrc
export CLIENT_A_KEY="sk-ant-..."  # or source from a secrets manager

alias claude-client-a='ANTHROPIC_API_KEY=$CLIENT_A_KEY CLAUDE_CONFIG_DIR=~/.claude-client-a claude'
alias claude-client-b='ANTHROPIC_API_KEY=$CLIENT_B_KEY CLAUDE_CONFIG_DIR=~/.claude-client-b claude'

Each client gets:

• Their own API key (billing goes to the right place)
• Their own memory (client context stays separate)
• Their own MCP servers (different clients, different tools)
• Their own hooks (different code review standards, different workflows)

Running accounts simultaneously

You can run multiple Claude Code instances in parallel, each in its own terminal tab. The config directories are independent, so there's no locking or conflict.

# Terminal 1
claude-work

# Terminal 2
claude-personal

Both sessions run concurrently without interference. This is useful when you're waiting on a long task in one account and want to work on something else in another.

Quick reference

Going further: multiple Claude Desktop instances

Everything above covers Claude Code (the CLI). If you also use the Claude desktop app and want two instances running side by side with different accounts, the approach is different: you need to duplicate the app itself.

On macOS, Parallels Toolbox can create an "app shortcut" that acts as a second copy of Claude. Each copy maintains its own login session, so you can run your work account in one window and your personal account in another, without logging in and out. This walkthrough shows the full setup.

The process: open Parallels Toolbox, create an app shortcut pointing to Claude, give it a distinct name (like "Claude Work"), approve it in macOS security settings, and log in with your second account. Both instances live in your dock and run independently.

This pairs well with the CLI multi-account setup: use CLAUDE_CONFIG_DIR aliases for terminal work, and Parallels app shortcuts for the desktop GUI.

What I actually use

Two config directories: ~/.claude-personal for my own projects, ~/.claude-work for client work. Direnv handles the switching per project, so I just type claude and it picks the right account. I symlink settings.json from my personal config to the work one because I want the same hooks everywhere, but memory stays separate.

The total setup took five minutes. The part that took longest was realizing I needed to re-run /login in each config directory after creating it.

Originally published on jguillaumesio.com