cc-profiles Documentation PyPI GitHub Install

Guides

Health and About

Health

The Health tab: the checks of each profile, and a project whose folder is gone with Relink, Merge into and Delete

The Health tab checks every profile:

Check Fails when
Login claude auth status says the profile is not logged in
.claude.json, settings.json, settings.local.json the file is not valid JSON
Prompt history some lines of history.jsonl are not valid JSON
skills, plugins the folder is a broken link (shared items show where they point)
Plugins an installed plugin’s files are missing
Memory indexes MEMORY.md lists a missing file (error), or a memory is not listed (warning)
Open session warning only: a claude process is running in the profile, or one of its conversations was written in the last 2 minutes

Below the checks, Projects whose folder is gone lists the orphan projects of the profile, with one-click Relink to … buttons for the candidate folders found, plus Relink…, Merge into… (into another project of the profile) and Delete.

Disk space

Below the checks, Disk space shows what fills one profile’s folder (pick it at the top of the section), and what has been untouched for a number of days: 30, or the profile’s Keep conversations for setting when it has one.

Row What it holds
Conversations projects/*/*.jsonl, with each conversation’s subagent replies, file snapshots, session environment and task lists. Memories and the prompt history stay.
File snapshots file-history/ of conversations that no longer exist
Session environments session-env/ of conversations that no longer exist
Task lists todos/ of conversations that no longer exist
Shell snapshots shell-snapshots/: your shell’s setup, saved at the start of each session
Debug logs debug/, written with --debug
Pasted text, Pasted images paste-cache/, image-cache/

Tick what to clean up and press Move … to a backup…. Conversations are not ticked at first: an old conversation can no longer be resumed or read once it is gone, and the confirmation says so. Nothing is deleted. Everything goes into one backup, so Undo puts it back, and the space comes back when that backup is deleted in Backups, or by itself after the backup cleanup’s days (90 by default). Only items untouched for at least one day are ever offered, so an open session is never touched. A folder that is a link to another profile’s is cleaned up from that profile.

Health runs claude auth status once per profile, so it takes a few seconds. Run the checks again refreshes it. The list of projects whose folder is gone also updates by itself when you come back to the page, for example after renaming a folder.

About

The ⓘ button at the top right opens a panel with:

On macOS the cc-profiles card also says whether the Mac app is in Applications: Add Mac app creates it, and Update Mac app shows when it is from another version or uses another port than this server. Both make a backup.

Below them, What’s new shows the release notes of the last versions, and Report a problem… opens a bug report on GitHub with the versions of cc-profiles, Claude Code, Python and your system already filled in. Nothing is sent until you submit the form, and you can read and change every field first.

What’s new after an update

The release notes come with the app: after cc-profiles updates, from the app or from a terminal, the next time you open it a window shows what changed since the version you used before, once. It reads nothing from the internet. On a new installation it shows nothing; open it any time from What’s new in the About panel, or see every release.

Updating cc-profiles

cc-profiles asks PyPI for its latest version by itself, at most once a day: a few seconds after it starts, and again every day while it runs. When a newer version exists, the ⓘ button gets an orange dot, a notice says so once for each new version, and the Update button at the top of the About panel, next to Refresh, lights up in the logo’s orange (it stays grey and cannot be clicked while cc-profiles is up to date). The line at the bottom of the panel says which version is available. Nothing is installed until you click. At the bottom of the About panel, Check for updates asks PyPI right away.

The check sends PyPI only a request for the version, and PyPI sees your IP address. To turn it off, untick Check for updates automatically, once a day in the About panel, under cc-profiles settings (it writes "update_check": false in config.json): then cc-profiles asks only when you click. Apart from this check, cc-profiles reaches the internet only to read your plan limits from Anthropic (with each profile’s own sign-in), to ask GitHub’s public API for commit identities, and to run the Claude Code installer when you click Install: see Security.

When a newer version exists, Update runs the update for the way you installed cc-profiles, pipx upgrade cc-profiles, uv tool upgrade cc-profiles or brew upgrade cc-profiles, then restarts the app on the same port; the page reloads by itself. Your profiles, backups and settings are not touched. A copy run from the source folder, or installed with plain pip, shows the command to run by hand instead. In the first minutes after a release, PyPI announces the new version before pip can download it: the update then changes nothing and says so: click Update again a few minutes later (pip’s output is under Details). After updating from a terminal, run cc-profiles restart so the running app picks up the new version.

Installing Claude Code

If Claude Code is not found, a notice at the top of the page offers Install Claude Code…. The same button is in the About panel. You pick one of the official methods from the Claude Code setup guide:

Method Command Updates
Official installer (recommended) curl -fsSL https://claude.ai/install.sh \| bash automatic
Homebrew, stable brew install --cask claude-code brew upgrade claude-code
Homebrew, latest brew install --cask claude-code@latest brew upgrade claude-code@latest
npm (Node.js 22+) npm install -g @anthropic-ai/claude-code npm install -g @anthropic-ai/claude-code@latest

Methods that cannot work on your machine are disabled, with the reason (“Homebrew is not installed”, “needs Node.js 22 or later”). The installation output is shown live, and at the end the app checks that claude is really there.

If Claude Code is installed but your terminal cannot find it (usually because ~/.local/bin is not in PATH), the notice tells you which line to add to your shell startup file. cc-profiles asks your login shell for the PATH a new terminal gets, so the notice is right even when cc-profiles runs from the Mac app, whose own PATH is macOS’s minimal one.

cc-profiles looks for programs in your PATH plus ~/.local/bin, /opt/homebrew/bin and /usr/local/bin, so it finds a fresh installation even if it was started from a terminal opened before installing.