cc-profiles Documentation PyPI GitHub Install

Working on cc-profiles

Claude Code’s on-disk formats

cc-profiles reads and writes files that Claude Code does not document as a public API. This page records what the app relies on, so that when Claude Code changes, it is clear what to check. Observed with Claude Code 2.1.x.

A profile folder

~/.claude/                       (or the folder in CLAUDE_CONFIG_DIR)
├── settings.json                user settings
├── settings.local.json          local overrides (win over settings.json)
├── CLAUDE.md                    global instructions
├── history.jsonl                prompt history (arrow up)
├── projects/<name>/             per-project data
│   ├── <sessionId>.jsonl        one conversation
│   └── memory/                  auto-memory
│       ├── MEMORY.md            index
│       └── <memory>.md
├── file-history/<sessionId>/    file snapshots of a conversation
├── session-env/<sessionId>/     a session's environment
├── todos/<sessionId>-agent-…    a session's task lists
├── shell-snapshots/  debug/  paste-cache/  image-cache/
├── keybindings.json             keyboard shortcuts (/keybindings)
├── skills/  plugins/  agents/  commands/  output-styles/
└── .credentials.json            login (on some systems; never copied)

The profile’s .claude.json is <dir>/.claude.json, except for the default profile: ~/.claude.json, in the home folder.

Project folder names

projects/<name> where <name> is the absolute project path with every character outside [A-Za-z0-9] replaced by -:

Path Folder
/Users/me/code/api -Users-me-code-api
/Users/me/Work Stuff/+site -Users-me-Work-Stuff--site

The mapping is not reversible; see Architecture.

Conversations

projects/<name>/<sessionId>.jsonl, one JSON object per line. cc-profiles reads the cwd field to learn the project path, the messages for the Conversations viewer and the token usage for the Usage tab; it never changes a line. File snapshots of the session are in file-history/<sessionId>/, and they must move together with the conversation.

Lines with "type": "assistant" carry the token usage of the reply, which the Usage tab adds up:

{"type": "assistant", "timestamp": "2026-10-06T09:12:00.000Z", "requestId": "req_…",
 "message": {"id": "msg_…", "model": "claude-opus-5-5",
             "usage": {"input_tokens": 12, "output_tokens": 840, "cache_creation_input_tokens": 3100,
                       "cache_read_input_tokens": 52000,
                       "cache_creation": {"ephemeral_5m_input_tokens": 3100, "ephemeral_1h_input_tokens": 0}}}}

One reply can span several lines (one per content block, all with the same message.id and requestId), and a resumed conversation copies earlier replies into its new file: count each message.id + requestId once. Subagents write their own conversations in projects/<name>/<sessionId>/subagents/*.jsonl.

Prompt history

history.jsonl, one object per prompt:

{"display": "fix the failing test", "timestamp": 1782679708827, "project": "/Users/me/code/api", "sessionId": "…"}

Claude Code filters it by project to offer arrow-up history in each folder. cc-profiles moves lines by project (an exact match or a sub-path), and avoids duplicates by (timestamp, display).

Per-project settings

The projects key of .claude.json, keyed by absolute path: trust, allowed tools, project MCP servers and more. Most other keys of .claude.json are internal state: caches, counters, tips seen. cc-profiles edits only projects, autoUpdates and the keys the /config panel keeps there (see Settings).

Memories

Each memory is Markdown with frontmatter:

---
name: api-uses-postgres
description: The API stores everything in Postgres, never in files
metadata:
  type: project
---
The body…

MEMORY.md has one line per memory:

- [API uses Postgres](api-uses-postgres.md) — never store data in files

cc-profiles finds index lines by the (file.md) link.

Hooks

The hooks key of settings.json and settings.local.json: an event, then groups with an optional matcher, then the hooks of each group.

{ "hooks": { "PostToolUse": [ { "matcher": "Edit|Write", "hooks": [ { "type": "command", "command": "npx prettier --write", "timeout": 30 } ] } ] } }

A hook’s type is command, prompt, agent, http or mcp_tool. A command hook also takes async, statusMessage, shell, args, once and more; cc-profiles edits command, timeout, async and statusMessage and keeps the rest. The events are HOOK_EVENTS in hooks.py, checked against HOOKS_SCHEMA_VERSION. "disableAllHooks": true turns off every hook, plugins’ included, and the status line. A plugin’s hooks are in its hooks/hooks.json, in the same shape.

Slash commands

commands/<name>.md is /<name>, and a subfolder adds a namespace: commands/git/commit.md is /git:commit. The file is the prompt, with optional frontmatter (description, argument-hint, allowed-tools, model); $ARGUMENTS is what is typed after the command. A plugin’s commands are /<plugin>:<name>. cc-profiles’ own /cc-profiles carries the line # managed by cc-profiles.

Keyboard shortcuts

keybindings.json in the profile folder:

{ "bindings": [ { "context": "Chat", "bindings": { "ctrl+e": "chat:externalEditor", "ctrl+g": "command:review", "ctrl+u": null } } ] }

A block per context, null to unbind a key, command:<name> to run a slash command (Chat context only). The contexts are CONTEXTS in keybindings.py.

Old files

At start, Claude Code deletes conversations older than cleanupPeriodDays (30 when unset). File snapshots, session environments and task lists are named after a session id. Once the session’s conversation is gone, Health → Disk space counts them as orphans.

Settings schema

Claude Code validates settings with a schema compiled into its binary. To see the accepted values of a setting:

strings -n 6 "$(readlink -f "$(which claude)")" | grep -o 'effortLevel:()=>[^)]*)' | head -1
# effortLevel:()=>B(["low","medium","high","xhigh"])

The values used by the UI are in SETTING_FIELDS in settings.py, checked against SCHEMA_VERSION. When updating them, keep any current value that is not in the new list as a selectable option.

Login

claude auth status prints JSON with loggedIn, email, authMethod, subscriptionType, orgName, apiProvider, analyticsDisabled and more. With CLAUDE_CONFIG_DIR set, it reports that profile. On macOS, credentials are stored in the login keychain, account $USER: Claude Code-credentials for ~/.claude used without CLAUDE_CONFIG_DIR, Claude Code-credentials-<first 8 hex digits of the SHA-256 of CLAUDE_CONFIG_DIR> for any other folder. Elsewhere, or when the keychain cannot be used, they are in .credentials.json in the profile folder. Both hold {"claudeAiOauth": {accessToken, refreshToken, expiresAt (ms), scopes, subscriptionType, rateLimitTier}}; after a logout the entry can stay with an empty accessToken.

Plan usage limits

/usage reads GET https://api.anthropic.com/api/oauth/usage with Authorization: Bearer <accessToken> and anthropic-beta: oauth-2025-04-20 (the sign-in needs the user:profile scope). The answer has a limits list (kind: session for the 5-hour window, weekly_all, weekly_scoped with scope.model.display_name; percent, resets_at, severity) and, older, five_hour, seven_day, seven_day_opus and seven_day_sonnet with utilization and resets_at. quota.py reads both, never refreshing the token.

claude.ai connectors

Connectors come from the claude.ai account, fetched by Claude Code at start. Each one is an MCP server named claude.ai <name>; its tools are mcp__claude_ai_<name>__<tool>, where every character other than letters, digits, _ and - becomes _, and runs of _ collapse into one (claude.ai vidIQ for Claude → mcp__claude_ai_vidIQ_for_Claude).

Checked against Claude Code 2.1.294.