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
_guard()checks theHostheader and, for/api/, theX-Tokenheader.- A routing table maps the path to a function. GET handlers only read.
- POST handlers run under a global lock, so writes never interleave.
- Errors raised as
ApiErrorbecome{"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:
bk.copy()keeps only the first copy of a path, the true original. A later copy would capture an intermediate state.bk.copy()andwrite_text()resolve symlinks, so shared files are written and restored in place without replacing the link.
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:
- A cache keyed on a stat is as current as a new read: a changed file is read again in the same request. Time-keyed caches only serve numbers and suggestions on screen.
- Before a write, code reads afresh:
history_lines()(never cached) for history rewrites,memory_files(d, fresh=True)before deleting a folder,read_json()for manifests being restored. - At startup,
cli.warm_caches()fills the caches in a background thread (projects, backups, profile sizes, search texts, token usage), so the first tabs open fast. It only reads.
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.
- A single state object
Sholds the current tab, data and filters. - Each tab has a
load…()function, which fetches, and arender…()function, which writes#main.innerHTMLfromS. - All user data goes through
esc()before entering HTML. - One delegated
clicklistener ondocumentdispatches ondata-*attributes. modal()returns a promise with the chosen action, which keeps confirmation flows linear withawait.api()adds the token and turns errors into exceptions;run()shows the resulting toast.
The visual rules are in DESIGN.md.
Security model
The threat is another program or website reaching the local server, not the user. Hence:
- binding to
127.0.0.1only; - an exact
Hostcheck, because DNS rebinding can make a remote name resolve to127.0.0.1; - a per-run token that only the served page knows. No CORS headers are sent, so another origin cannot read the page to steal it;
- strict validation of every name coming from the client, and installer methods chosen from a fixed list;
- a Content-Security-Policy that runs only the page’s own scripts (
static/*.jsand two inline ones with a per-response nonce) and lets it connect only to this server.
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.
Something wrong, unclear or missing on this page? Open an issue on GitHub