Start
Getting started
Requirements
- macOS or Linux; on Windows, WSL 2
- Python 3.9 or later (the one that ships with macOS works)
- pipx, uv or Homebrew
- Claude Code, or let cc-profiles install it for you (see Health and About)
Install
curl -fsSL https://raw.githubusercontent.com/andreaiannarone/cc-profiles/main/install.sh | sh
The script installs cc-profiles with pipx or uv, whichever you have, or with Homebrew when you have neither (uv and Homebrew bring their own Python; pipx needs Python 3.9 or later). With none of the three, as on a new Mac, it first installs uv with uv’s official installer, in ~/.local/bin, and installs cc-profiles with it; nothing else is needed, not even Python or Apple’s developer tools. Then it adds the /cc-profiles command to Claude Code (see Open it from Claude Code) and, on macOS, the Mac app.
Run it again to update. It updates with the tool that installed cc-profiles, so you never end up with two copies, rebuilds an environment broken by a Python update, and restarts cc-profiles if it is running (then reload the page). It never uses sudo, and refuses to run under it. With uv it installs cc-profiles on uv’s own Python, which no Homebrew update can remove (set UV_PYTHON to choose another). At the end it says how to open cc-profiles, how to install Claude Code if it is missing, and warns when your terminal would run another copy of cc-profiles found first in your PATH. The whole script runs only once it has been downloaded entirely.
| Option | Effect |
|---|---|
--no-command |
do not add /cc-profiles, and do not let cc-profiles add it later |
--no-app |
macOS: do not add the Mac app |
Add them at the end: curl -fsSL …/install.sh | sh -s -- --no-app.
Or install it by hand:
pipx install cc-profiles
# or
uv tool install cc-profiles
Both put a cc-profiles command in ~/.local/bin, in an isolated environment, so nothing else on your system is affected.
With Homebrew, on macOS or Linux:
brew install andreaiannarone/cc-profiles/cc-profiles
Homebrew gets each new version shortly after it is on PyPI. To try it once without installing:
uvx cc-profiles
Windows (WSL)
Claude Code runs on Windows inside WSL 2, and so does cc-profiles: open your WSL terminal, in the same Linux distribution where you use Claude Code, and install it with the commands above. Its profiles are the ones in your Linux home (~/.claude), as Claude Code sees them.
The app still opens in your Windows browser: cc-profiles uses wslview when it is installed (package wslu), or else Windows’ own start. WSL 2 forwards 127.0.0.1 to Windows, so the address works as it is. WSL support is new: if something does not work, report it.
First run
cc-profiles
The server starts on http://127.0.0.1:4777 and your browser opens on it. Stop it with ctrl+C. If cc-profiles is already running, for example started by /cc-profiles, the command only opens your browser on it.
On the very first run, cc-profiles writes ~/.cc-profiles/config.json with:
- profiles:
~/.claude(called Default, commandclaude) plus every~/.claude-<id>folder that looks like a Claude Code profile, meaning it containssettings.json,projects,history.jsonl,.claude.jsonorskills. Empty folders and symlinks are ignored. - rules: only the defaults that mark your home folder and temporary folders as shared (see Concepts).
Rename profiles from the Profiles tab. The first profile in the list is the source profile.
On macOS, cc-profiles also adds itself to Applications, the first time it starts, as an app with its own window: see Mac app.
Open it from Claude Code
Type /cc-profiles in any Claude Code session. It runs cc-profiles open, which starts the server in the background if it is not running yet, opens your browser and returns, so the session goes on.
| In Claude Code | Runs | Does |
|---|---|---|
/cc-profiles |
cc-profiles open |
starts the server if needed and opens the browser, or the Mac app when it is installed |
/cc-profiles restart |
cc-profiles open restart |
stops the server and starts it again, e.g. after an update; then reload the page |
/cc-profiles stop |
cc-profiles open stop |
stops the server |
From a terminal, cc-profiles restart and cc-profiles stop do the same.
You do not need to add the command yourself. The install script adds it at once; with pipx, uv, pip or Homebrew, start cc-profiles once (with plain pip --user, whose folder is often not in PATH: python3 -m cc_profiles), and it writes commands/cc-profiles.md in every profile. The command calls cc-profiles by its full path, such as ~/.local/bin/cc-profiles or /opt/homebrew/bin/cc-profiles, so it works even when Claude Code was started from a terminal whose PATH does not have it. It skips profiles that share commands with the source profile (they get it through the link) and never overwrites a cc-profiles.md it did not create. After an update, it rewrites the copies it wrote, so /cc-profiles always matches the app; a copy you delete stays deleted. Profiles you create from the app get it too. Each of these changes has a backup you can restore from the Backups tab. Sessions that are already open see the command after a restart.
| Command | Does |
|---|---|
cc-profiles install-command |
adds the command again, also where you deleted it |
cc-profiles install-command --off |
stops adding and updating it; the copies already written stay (remove them). The install script’s --no-command does the same |
As a plugin
The repository is also a Claude Code plugin marketplace. Install the plugin once:
/plugin marketplace add andreaiannarone/cc-profiles
/plugin install cc-profiles@cc-profiles
The plugin’s command is /cc-profiles:open, because Claude Code always prefixes plugin commands with the plugin’s name; it does the same as /cc-profiles, restart and stop included (/cc-profiles:open restart), except that Claude runs cc-profiles open with its Bash tool, so Claude Code asks for permission the first time (choose to always allow it). The plugin directory accepts commands that run by themselves only from Verified organizations. The plugin only opens the app: install cc-profiles first. To get it in every profile, install it in the source profile and share plugins from the Profiles tab.
Starting Claude Code in a profile
Claude Code picks its profile from the CLAUDE_CONFIG_DIR environment variable:
claude # ~/.claude
CLAUDE_CONFIG_DIR=~/.claude-work claude # ~/.claude-work
When cc-profiles creates a profile, it also creates a launcher: a small script in ~/.local/bin named after the profile’s command.
claude-work # same as: CLAUDE_CONFIG_DIR=~/.claude-work claude
Launchers work in every shell, right away. They need ~/.local/bin in your PATH; the official Claude Code installer usually adds it. If it is missing, add this line to your shell startup file (~/.zshrc, ~/.bashrc, …):
export PATH="$HOME/.local/bin:$PATH"
Each new profile must log in once: run its command and use /login. Credentials are never copied between profiles.
Finding your way
The tabs sit in one row under the profile cards. On a narrow window the ones that do not fit are in the More menu at the end of the row.
Keyboard shortcuts
| Keys | What they do |
|---|---|
/ |
Search everything |
g then p, m, c, u |
Projects, Memories, Conversations, Usage |
g then s, a, x, l |
Skills, Agents, MCP, Plugins |
g then r, o |
Profiles, Compare |
g then b, h, t |
Backups, Health, Settings |
? |
Show the list of shortcuts |
Esc |
Close the search, a dialog or a panel |
Shortcuts are ignored while you type in a field or while a dialog is open. The keyboard button in the header shows the same list.
Next steps
- Read Concepts: five minutes that make everything else obvious.
- Open the Projects tab: it starts on Needs attention, which lists what to fix first.
Something wrong, unclear or missing on this page? Open an issue on GitHub