claude-code-profiles

# claude-profile

> Manage multiple Claude Code configuration profiles. Switch between work, personal, and project-specific setups with transparent profile resolution.

claude-profile is a free, open-source shell tool that wraps the `claude` CLI binary with a transparent function. It automatically sets `CLAUDE_CONFIG_DIR` to your active profile directory before each invocation, so you never need to think about profiles during normal use. Like nvm for Node.js or pyenv for Python, but for Claude Code configuration.

Each profile is a complete, isolated Claude Code configuration directory containing settings.json, .credentials.json, MCP server configs, CLAUDE.md, plugins, and history.

License: MIT
Repository: https://github.com/quinnjr/claude-code-profiles
Website: https://quinnjr.github.io/claude-code-profiles/

## Install

**Linux / macOS / WSL:**

```
curl -fsSL https://raw.githubusercontent.com/quinnjr/claude-code-profiles/main/install.sh | sh
```

**Windows (PowerShell):**

```
irm https://raw.githubusercontent.com/quinnjr/claude-code-profiles/main/install.ps1 | iex
```

The installer downloads the appropriate scripts and configures your shell. Restart your shell (or open a new terminal) after installing.

## Quick Start

```
# Create profiles
claude-profile create work
claude-profile create personal

# Set a default
claude-profile default work

# Just use claude — it automatically uses your default profile
claude
claude --resume
claude -p "explain this code"
```

## Commands

| Command | Description |
|---------|-------------|
| `claude-profile` | Show current profile status |
| `claude-profile use <name>` | Switch to a profile for this session |
| `claude-profile create <name>` | Create a new profile |
| `claude-profile list` | List all profiles |
| `claude-profile default [name]` | Get or set the default profile |
| `claude-profile local [name]` | Show, set, or `--remove` this directory's `.claude-profile` |
| `claude-profile auto [on\|off\|status]` | Control directory-local auto-switching (not on cmd.exe) |
| `claude-profile delete <name>` | Delete a profile (with confirmation) |
| `claude-profile which [name]` | Show the config directory path |
| `claude-profile help` | Show help |

## How It Works

Claude Code supports a `CLAUDE_CONFIG_DIR` environment variable that redirects where it stores configuration and data. claude-profile provides a `claude()` shell function that wraps the real `claude` binary:

1. On each directory change, the nearest `.claude-profile` file (if any) sets `CLAUDE_CONFIG_DIR`.
2. Before each invocation, the wrapper checks if a default profile exists and auto-sets `CLAUDE_CONFIG_DIR`.
3. If `CLAUDE_CONFIG_DIR` is already set (e.g., via `claude-profile use`), it is used as-is.
4. The real `claude` binary is then called with all your arguments.

This means you never need to think about profiles during normal use — just run `claude` as you always have.

### Session Override

To temporarily use a different profile in the current shell session:

```
claude-profile use personal
claude                          # uses "personal" for this shell session
```

The override lasts until you close the shell or run `claude-profile use` again.

### Per-Directory Profiles

A directory can pin itself (and everything under it) to a profile by holding a `.claude-profile` file whose first non-empty, non-comment line is a profile name:

```
cd ~/work/acme
claude-profile local work        # writes ./.claude-profile containing "work"
```

Your shell then switches to `work` whenever you `cd` into that tree, and back to the default when you leave. The file is plain text, so it can be committed to a repo; blank lines and `#` comments are ignored.

An explicit `claude-profile use <name>` pins the session and wins over any `.claude-profile` until `claude-profile auto on`. `claude-profile auto off` disables auto-switching for the session, and `claude-profile auto status` shows what is in effect. Set `CLAUDE_PROFILE_NO_AUTO_SWITCH=1` to disable it entirely, or `CLAUDE_PROFILE_AUTO_QUIET=1` to switch silently.

Hooking into directory changes is per-shell: zsh uses `chpwd`, bash uses `PROMPT_COMMAND`, and other POSIX shells get a `cd` wrapper. PowerShell 6+ uses `LocationChangedAction`; Windows PowerShell 5.1 hooks the `prompt` function. cmd.exe has neither a `cd` hook nor a transparent `claude` wrapper, so it cannot switch automatically — instead a bare `call claude-profile.cmd` prefers the nearest `.claude-profile` over the default profile.

### Profile Storage

Profiles are stored in platform-appropriate locations:

