Guides
Health and About
Health
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:
- Claude Code: version, binary path, install method, auto-updates, and the Claude Code version the settings dropdowns were checked against.
- Each profile:
- account, login method, plan, organization, API provider;
- usage: startups, first start, conversations, projects, memories, prompts, disk usage;
- contents: skills, plugins, subagents, slash commands, output styles, MCP servers, hooks,
CLAUDE.md, shared items.
- cc-profiles: version, code and data locations, number and size of backups, address, Python version and system.
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.
Something wrong, unclear or missing on this page? Open an issue on GitHub