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
- Base URL
http://127.0.0.1:<port>. - Every
/api/request needs the headerX-Token: <token>. The token is generated at each start and embedded in the page served at/. - The
Hostheader must be127.0.0.1:<port>orlocalhost:<port>. - GET requests only read. POST requests take a JSON body and run one at a time.
- Errors return a non-2xx status and
{"error": "message"}. - Write operations return
{"message": "...", "backup": "~/.cc-profiles/backups/…", "backup_title": "…"}(the title is what Undo shows). profileis a profileid;projectis a folder name underprojects/(for example-Users-me-code-api).
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
Something wrong, unclear or missing on this page? Open an issue on GitHub