cc-profiles Documentation PyPI GitHub Install

Guides

Profiles and sharing

The Profiles tab lists your profiles with their command, folder and how many conversations, projects and memories each has. From here you create, edit and delete profiles, start one from a template, choose what each profile shares with the source profile, and turn on profile by folder.

The Profiles tab: three profiles with their command, folder and counts, and the Sharing switches below

Claude accounts

Above the profiles, Claude accounts has a card for each claude.ai account the profiles are signed in to (one per organization): the name, email, organization and role, the plan (such as Max 5× or Team), since when you are a member and subscribed, whether extra usage is on, and the profiles that use it. A profile whose sign-in is gone, as after /logout, says so: log in again there with /login. Profiles signed in to no account are listed under the cards.

Plan usage limits

On each card, three bars show how much of the plan is used: the 5-hour window, the week, and the weekly limit of a single model when the plan has one, each with the time it resets. A bar turns orange from 75 % and red from 90 %. In the About panel (ⓘ), under cc-profiles settings, Plan limits picks whether the bars show how much is used or how much is left; the colour follows what is used either way, and the choice is kept in the browser.

cc-profiles asks claude.ai the way Claude Code’s /usage does, with the profile’s sign-in (from the macOS keychain, or .credentials.json in the profile folder), and keeps the answer for 5 minutes: under the bars, the time it was checked, and Refresh to ask again now. The token is only read: it never reaches the page and is never stored, copied or refreshed. When it has expired, the row says to open Claude Code in the profile, which refreshes it. The first time, macOS may ask to let cc-profiles read the keychain. A sign-in with an API key, Bedrock or Vertex has no plan limits.

While the page is open, cc-profiles checks the limits every 15 minutes, from any tab. When a limit reaches 90 % it says so once, in a message at the bottom of the page; the Mac app sends a macOS notification instead, also with its window closed, and shows the 5-hour window’s use next to its menu bar icon. Every check also records the day’s highest value of each limit, which the Usage tab draws.

Create a profile

New profile (in the Profiles tab, or the + New profile card at the top) asks for:

With a template, an item you share is linked to the source profile instead of being filled from the template: the template’s copy of it is not used. The dialog lists what each shared item skips, for example skills: shared with Default, the template’s 3 skills are not copied, and the confirmation after creating says the same. Templates never hold plugins, so sharing plugins is how a profile created from a template gets the plugins of the source profile.

What a new profile never gets:

cc-profiles also creates the launcher ~/.local/bin/claude-<id> (see Getting started) and adds the /cc-profiles command to the new profile, so you can open this app from it right away. If the profile shares commands with the source profile, the command goes into the source and reaches both through the link. A cc-profiles.md that cc-profiles did not write is left as it is.

Items you choose to share that the source profile does not have yet are created there, empty, so the link always works.

Templates

A template is a reusable starting point for new profiles. Templates… in the Profiles tab lists them and saves a new one from any profile.

A template holds the profile’s settings.json and settings.local.json (with permissions and hooks), CLAUDE.md, skills/, agents/, commands/, output-styles/ and the MCP servers of .claude.json (user scope). It never holds conversations, prompt history, memories, plugins, login credentials (.credentials.json) or account data (oauthAccount, userID). Shared items are saved as real files, so the template does not depend on the source profile.

Templates are .zip files in ~/.cc-profiles/templates/, in the same format as an export without conversations. Creating a profile from a template uses the import code, so paths inside settings.local.json point to the new folder.

Saving, deleting and creating a profile from a template each have a backup. A deleted template goes to the backup and Restore brings it back.

Edit a profile

Edit changes:

Never rename a profile’s folder in the Finder: the paths in its files, its command and the links of other profiles would still point to the old name.

Delete a profile

Delete offers two options:

When the profile has conversations or memories, moving them is the option already chosen; pick Delete everything to drop them.

In both cases the profile leaves config.json and its launcher (or shell alias) is removed. Type the profile’s name to enable the button.