| Platform | Location |
|----------|----------|
| Linux | `$XDG_DATA_HOME/claude-profiles/` (default: `~/.local/share/claude-profiles/`) |
| macOS | `$XDG_DATA_HOME/claude-profiles/` (default: `~/.local/share/claude-profiles/`) |
| Windows | `%LOCALAPPDATA%\claude-profiles\` |

Each profile directory is a complete Claude Code config directory. After creating a profile and launching Claude with it, Claude will populate it with `settings.json`, `.credentials.json`, and everything else it needs.

### Profile Names

Profile names can contain letters, digits, hyphens, and underscores. Examples: `work`, `personal`, `client-acme`, `side_project`.

## Platform Support

| Script | Platform | Shell |
|--------|----------|-------|
| `claude-profile.sh` | Linux, macOS, WSL | bash, zsh (sourced) |
| `claude-profile-init.ps1` | Windows, Linux, macOS | PowerShell 5.1+ / pwsh 6+ (dot-sourced) |
| `claude-profile.cmd` | Windows | cmd.exe (use with `call` prefix) |

## Architecture

All three scripts implement the same command interface (`create`, `list`, `default`, `which`, `use`, `delete`, `help`) with platform-appropriate idioms:

- **claude-profile.sh** (POSIX sh) — reference implementation. Strict POSIX only: no `local`, no `[[ ]]`, no arrays, no bashisms. Uses `printf` over `echo`, underscore-prefixed variables (`_cp_name`) instead of `local`, `command claude "$@"` to call the real binary past the function.
- **claude-profile-init.ps1** (PowerShell 5.1+/pwsh 6+) — cross-platform. Uses `$args` manual parsing (not `param()`) to avoid conflicts with PowerShell parameter binding. `Get-Command claude -CommandType Application` to find the real binary past the function.
- **claude-profile.cmd** (Windows batch) — uses `goto :label` dispatch, `setlocal enabledelayedexpansion`, `endlocal & set` idiom to pass variables across scope boundaries. Sets `CLAUDE_CONFIG_DIR` without launching claude (user runs claude separately).

Profile data lives at `$XDG_DATA_HOME/claude-profiles/` (Linux/macOS, default `~/.local/share/claude-profiles/`) or `%LOCALAPPDATA%\claude-profiles\` (Windows). A `.default` file stores the default profile name as plain text.

### Validation Rules

Profile names must match `[A-Za-z0-9_-]+`. Reject: empty, starts with `.`, contains `/` or `\` or `..`. This prevents path traversal — all three scripts enforce this identically.

## Manual Install

**Linux / macOS:**

```
# Download
mkdir -p "${XDG_DATA_HOME:-$HOME/.local/share}/claude-profile"
curl -fsSL https://raw.githubusercontent.com/quinnjr/claude-code-profiles/main/claude-profile.sh \
  -o "${XDG_DATA_HOME:-$HOME/.local/share}/claude-profile/claude-profile.sh"

# Add to shell profile (.bashrc or .zshrc)
echo '. "${XDG_DATA_HOME:-$HOME/.local/share}/claude-profile/claude-profile.sh"' >> ~/.bashrc
```

**Windows (PowerShell):**

```
$dir = "$env:LOCALAPPDATA\claude-profile"
New-Item -ItemType Directory -Force -Path $dir | Out-Null
Invoke-WebRequest -Uri "https://raw.githubusercontent.com/quinnjr/claude-code-profiles/main/claude-profile-init.ps1" -OutFile "$dir\claude-profile-init.ps1"
Invoke-WebRequest -Uri "https://raw.githubusercontent.com/quinnjr/claude-code-profiles/main/claude-profile.cmd" -OutFile "$dir\claude-profile.cmd"
# Add to PowerShell profile
Add-Content -Path $PROFILE -Value ". '$dir\claude-profile-init.ps1'"
# Add to PATH for cmd.exe
$path = [Environment]::GetEnvironmentVariable('Path', 'User')
if ($path -notlike "*$dir*") { [Environment]::SetEnvironmentVariable('Path', "$path;$dir", 'User') }
```

## FAQ

**What is claude-profile?**
claude-profile is a free, open-source tool that lets you manage multiple Claude Code configuration profiles. Each profile is a complete, isolated Claude Code configuration directory containing settings, credentials, MCP servers, history, and CLAUDE.md. It works like nvm for Node.js or pyenv for Python — transparently resolving your active profile when you run the claude command.

**How do I install claude-profile?**
On Linux, macOS, or WSL, run: `curl -fsSL https://raw.githubusercontent.com/quinnjr/claude-code-profiles/main/install.sh | sh`. On Windows PowerShell, run: `irm https://raw.githubusercontent.com/quinnjr/claude-code-profiles/main/install.ps1 | iex`. Then restart your shell.

**What shells does claude-profile support?**
claude-profile supports bash, zsh, PowerShell 5.1+, PowerShell Core (pwsh) 6+, and Windows cmd.exe. On Unix shells it works via sourceable shell functions. On Windows it provides both a PowerShell module and a cmd.exe batch script.

**How does claude-profile work?**
claude-profile provides a transparent `claude()` shell function wrapper. Before each invocation, the wrapper checks if a default profile is set and automatically sets the `CLAUDE_CONFIG_DIR` environment variable. If `CLAUDE_CONFIG_DIR` is already set (e.g., via `claude-profile use`), it passes through without overriding. The real `claude` binary is then called with all your arguments.

**Can I switch Claude Code profiles temporarily?**
Yes. Run `claude-profile use <name>` to switch to a different profile for the current shell session only. This overrides the default without changing it. The override lasts until you close the shell or run `claude-profile use` again.

**Where are Claude Code profiles stored?**
On Linux and macOS, profiles are stored at `$XDG_DATA_HOME/claude-profiles/` (default: `~/.local/share/claude-profiles/`). On Windows, profiles are stored at `%LOCALAPPDATA%\claude-profiles\`. Each profile directory is a complete Claude Code configuration directory.

**What is CLAUDE_CONFIG_DIR?**
`CLAUDE_CONFIG_DIR` is an environment variable supported by Claude Code that redirects where it stores configuration and data. claude-profile manages this variable automatically, setting it to point to your active profile directory before each `claude` invocation.