cc-profiles Documentation PyPI GitHub Install

Working on cc-profiles

Architecture

cc-profiles is a small Python package (one module per area), one HTML file for the UI and a test suite, on purpose: no framework, no build step, no dependencies.

browser ──HTTP (token)──► cc_profiles ──reads/writes──► ~/.claude*, ~/.claude.json
   ▲                          │
   └──── index.html ◄─────────┘        ~/.cc-profiles/{config.json, backups/}

The server: src/cc_profiles/

A ThreadingHTTPServer from the standard library, bound to 127.0.0.1. GET / serves static/index.html with a fresh token inside, and GET /static/<name> its stylesheet and scripts (only [a-z]+.css and .js files of that folder). Everything else is a JSON API under /api/ (see API).

The code is one module per area. Each module imports only from the ones above it in this table, so there are no import cycles:

Module Responsibility
byfolder.py rule matching (match_rule(), san()), cc-profiles which and shell-init. Imports nothing from the package, so which starts fast on every claude launch
core.py paths and constants, san(), atomic write_text(), cached_read(), config loading and first-run detection, Backup and failed-operation handling, tool lookup, settings files, running sessions
folders.py Choose…: the system’s folder dialog (osascript, zenity, kdialog) and the folder listing of the page’s own browser (read-only)
paths.py rules, path_index() (folder name → real path), resolve_on_disk(), shared memory links (memory_holder(), memory_sharers())
projects.py list, move (with preview), relink, delete, rules; a project’s whole folder shared with another profile (a link to the holder’s)
memories.py list, read, save, move, delete; a project’s memory shared between profiles (a link to the holder’s), with a preview
sharing.py symlinks to the source profile, with a preview; Share everything (every item but settings.json, and every project)
settings.py schema-checked fields (SETTING_FIELDS, SCHEMA_VERSION), permissions, raw JSON, CLAUDE.md; a value or a rule applied to every profile
statusline.py the status line cc-profiles writes for a profile (a sh script reading Claude Code’s JSON with jq), its presets and preview, applied to one profile or to all
hooks.py hooks of settings.json and settings.local.json: listed (plugin hooks read-only), a command hook added, edited (other keys kept) or moved, any hook deleted or copied to one profile or to all; a hook is named by its place and a fingerprint, so a changed file is never edited blindly
keybindings.py keybindings.json: listed, checked as Claude Code checks it, saved whole, removed, copied to one profile or to all
github.py a GitHub account per profile: GitHub CLI folders and their user, GH_CONFIG_DIR and the commit identity in the profile’s env, and a folder of its own for each new profile
health.py profile summaries, candidate folders, health checks
backups.py list, what a backup changed (steps and diffs, read-only), restore (journal replayed backwards), delete, prune, automatic cleanup (backup_keep_days, 90 days by default), kept backups
storage.py disk space of a profile by kind (conversations and what goes with them, caches, logs), and what has been untouched for some days moved into a backup
info.py the About panel
extensions.py skills and MCP servers, copied to one profile or to all; the browser for Claude (the local one, Playwright’s MCP server, and Claude in Chrome at start, only ever turned off); claude.ai connectors kept out of a profile, and checked against the account with claude mcp list
agents.py subagents: the frontmatter fields checked against Claude Code’s schema (AGENT_SCHEMA_VERSION), create, edit (other keys kept), rename, copy to one profile or to all, delete; plugin agents read-only
conversations.py list, view, move one, delete
usage.py tokens and estimated cost per day, project, model, profile and conversation, and the CSV export, from the usage of every reply (read-only); the list-price table
quota.py the claude.ai accounts the profiles are signed in to (from oauthAccount), and the plan’s usage limits (5 hours, week) of each, asked of claude.ai with the profile’s sign-in from the keychain or .credentials.json, never stored or refreshed (read-only)
mods.py Claude Code mods recognised among the installed plugins, and what each one does, read from its source (read-only)
search.py global search and profile comparison (read-only)
command.py the /cc-profiles command file
claudebinary.py Claude Code’s own slash commands and bundled skills, read from the installed binary (mapped, not loaded) and kept in ~/.cc-profiles/claude-commands.json until it changes (read-only)
slashcommands.py custom slash commands (commands/**/*.md, a subfolder for a namespace): create, edit, copy to one profile or to all, delete; /cc-profiles and plugin commands read-only; Claude Code’s own commands and skills (BUILTIN_COMMANDS, BUILTIN_SKILLS: groups, and the fallback when the binary cannot be read)
macapp.py cc-profiles install-app: the Mac app in ~/Applications, put together from app/main.swift (compiled into the package by scripts/build_app.py), its Info.plist, launch.json and icon (drawn in Python); kept up to date at every start
terminal.py Continue in… (a conversation resumed in another profile, its project shared first if needed); Open in Terminal: a project’s folder in a new terminal window with Claude Code in a profile, through a script that deletes itself. Terminal, iTerm or Ghostty on macOS; on Linux, in a graphical session, a fixed list of terminal programs found on the PATH (LINUX_TERMINALS)
launchers.py ~/.local/bin scripts, legacy shell aliases, and the profile by folder line in the shell rc files
newprofile.py copy or create, never copying credentials
transfer.py export and import of a profile as a .zip
autoexport.py automatic exports of every profile (daily or weekly, the last 3 of each kept) into iCloud Drive or ~/.cc-profiles/exports, in a background thread; a profile whose folder is gone restored from its latest export
templates.py profile templates: an export without projects in ~/.cc-profiles/templates/, used to create new profiles
plugins.py installed plugins, enable and disable, copy to another profile
editprofile.py rename, change command, rename the folder (paths in its files, launcher, links of other profiles), delete with optional merge, with a preview
installer.py official Claude Code install methods, background job with live log
updater.py check for updates on PyPI, update and restart
selfinstall.py cc-profiles uninstall and reinstall: what cc-profiles added to Claude Code, and the fixed package commands per install kind
web.py routing, error handling, the security guard, the Content-Security-Policy
cli.py serve (with the automatic backup cleanup at start and daily, and /cc-profiles added or updated at start), open, stop, restart, install-command, install-app (and the Mac app updated at start), label, argument parsing
entry.py the console script: which and shell-init go to byfolder.py without loading the server, everything else to cli.main

