cc-profiles Documentation PyPI GitHub Install

Working on cc-profiles

HTTP API

The UI talks to the server through a small JSON API. It is an internal API, made for the page, and may change between versions. It is documented to make contributing easier.

Conventions

Read

Endpoint Parameters Returns
GET /api/profiles   profiles with label, command, folder, email, github (the active GitHub account), counts, primary, active
GET /api/projects   every project: real path, exists, expected profile, per-profile counts, issues
GET /api/candidates name, fresh (1 to search again; otherwise the search of the last minute is reused) up to 10 folders with that name under the search roots
GET /api/memory/projects profile the profile’s projects with memory and conversation counts
GET /api/memory/list profile, project memories with name, type, description, indexed; missing index entries; sharing: from (the profile whose memory this one uses), with (the profiles using this one’s), others
GET /api/memory/file profile, project, file {content}
GET /api/projects/share-plan profile, project, from what sharing from’s folder of the project with profile does: conversations and memories of its own that join, conflicts, theirs (conversations already there), active
GET /api/conversations/continue-plan profile, project, session, to {shared, holder, holder_label, recent}: whether to sees the conversation already, who holds the project’s folder, and whether it was written in the last 2 minutes
GET /api/memory/share-plan profile, project, from what sharing from’s memory with profile does to its own memories: join, conflicts
GET /api/conversations/projects profile the profile’s projects that have conversations, with count
GET /api/conversations profile, project {conversations: [{session, title, prompts, replies, first, last, mtime, size, snapshots}], path}, newest first
GET /api/conversations/view profile, project, session {messages: [{role, time, text}], truncated, total}: prompts, replies and one line per tool call; the last 300
GET /api/usage profile (all or an id, default all), days (7, 14, 30 or 90, default 30) {profile, days, start, end, currency, prices_checked, prices, totals, daily, projects, projects_count, models, profiles}. Every total has input, output, cache_write, cache_read, tokens, replies, cost (estimated USD at list price) and unpriced_tokens (tokens of models without a price); totals adds cache_read_share. daily has one entry per day of the period, zeros included, with date (local); projects the top 10 with profile, name, pretty; models has model and family (null without a price); profiles only with all; sessions the 10 conversations with the highest cost, then the most tokens, with profile, project, pretty, session, title, exists (the main conversation file is there), date and last of the last reply. A reply counts once per message and request id. Read-only
GET /api/usage.csv the same as /api/usage a text/csv; charset=utf-8 download, cc-profiles-usage-<profile>-<days>d.csv: one row per day and model with date, model, input_tokens, output_tokens, cache_write_tokens, cache_read_tokens, replies, estimated_cost_usd (empty without a list price). Needs the X-Token header like every API call. Read-only
GET /api/quota profile, fresh (1: ask again instead of the answer kept for 5 minutes) {state, …}: ok with limits (label such as 5 h, Week or Week · Opus, percent used, resets_at ISO time or null), plan and checked; otherwise none, unknown, expired or error with a message. The plan’s usage limits of the claude.ai account signed in to the profile, asked of claude.ai with the profile’s sign-in the way Claude Code’s /usage does; the token is never sent to the page, stored or refreshed. Read-only
GET /api/quota/history   {accounts: [{account, name, days: [{date, limits: {label: percent}}]}]}: the highest value of each limit on each day an answer came from claude.ai, per account (its email, or profile:<id> without one), for the last 90 days, from ~/.cc-profiles/quota-history.json. Read-only
GET /api/accounts   {accounts: [{email, name, organization, role, plan (such as Max 5× or Team), billing, extra_usage, since, subscribed, profiles: [{id, label, sign_in}], quota_profile}], not_signed_in}: the claude.ai accounts the profiles are signed in to, one per account and organization, from the oauthAccount of each .claude.json. sign_in is ok, refresh (expired: Claude Code refreshes it at the next session) or signed_out; quota_profile is a profile whose sign-in can ask /api/quota, or null. Asks claude.ai nothing; tokens are never returned. Read-only
GET /api/skills profile {skills: [{name, title, description, files, linked}], dir, shared}
GET /api/skills/file profile, name {content} of SKILL.md and the other files in the folder
GET /api/agents profile {agents: [{name, title, description, model, color, tools, disallowed, effort, valid, linked, lines}], dir, shared, plugins, options, tools, schema_version}: the profile’s subagents; plugins the read-only ones of installed plugins (with plugin); options the dropdowns’ values
GET /api/agents/file profile, name {content, fields, prompt, valid, other}: the whole file, the form’s fields, the instructions, and the other keys of the frontmatter
GET /api/agents/copy-all/preview profile, name {name, from, apply, skip}
GET /api/commands profile {commands: [{name, slash, description, fallback, hint, model, tools, linked, managed}], dir, shared, plugins, template}: the profile’s slash commands (name is the path under commands/ without .md, slash how it is typed); fallback the prompt’s first line when there is no description; managed marks /cc-profiles; plugins the read-only ones of installed plugins; skills every skill that can be typed as a command ({slash, hint, description, source}, source profile, the plugin, or builtin); builtin Claude Code’s own commands ({name, slash, hint, description, aliases, group}), from builtin_version; builtin_source installed when they were read from the installed Claude Code’s binary (new ones in the group New in your version), list for cc-profiles’ own list; installed_version the installed Claude Code’s (null when not found)
GET /api/commands/file profile, name the command’s summary plus content, the whole file
GET /api/commands/copy-all/preview profile, name {name, from, apply, skip}
GET /api/mcp profile {servers: [{name, scope, type, target, env, headers}], config, projects}; env and headers list names only
GET /api/browser profile {config, email, local: {name, servers, taken, command, npx, elsewhere}, chrome: {on, profiles}, warnings}: the local browser (Playwright’s MCP server; servers are this profile’s servers running it, taken a server called playwright that is something else, elsewhere the other profiles that have it) and Claude in Chrome at start (claudeInChromeDefaultEnabled; profiles every profile where it is on, with its account). warnings when Chrome is on at start in profiles of more than one account
GET /api/connectors profile {connectors: [{name, rule, blocked, where, seen, on_account}], all_off, url, check, errors}: the claude.ai connectors of the profile. rule is the deny rule for the whole connector, where the settings files that have it, seen whether it is in claudeAiMcpEverConnected, on_account what the last check found (null before one); all_off lists the files with disableClaudeAiConnectors: true
GET /api/connectors/check profile, force (1 to ask again within the hour) {skipped, gone, error}: runs claude mcp list in the profile (at most once an hour) to learn the account’s connectors; gone are the ones in the profile’s list that the account no longer has. Skipped without Claude Code, without a sign-in, or with every connector off. Changes nothing
GET /api/folders path (absolute or starting with ~), hidden (1 to list hidden folders) {path, parent, home, folders, truncated, crumbs}: the subfolders of the closest existing folder (at most 500), for the folder browser. Read-only
GET /api/folders/pick start, prompt opens the system’s folder dialog and waits: {native: true, cancelled, path, exists}, or {native: false, start} when there is none here. Read-only
GET /api/github   {gh, git_uses_gh, accounts, profiles: [{id, label, dir, user, users, set_up, shared, default, name, email, suggest}], account_list: [{user, folders, used_by, insecure}], accounts_dir}: each profile’s GitHub CLI folder and active account, its commit identity and suggest, the one of its account ({name, email}, or null without an account or a git config), and every account signed in on the computer. Only user names are read from hosts.yml, never a token
GET /api/mcp/server profile, scope (user or a project path), name {config}: the full server entry, values included
GET /api/sharing   for each secondary profile, the state of every shareable item; linked names the profile an item links to when it is not the source
GET /api/plugins profile {plugins: [{name, plugin, marketplace, version, installed, path, is_installed, scopes, projects, enabled, source, mod}], marketplaces, dir, shared}; mod is null for a plugin that is not a mod, else {features, commands, events: [{name, label}], reach} read from its source
GET /api/profiles/export id, projects (1 to include conversations) a .zip download (not JSON): profile/…, claude.json, home-memory/…, cc-profiles-export.json; never login credentials
GET /api/settings profile settings fields (value, source, options, other profiles), permissions, CLAUDE.md, raw files, global info
GET /api/projects/merge/preview project, profile, into (another project of the same profile, on disk) {from, into, conversations, memories, prompts, conflicts}: what merging would move, and the files the target already has. Changes nothing
GET /api/projects/move/preview project, from, to {items: [{action, item, from, to}], prompts, settings, history, config}: what a move would do; action is move, merge or conflict. Changes nothing
GET /api/profiles/rename-folder/preview id, name {profile, from, to, command, files, links, link_count}: what renaming the folder would rewrite. Changes nothing
GET /api/profiles/delete/preview id, merge_into (optional) {items: [{action, item, from, to}], projects, conversations, memories, prompts, settings, active, folder, config, into}: what deleting would do; action is move, merge, conflict, stash (goes to the backup) or edit (a line or entry removed from a file). Changes nothing
GET /api/sharing/everything/preview profile, to (default: the source profile), settings (1: settings.json too) {profile, source, items: [{item, action, join, backup}], projects: [{name, pretty, action, reason, holder, joins, new}], active}; action is share, already or skip. Changes nothing
GET /api/sharing/preview profile, item, shared (1 to share, 0 to separate) {items: [{action, item, from, to}], source, profile, only_own}; action is create (made empty in the source), stash, only-here (only the own copy has it), link or copy. Changes nothing
GET /api/settings/field/all/preview profile, key {key, label, value, shown, from, apply: [{id, label, detail}], skip: [{id, label, reason}]}: which profiles applying the value would change
GET /api/statusline profile {value, source, mode: off\|builtin\|custom, parts, separator, colors, limits, script, script_is_other, jq, separators, brackets, parts_available}; limits is used or left, and the limit pieces of parts_available also have a sample_left
GET /api/statusline/preview profile, parts (comma-separated id:brackets), separator, colors (1 or 0), limits (used or left) {text, script}: what the built-in script prints on sample data (its own sample conversation, never a file of yours), and the script
GET /api/statusline/all/preview profile {from, mode, apply, skip}
GET /api/hooks profile {hooks: [{file, event, matcher, group, index, fp, type, text, timeout, async, status, other}], files, plugins, disabled, disabled_in, events: [{name, desc, matchers}], schema_version}: the hooks of settings.json (file: settings) and settings.local.json (local); group, index and fp (a fingerprint of the hook) name one in a write; other lists its keys the form does not show; plugins the read-only ones of installed plugins
GET /api/hooks/copy-all/preview profile, file, event, group, index, fp {event, matcher, text, from, apply, skip}
GET /api/keybindings profile {path, exists, shared, error, warnings, rows: [{context, key, action}], raw, contexts, others: [{id, label, count, same}], schema_version}: keybindings.json, its shortcuts, and how many each other profile sets
GET /api/keybindings/copy-all/preview profile {from, apply, skip}
GET /api/settings/permissions/all/preview list (allow, ask, deny), rule {list, rule, apply, skip}
GET /api/skills/copy-all/preview profile, name {name, from, apply, skip}
GET /api/mcp/copy-all/preview profile, scope, name {name, from, apply, skip}
GET /api/browser/local/all/preview   {name, from, apply, skip}: the profiles the local browser would be added to
GET /api/browser/chrome-off/all/preview   {apply, skip}: the profiles where Claude in Chrome connects at start
GET /api/templates   {templates: [{name, from, created, items, skills, mcp, counts, size}], dir}; counts: entries per shareable item the template holds, e.g. {skills: 3, "CLAUDE.md": 1}
GET /api/backups   backups, newest first, with title, size, steps, restorable
GET /api/backups/changes name {name, title, created, log, failed, restored, steps, files_changed, max_lines, max_bytes}: each journal step with op, text (in plain words), path, to (moves), now (file, folder, link or null); copy steps add diff with status (changed, same, hidden-only, secret, too-big, binary, dir, unavailable), lines (unified diff, the backup copy against the file now, at most 2,000 lines), added, removed, truncated, notes. JSON is compared with sorted keys and secrets masked; .credentials.json is never read. Read-only
GET /api/backups/auto   {days, default, choices, last, message, config}: the automatic cleanup setting (90 days when unset; it cannot be off) and its last run
GET /api/search q (2 characters or more) {q, results: {projects, memories, skills, mcp, claude_md}, counts, truncated}; each result has kind, profile, title, snippet {text, at, len} and open (what to open). Never includes MCP env or header values
GET /api/compare a, b (profile ids) {a, b, settings, permissions: {a, b, diff}, skills, mcp, claude_md, plugins}: differences between two profiles, read-only
GET /api/health fresh (1 to search the candidate folders again) checks and orphan projects for every profile (runs claude auth status)
GET /api/storage profile, days (optional: the profile’s cleanupPeriodDays, or 30) {profile, dir, days, total, cleanup_days, default_cleanup_days, keep_days, categories: [{id, label, where, desc, size, count, old_size, old_count, shared}]}: what fills the profile’s folder, and what has been untouched for days
GET /api/about   Claude Code, per-profile account/usage/contents, app info
GET /api/update   {current, latest, newer, kind, command, can_update, manual}: asks PyPI, only when called (Check for updates), and keeps the answer
GET /api/macapp   the Mac app: {supported: false} outside macOS, else {supported, state, path, port}, state being missing, current, outdated (another version, or another port than this server) or foreign (an app cc-profiles did not create)
GET /api/terminal   Open in Terminal: {supported: false} outside macOS and a Linux graphical session, else {supported, terminal, choices}, terminal being the one projects open in and choices the ones installed
GET /api/autoexport   the automatic export: every (day, week or null), dir, icloud, keep, running and the profile being exported, last and next (Unix times), and results: per profile its file and size, or an error
POST /api/autoexport {every} turn the automatic export on (day, week) or off (anything else), with a backup
POST /api/autoexport/run {} export every profile now, in the background: follow it with GET /api/autoexport
POST /api/profiles/restore-export {id} put back the folder of a profile that is gone from its latest export (restore_from in GET /api/profiles), with a backup
GET /api/update/auto   the same fields from the last answer, without asking PyPI, plus enabled (the automatic daily check) and checked (when PyPI was last asked)
POST /api/update/auto {enabled} turn the automatic daily check on or off (update_check in config.json), with a backup
GET /api/claude/status   whether Claude Code is installed, install methods, install job state
GET /api/shell   profile by folder: {installed, targets: [{file, shell, line}], shell, lines, on_path, rules: [{text, exact, profile, label}], projects: [{path, rule, profile, label}]}: the rc files that have the line, the ones turning it on would write, the rules, and what cc-profiles which gives each known project
GET /api/shell/which path (absolute or starting with ~) {path, exists, rule, profile, label, dir, default}: the profile claude would start in there. rule is what the rules say (shared included), profile is null when claude keeps the default profile; default is true for ~/.claude, where CLAUDE_CONFIG_DIR stays unset