The dialog shows what the chosen option does before you confirm: how many projects, conversations, memories and prompts move and where, and under Show the files and folders it touches every item, including the launcher, the alias line in your shell file, the entry in config.json and the folder that goes to the backup. The preview changes nothing.

Deleting is refused:

Share items

Under Sharing, each secondary profile has a switch per item:

Item What sharing means
skills same local skills everywhere
plugins same installed plugin files (enabling is per profile, in settings.json)
agents same custom subagents
commands same custom slash commands
CLAUDE.md same global instructions
settings.json same settings, status line, enabled plugins, permissions and hooks

Turning a switch on replaces the profile’s own copy with a link. The old copy goes to the backup, and the confirmation lists anything the source profile does not have, so you can copy it over first. Turning it off gives the profile an independent copy of the current source content.

Both confirmations have Show the files and folders it touches: the own copy that goes to the backup, each item only that copy has, the link and its target, and what is created in the source profile when it does not have the item yet; when separating, the link that goes to the backup and the files copied in its place.

Share everything

Share everything…, at the top of each profile’s card, makes the profile differ from another one only by its Claude account. Pick the other profile in With: the source profile, or any other one. One confirmation lists what happens, and one backup holds all of it, so one Restore undoes it:

Projects opened later in one profile only are not shared by themselves: run Share everything again. Then to change account, open Claude Code with the other profile’s command, or use Continue in… to go on with the same conversation.

The item switches show shared with … for an item linked to a profile other than the source; unticking it gives the profile its own copy. A profile whose files others use this way cannot be deleted until they are separated.

A GitHub account per profile

Signing in to GitHub is not part of a Claude Code profile: the GitHub CLI (gh) keeps its sign-in in a folder, ~/.config/gh, shared by everything you run. cc-profiles gives every profile a GitHub CLI folder of its own, named after it:

Profile GitHub CLI folder
Default (~/.claude) ~/.config/gh, the same as your terminal
~/.claude-<id> ~/.config/gh-<id>

cc-profiles creates the missing folders when it starts, and a new profile gets its own right away. A new folder starts with the account the profile used until then (config.yml and hosts.yml are copied without any token line), and GH_CONFIG_DIR in the env of the profile’s settings.json points to it: Claude Code passes it to every command it runs, so gh in that profile’s sessions uses that folder. The profile cards and the About panel show the account: GitHub as ….

A profile’s folder lists only the account it uses. gh auth status in a session of that profile shows that account alone, and there is no other one to gh auth switch to, so Claude cannot use or pick another account by mistake. cc-profiles keeps it so: when it starts, and when you pick another account for a profile, the other accounts leave that profile’s folder (the file goes to the backup first). They stay listed in Default’s folder or in ~/.config/gh-accounts, so you can still pick them here. Two folders are left as they are: Default’s ~/.config/gh, because it is your terminal’s too, and a folder with a token written in its hosts.yml, where taking an account off would delete its token. This keeps accounts apart, it is not a wall: the tokens are in one system keychain, and a command that sets GH_CONFIG_DIR to another folder uses that folder’s account.

The GitHub section at the bottom of the Profiles tab has a row per profile. As in Settings, what you change there is a draft: changed rows get an orange bar, and Save changes in the bar below the table saves them all in one backup (Cancel drops them).

A profile whose settings.json is shared with the source profile also shares its GitHub account, so it has no folder. An account whose token is written in hosts.yml (gh auth login --insecure-storage) is not offered to the other profiles, because its token is not in the keychain; a folder copied from it asks for a sign-in.

For git push to follow the account too, git must ask gh for GitHub passwords: run gh auth setup-git once. The section warns when it is not set up, with a button to copy the command. Changes apply to the profile’s Claude Code sessions, not to your own terminal (except for Default), and an open session picks them up when it restarts. Every change goes to the backup.

cc-profiles reads only which users each folder is signed in as, never a token. Deleting a profile leaves its GitHub CLI folder in place; gh auth logout inside one folder removes that account’s token from the keychain, which signs it out in every folder.