cc-profiles Documentation PyPI GitHub Install

Reference

Troubleshooting

“Port 4777 is busy with another program”

Another program uses port 4777: start cc-profiles on another one, cc-profiles --port 4778. If it is cc-profiles itself, already running (started by /cc-profiles or in another terminal), cc-profiles does not complain: it opens your browser on it.

A tab says the page is newer than the server

You updated cc-profiles while it was running: the page comes from the new version, the server is still the old one. Run cc-profiles restart (or /cc-profiles restart in Claude Code) and reload the page.

The page shows “Missing or wrong token”

The page is from an older run of the server. Every start generates a new token: reload the page.

claude-<id>: command not found

The launcher is in ~/.local/bin, which is not in your PATH. Add this to your shell startup file and open a new terminal:

export PATH="$HOME/.local/bin:$PATH"

A new profile is not logged in

That is expected: credentials are never copied. Run the profile’s command and use /login.

A profile that was logged in now says “Not logged in”

If the profile was created by copying another profile’s folder by hand, it shared the same login token. When one profile refreshed the token, the copy became invalid. Log in again with /login. Profiles created by cc-profiles do not have this problem.

A project shows “folder not found on disk”

You moved or renamed the project folder. Use Relink… in the Projects tab, or in Health. If you already opened the new folder in Claude Code, use Merge into… and pick that project. If the folder is on an external disk, connect it: the project comes back by itself.

A project shows “unknown path”

No file mentions the project’s real path, and the folder name could not be matched on disk. That usually means the folder is gone. Delete moves it to the backup.

“A session is open”

A claude process is running in that profile, or a conversation in it was written in the last 2 minutes. Close Claude Code in that profile (every terminal and editor that runs it), wait two minutes, and try again. The check exists because a running session would keep writing into folders being moved.

A restore reports “steps not restored”

Some files the backup needs were changed again by a later operation. Restore the newer backups first, newest first, then try again. The Before restoring: … backup lists every step that was skipped.

A setting I changed has no effect

Settings dropdowns do not show a value I know exists

Dropdown options come from a specific Claude Code version, shown in the Settings tab. A newer Claude Code may accept more values. Set it from the advanced editor, and open an issue so the list can be updated.

/cc-profiles is missing or says the command was not found

The command appears after cc-profiles has started once: the install script starts nothing, but adds it right away; with pipx, uv, pip or Homebrew, run cc-profiles once. It calls cc-profiles by full path; if you reinstalled cc-profiles another way (pipx instead of Homebrew, for example), run cc-profiles once again and it points the command to the new place. Restart open Claude Code sessions to see the change.

The browser does not open (WSL)

Under WSL, cc-profiles opens the Windows browser with wslview or Windows’ start. If neither works, open the address it prints, http://127.0.0.1:4777, in your Windows browser yourself. Installing wslu (sudo apt install wslu) adds wslview.

My rules or profiles are gone

~/.cc-profiles/config.json was not valid JSON, for example after an edit by hand, so cc-profiles started again from the defaults. Your file is kept next to it as config.broken-<date>-<time>.json: fix it (a missing comma or bracket, usually), stop the app, and put it back as config.json. See Configuration.

bad interpreter: … no such file or directory after a Python update

cc-profiles, /cc-profiles included, stops with an error like this one:

bad interpreter: /Users/you/.local/pipx/venvs/cc-profiles/bin/python: no such file or directory

pipx and uv install cc-profiles in its own environment, built on the Python that was installed then. When Homebrew moves to a new Python version (3.14 to 3.15, for example), it removes the old one, and the environment points to a Python that is gone. cc-profiles reinstall cannot run either, because it needs that same Python. Build the environment again on the current Python:

pipx reinstall cc-profiles                         # installed with pipx or the install script
uv tool install --force --reinstall cc-profiles    # installed with uv

pipx reinstall-all does the same for every program installed with pipx, which a Python update breaks in the same way. Your profiles and ~/.cc-profiles (settings, templates, backups) are not touched, and you get the latest version. Then run cc-profiles once, or /cc-profiles restart if the old server is still running.

LookupError: unknown encoding: idna or a similar error after a Python update

A cc-profiles started before Homebrew updated Python keeps running, but the old Python’s files are gone: the first thing it has not loaded yet, such as the code Check for updates needs to reach PyPI, fails with an error like this one. Since 0.6.2 the server notices, starts again with the new Python and the page reloads by itself; try the button again then. An older version, or one that cannot find a Python to start again with, says so: run cc-profiles restart, or /cc-profiles restart in Claude Code.

The Mac app says “cc-profiles did not start”

The Mac app runs the cc-profiles you installed, and shows its output when it fails. bad interpreter or could not start means the command itself no longer runs: see the section above. A busy port means another program uses it: cc-profiles install-app --port 4800 gives the app another one. After fixing it, Try again in the window starts it.

Something is broken after an update or a reinstall

If cc-profiles does not start, a tab keeps failing or /cc-profiles points to the wrong place, install it again from scratch:

cc-profiles reinstall

It uses the tool you installed it with (pipx, uv, Homebrew or pip), keeps your settings, templates and backups in ~/.cc-profiles, and starts the server again if it was running. If the cc-profiles command itself is gone, run the install script again: it installs over the old copy.

Reporting a bug

The quickest way: Report a problem… in the About panel (ⓘ) opens the bug report with the versions filled in. Otherwise open an issue with the steps to reproduce and the output of cc-profiles --version and claude --version. If an operation went wrong, the operation.txt of its backup folder helps, but check it first for private paths or names. Never paste conversations, memories or credentials.