Issue kinds in /api/projects: orphan (folder gone), profile (content in a profile it does not belong to; includes from and to), unclassified (no rule matches).

Write

Endpoint Body
POST /api/projects/move project, from, to
POST /api/projects/relink project, profile, path
POST /api/projects/merge project, profile, into: a relink to the folder of another project of the same profile
POST /api/projects/delete project, profile
POST /api/rules match, profile (an id or shared), exact (optional: true for a rule on the folder match alone, a full path starting with / or ~)
POST /api/memory/save profile, project, file, content
POST /api/memory/move profile, project, file, to_profile, to_project
POST /api/memory/delete profile, project, file
POST /api/projects/share profile, project, from, shared (false: profile gets its own copy again, from not needed)
POST /api/conversations/continue profile, project, session, to, share (bool: share the project first when to does not see it): links the file snapshots, opens a terminal with claude --resume in to
POST /api/memory/share profile, project, from, shared (false separates: from not needed)
POST /api/conversations/move profile, project, session, to: one conversation and its file snapshots
POST /api/conversations/delete profile, project, session
POST /api/skills/create profile, name, description
POST /api/skills/save profile, name, content (the whole SKILL.md)
POST /api/skills/copy profile, name, to
POST /api/skills/copy-all profile, name: to every profile that lacks it, one backup
POST /api/skills/delete profile, name
POST /api/agents/save profile, fields (name, description, tools, disallowedTools, model, effort, permissionMode, maxTurns, color), prompt, old_name (to edit or rename; without it, creates)
POST /api/agents/save-raw profile, name, content: the whole file; name in it must stay the same
POST /api/agents/copy profile, name, to
POST /api/agents/copy-all profile, name: to every profile that lacks it, one backup
POST /api/agents/delete profile, name
POST /api/commands/save profile, name, content, new (true to create)
POST /api/commands/copy profile, name, to
POST /api/commands/copy-all profile, name: to every profile that lacks it, one backup
POST /api/commands/delete profile, name
POST /api/mcp/save profile, scope, name, config (object), old_name (to rename or edit)
POST /api/mcp/copy profile, scope, name, to (added to the target’s user scope)
POST /api/mcp/copy-all profile, scope, name: to every profile that lacks it, one backup
POST /api/mcp/delete profile, scope, name
POST /api/browser/local profile: adds the local browser (playwright: npx @playwright/mcp@latest --isolated) for every project
POST /api/browser/local/all to every profile that lacks it, one backup
POST /api/browser/chrome-off profile: sets claudeInChromeDefaultEnabled to false (never true: turning it on needs the user’s consent in /chrome)
POST /api/browser/chrome-off/all in every profile where it is on, one backup
POST /api/connectors/set profile, name, enabled: removes or adds the deny rule for the whole connector
POST /api/connectors/all profile, enabled: removes or sets disableClaudeAiConnectors
POST /api/connectors/forget profile, name: takes it off claudeAiMcpEverConnected (only when no deny rule blocks it)
POST /api/connectors/sync profile: takes off the list the connectors the last check found gone from the account
POST /api/github/save changes: [{profile, user?, name?, email?}]: the GitHub table, every change checked first, one backup
POST /api/github/account profile, user: makes a signed-in account the active one in the profile’s folder; a commit identity taken from the old account moves to the new one’s
POST /api/github/identity profile, name, email (both, or both empty for the one of its account): GIT_AUTHOR_* and GIT_COMMITTER_* in the profile’s env
POST /api/github/setup profile: gives it its own GitHub CLI folder now (the server does it at start)
POST /api/github/remove user: takes an account no profile uses off every folder; its keychain token stays
POST /api/sharing/everything profile, to (default: the source profile), settings (bool): every shareable item (settings.json only with settings), and every project of the two profiles
POST /api/sharing profile, item, shared (bool)
POST /api/plugins/enable profile, plugin (name@marketplace), enabled (bool): writes enabledPlugins where the value lives
POST /api/plugins/copy profile, plugin, to: copies a plugin installed for every project, with its marketplace, to another profile and enables it there
POST /api/profiles/import?label=…&id=… the request body is the exported .zip itself (Content-Type: application/zip, up to 2 GB), not JSON
POST /api/settings/field profile, key, value (null removes the setting)
POST /api/settings/permissions profile, rules: {allow, ask, deny} (lists of strings)
POST /api/settings/field/all profile, key: the profile’s value goes to every other profile, one backup
POST /api/settings/fields profile, values ({key: value}): several fields at once, all checked first, one backup
POST /api/statusline profile, mode (off, builtin, custom), parts, separator, colors, limits (used, the default, or left), command, padding, refreshInterval, hideVimModeIndicator
POST /api/statusline/all profile: its status line goes to every other profile, one backup
POST /api/hooks/save profile, hook (event, matcher, command, timeout, async, statusMessage, file: settings or local), at (file, event, group, index, fp of the hook to edit; without it, adds one). A changed file answers 409
POST /api/hooks/delete profile, at
POST /api/hooks/copy profile, at, to: into its settings.json
POST /api/hooks/copy-all profile, at: to every profile that does not run it, one backup
POST /api/keybindings/save profile, content: the whole file, checked first
POST /api/keybindings/delete profile: back to Claude Code’s default shortcuts
POST /api/keybindings/copy profile, to: replaces that profile’s file
POST /api/keybindings/copy-all profile: to every other profile, one backup
POST /api/storage/clean profile, days, categories (ids from GET /api/storage): what has been untouched for days goes into one backup; the answer adds freed (bytes)
POST /api/settings/permissions/all list, rule: added to settings.json of every profile, one backup
POST /api/settings/raw profile, file (settings or local), content (JSON text)
POST /api/settings/claude-md profile, content
POST /api/settings/global profile, key (autoUpdates), value (bool)
POST /api/profiles/create label, id, base (profile id or empty), include_projects, share (list)
POST /api/templates/save profile, name (letters, digits, spaces, ., -, _, up to 48)
POST /api/templates/delete name: the file goes to the backup
POST /api/templates/create name, label, id, share (as in /api/profiles/create: those items are linked to the source profile instead of being filled from the template): a new profile from the template, through the import code
POST /api/profiles/update id, label, command
POST /api/profiles/rename-folder id, name (clienti or .claude-clienti): the folder, the paths in its files, its launcher or alias, config.json and the links of other profiles into it
POST /api/profiles/delete id, merge_into (optional), force (skip the open-session check)
POST /api/backups/restore name
POST /api/backups/delete name
POST /api/backups/prune days (integer, 1 or more): permanently deletes the backups older than that
POST /api/backups/auto days (15, 30, 60 or 90): the automatic cleanup; it also prunes at once
POST /api/backups/keep name, kept (bool): keep a backup so no cleanup deletes it (and it cannot be deleted until kept is false), or let it go
POST /api/macapp (none): creates the Mac app or brings it up to date, on this server’s port; the same fields as GET /api/macapp, plus message and backup
POST /api/terminal terminal (one of choices): the terminal projects open in (terminal in config.json), with a backup
POST /api/terminal/open project, profile: opens the project’s folder in the terminal with Claude Code in that profile. Or path instead of project, for any folder (the Mac app’s Finder Quick Actions); without profile, the one the rules give it, else the one its project is in, else the first. Returns {message, profile}. Writes a script in ~/.cc-profiles/terminal/ that deletes itself when it runs; nothing the page sends is run as a command. An error when the folder is gone
POST /api/update (none): runs the update for this install, then restarts the server; {message, restarting}
POST /api/claude/install method (native, brew, brew-latest, npm)
POST /api/shell install (true or false): adds the profile by folder line to the shell rc files, or removes it. Without anything to change it returns a message and no backup

Example

PORT=4777
TOKEN=$(curl -s http://127.0.0.1:$PORT/ | grep -o 'const TOKEN = "[a-f0-9]*"' | cut -d'"' -f2)
curl -s -H "X-Token: $TOKEN" http://127.0.0.1:$PORT/api/profiles