server.py re-exports every public name, so from cc_profiles import server keeps working; the cc-profiles console script is entry.main. The version lives in __init__.py. PORT and ALLOWED_HOSTS are set when the server starts: other modules read them as core.PORT and core.ALLOWED_HOSTS, never as names imported at load time.

Request flow

  1. _guard() checks the Host header and, for /api/, the X-Token header.
  2. A routing table maps the path to a function. GET handlers only read.
  3. POST handlers run under a global lock, so writes never interleave.
  4. Errors raised as ApiError become {"error": "..."} with their status code; anything unexpected becomes a 500 with the exception text, which the UI shows in a toast.

The backup journal

The Backup class is the heart of the safety model. An operation opens a backup, records each step as it does it, and closes it:

bk = Backup("move-a-b", "Move ~/code/api: A → B")
bk.copy(history_file)          # before modifying it
write_text(history_file, ...)
shutil.move(src, dst)
bk.moved(src, dst)             # right after moving
return {"message": "...", "backup": bk.close()}

op_restore() replays the journal backwards. Two details matter:

Atomic writes

write_text() writes a temporary file in the same folder and renames it over the target with os.replace. On the same file system the rename is atomic: Claude Code, which reads .claude.json and history.jsonl all the time, sees either the old file or the new one.

Path resolution

Claude Code names project folders with san(path), which loses information (/, ` , . and + all become -). path_index() builds the reverse map from the paths the profiles mention: first the projects key of each .claude.json and the project field of history lines; then, only for folders still without an existing path, the cwd of the first lines of their conversations. For names nothing mentions, resolve_on_disk() walks from /` and, at each level, tries entries whose sanitized name is a prefix of what is left, longest first.

Caches

A large home has tens of thousands of conversation files, so listings keep what they read. Every cache is read-only and lives in the server process; none is written to disk, except the plan limits’ daily history (below).

Cache Where Keyed on
cached_read(kind, path, compute): the parsed content of a file or the listing of a folder core._file_cache the file’s or folder’s (mtime_ns, size, inode), checked with a fresh stat() on every use
load_config() core._file_cache config.json’s stat; callers get a deep copy
Conversation and memory file names of each project folder (project_folders(), memory_files()) core._file_cache the folder’s stat (adding, removing or renaming an entry changes its mtime)
Token usage of a conversation file (one record per reply), for the Usage tab core._file_cache the file’s stat
cwds of a conversation, projects of .claude.json, history summary (prompts, broken lines, projects), MEMORY.md, memory and skill text for search, backup manifests core._file_cache the file’s stat
Size of a closed backup core._file_cache the backup folder’s stat (only its manifest is ever rewritten, by os.replace)
Size of a profile folder (About) backups._size_cache time: 60 s
Folders under the search roots, by name (Health, relink candidates) health._cand_cache time: 60 s, and the search roots; Relink… and Run the checks again search afresh (fresh=1)
Running claude processes core._running time: 3 s
Plan usage limits of an account (Profiles) quota._cache time: 5 minutes, and the account. Each new answer also updates the day’s highest values in ~/.cc-profiles/quota-history.json (the Usage tab’s chart, 90 days), the only cache written to disk besides update-check.json

Rules that keep this safe:

tests/bench_home.py times every tab on a large fake home (see CONTRIBUTING).

The UI: src/cc_profiles/static/

Semantic HTML in index.html, CSS custom properties for both themes in app.css, and vanilla JavaScript, with no build step. The JavaScript is split by area into classic scripts that index.html loads in order at the end of the body. They share one global scope, as if they were one file: a function or const of one file is visible to the others. Only code that runs while the files load (listeners added by name, const X = f()) needs what it uses to be in the same file or an earlier one.

File Holds
core.js the state S, $(), esc(), api(), run(), modal(), data loading. First
projects.js Projects, Choose…, Open in Terminal, dropped files, Memories, Conversations, Health
profiles.js profiles and sharing, the GitHub account per profile, profile by folder
extensions.js Skills, MCP servers and claude.ai connectors, Agents
settings.js Settings, status line, theme
about.js About, the update check, what’s new, export, import and plugins, installing Claude Code
tools.js Search, Compare, Usage, Backups
main.js navigation, keyboard shortcuts, the delegated click handler, and the start of the page. Last

The token (const TOKEN = "…") and the theme set before the first paint stay inline in index.html, with a nonce that changes at every response: the Content-Security-Policy runs only those and the files of static/, so markup injected by an escaping mistake cannot run.

The visual rules are in DESIGN.md.

Security model

The threat is another program or website reaching the local server, not the user. Hence:

Tests

tests/conftest.py builds a fake HOME with fake profiles (FakeHome) and starts the real server on it as a subprocess (App), with a PATH that contains no claude, brew or npm. Tests call the API exactly like the UI, then usually restore every backup and compare a snapshot of the fake home (every file’s hash, every link’s target, every folder) with the one taken before.