File Locations

Reference for CCS configuration, credentials, cache, logs, and runtime paths. Base Directory: ~/.ccs/ (override with CCS_DIR, or legacy CCS_HOME which appends .ccs)

Overview

~/.ccs/
├── config.yaml                    # Main config (v13 schema)
├── profiles.json                  # Profile registry (legacy, deprecated)
├── instances/                     # Account instances (isolated Claude dirs)
│   ├── work/
│   └── personal/
├── cliproxy/
│   ├── auth/                      # OAuth tokens (per provider)
│   │   └── xai-*.json             # xAI OAuth tokens
│   ├── config.yaml                # CLIProxy config (auto-generated)
│   ├── sessions.json              # Active sessions (global)
│   ├── accounts.json              # Provider account registry
│   └── bin/
│       ├── original/              # CLIProxyAPI binary + version.txt
│       └── plus/                  # CLIProxyAPIPlus binary + version.txt
├── model-catalog-cache.json       # Cached remote model catalog snapshot
├── shared/
│   ├── commands/                  # Custom commands (symlinked to instances)
│   ├── skills/                    # Custom skills (symlinked)
│   ├── agents/                    # Custom agents (symlinked)
│   ├── settings.json              # Link to canonical Claude settings
│   └── CLAUDE.md                  # Link to canonical user instructions
├── docker/                        # Docker deployment assets (auto-generated)
├── logs/
│   ├── current.jsonl              # CCS-owned structured log stream
│   └── archive/                   # Rotated structured log segments
├── xai.settings.json              # xAI provider settings when used
└── *.settings.json                # API profile settings files

~/.claude/
├── settings.json                  # Canonical Claude Code settings
├── CLAUDE.md                      # Canonical shared user instructions
└── channels/
    ├── telegram/.env              # TELEGRAM_BOT_TOKEN
    └── discord/.env               # DISCORD_BOT_TOKEN

Path precedence is --config-dir → CCS_DIR → legacy CCS_HOME/.ccs → default ~/.ccs/.

Configuration Files

`~/.ccs/config.yaml`

Purpose: Main unified configuration file (v13) Format: YAML Created: First run, or via ccs setup Delete: Only if resetting CCS completely Contains:

Default profile setting
Account-based profiles
API-based profiles
CLIProxy configuration
User preferences
WebSearch settings
Global environment variables
Quota management (v7+)
Thinking configuration (v8+)
Dashboard authentication
Image analysis configuration (v8+)
Deprecated Copilot compatibility settings
Remote/local proxy configuration
OpenAI-compatible local proxy configuration (v13+)
Browser automation configuration (v13+)

Example:

version: 13
default: work
accounts:
  work:
    created: "2025-12-01T10:00:00Z"
    last_used: "2025-12-15T14:30:00Z"
profiles:
  glm:
    type: "api"
    settings: "~/.ccs/glm.settings.json"
cliproxy:
  oauth_accounts:
    kai-personal: "kai@example.com"
  variants:
    my-gemini:
      provider: gemini
      port: 8318
proxy:
  profile_ports:
    hf: 3460
browser:
  claude:
    enabled: false
    policy: manual
    user_data_dir: "~/.ccs/browser/chrome-user-data"
    devtools_port: 9222
  codex:
    enabled: false
    policy: manual

Related:

`~/.ccs/*.settings.json`

Purpose: Profile-specific environment variables Format: JSON Created: Via ccs api create <name> or dashboard Delete: Safe to delete (profile becomes unusable) Naming Pattern: ~/.ccs/<profile-name>.settings.json Contains:

{
  "env": {
    "ANTHROPIC_BASE_URL": "https://api.example.com/anthropic",
    "ANTHROPIC_AUTH_TOKEN": "your-api-key",
    "ANTHROPIC_MODEL": "model-name"
  }
}

Security: Store securely, do not commit to version control Examples:

~/.ccs/glm.settings.json - GLM profile
~/.ccs/km.settings.json - Kimi for Coding profile
~/.ccs/xai.settings.json - xAI (Grok) provider settings
~/.ccs/custom-api.settings.json - Custom API profile

grok is an xAI CLI alias; it does not create grok.settings.json.

CLIProxy Files

`~/.ccs/cliproxy/auth/xai-*.json`

Purpose: xAI OAuth credentials Created: ccs xai --auth or ccs grok --auth The token JSON uses "type": "xai". Email metadata can be absent, so CCS uses an email when present or derives the account ID from the token filename suffix. The account registry stores xAI metadata at providers.xai in accounts.json; grok does not create separate token files or a registry bucket.

`~/.ccs/cliproxy/sessions.json`

Purpose: Global session tracking for CLIProxy Format: JSON Created: First CLIProxy session Delete: Safe (sessions will reset) Structure:

{
  "gemini": {
    "activeCount": 2,
    "sessions": [
      {
        "id": "sess-123",
        "pid": 12345,
        "started": "2025-12-15T10:00:00Z"
      }
    ]
  }
}

Use Cases:

Track concurrent sessions per provider
Prevent proxy shutdown with active sessions
Debug session leaks

Related: ~/.ccs/cliproxy/sessions-{port}.json for port-isolated variants

`~/.ccs/cliproxy/sessions-{port}.json`

Purpose: Port-specific session tracking for variants Format: JSON Created: First session on variant with custom port Delete: Safe (variant sessions will reset) Naming Pattern: ~/.ccs/cliproxy/sessions-8318.json Structure:

{
  "my-gemini": {
    "activeCount": 1,
    "sessions": [...]
  }
}

When Created:

Variant has port specified in config.yaml
Port range: 8318-8417

Related:

Port Isolation Pattern
cliproxy.variants.<name>.port config key

`~/.ccs/cliproxy/accounts.json`

Purpose: OAuth account registry for CLIProxy providers Format: JSON Created: First OAuth authentication Delete: Removes all OAuth accounts (requires re-auth) Structure:

{
  "version": 1,
  "providers": {
    "xai": {
      "default": "subject-one",
      "accounts": {
        "subject-one": {
          "nickname": "personal",
          "tokenFile": "xai-subject-one.json",
          "createdAt": "2025-12-01T10:00:00Z"
        }
      }
    }
  }
}

Operations:

Add account: ccs codex --auth --add
List accounts: ccs codex --accounts
Switch account: ccs codex --use <nickname>
Rename account: ccs codex --nickname <new-name>

Related:

Multi-Account Guide
cliproxy.oauth_accounts config key

`~/.ccs/cliproxy/config-{port}.yaml`

Purpose: Port-specific CLIProxy configuration Format: YAML Created: Automatically for variants with custom ports Delete: Safe (will regenerate on next use) Naming Pattern: ~/.ccs/cliproxy/config-8318.yaml Contains:

Provider-specific settings
Port configuration
Auth credentials (if variant-specific)
Logging settings

When Created:

Variant has port: 8318 in config.yaml
Allows concurrent variants without config conflicts

Related:

Variant Isolation
Port range: 8318-8417

`~/.ccs/cliproxy/bin/original/`

Purpose: CLIProxyAPI (original) binary directory Format: Directory containing executable + version file Created: During CLIProxy installation (backend: original) Delete: Safe (will reinstall on next use) Files:

cli-proxy-api — CLIProxyAPI binary
version.txt — Installed version string

Use Cases:

Standard providers: gemini, codex, xai, agy, iflow, kimi, claude
Minimal install without the plus-only provider set

`~/.ccs/cliproxy/bin/plus/`

Purpose: CLIProxyAPIPlus binary directory Format: Directory containing executable + version file Created: During CLIProxy installation (backend: plus) Delete: Safe (will reinstall on next use) Files:

cli-proxy-api-plus — CLIProxyAPIPlus binary
version.txt — Installed version string

Use Cases:

Plus-only providers including Kiro, Cursor, GitLab Duo, CodeBuddy, Kilo AI, Qoder, and deprecated GitHub Copilot compatibility
Opt-in backend; original remains the default local backend
Legacy deleted-upstream Plus installs migrate safely to the original backend

Related Commands:

ccs cliproxy - Show current version
ccs cliproxy --install <version> - Install specific version
ccs cliproxy --latest - Update to latest

`~/.ccs/model-catalog-cache.json`

Purpose: Cached model catalog snapshot from CLIProxy management sync Format: JSON Created: Via ccs cliproxy catalog refresh Delete: Safe (reverts to static catalog; regenerates on next refresh) TTL: 24 hours Contains:

Model IDs and metadata per provider
Remote-overridden fields merged with static fallback
Last-synced timestamp

Related Commands:

ccs cliproxy catalog - View cache status
ccs cliproxy catalog refresh - Force refresh
ccs cliproxy catalog reset - Clear cache (revert to static)

`~/.ccs/browser/chrome-user-data/`

Purpose: Recommended dedicated Chrome user-data directory for Claude Browser Attach Format: Browser profile directory Created: Via ccs browser setup or first managed setup path Delete: Safe if you want to reset browser automation state Use Cases:

Keeps automation browser state separate from your daily browser profile
Works with Chrome launched via --remote-debugging-port=9222

`~/.ccs/mcp/ccs-browser-server.cjs`

Purpose: Managed local MCP runtime for Claude Browser Attach Format: JavaScript runtime file Created: When CCS prepares browser automation tooling Delete: Safe; CCS recreates it when browser tooling is prepared again Related Commands:

ccs browser setup
ccs browser status
ccs browser doctor

Claude Channel Token Files

`~/.claude/channels/telegram/.env`

Purpose: Telegram bot token for Official Channels integration Format: .env file with TELEGRAM_BOT_TOKEN=<token> Created: Via ccs config channels --set-token telegram=<token> Delete: Disables Telegram channel auto-enable Content:

TELEGRAM_BOT_TOKEN=1234567890:AABBccDDeeFFggHH...

Related:

Official Channels
channels.selected config key

`~/.claude/channels/discord/.env`

Purpose: Discord bot token for Official Channels integration Format: .env file with DISCORD_BOT_TOKEN=<token> Created: Via ccs config channels --set-token discord=<token> Delete: Disables Discord channel auto-enable Content:

DISCORD_BOT_TOKEN=MTIzNDU2Nzg5MDEyMzQ1Njc4...

Related:

Official Channels
channels.selected config key

Cache Files

`~/.ccs/cache/usage.json`

Purpose: Usage analytics cache (in-memory format) Format: JSON Created: First Claude Code session Delete: Safe (analytics will reset) Structure:

{
  "daily": {
    "2025-12-15": {
      "requests": 42,
      "tokens": 125000,
      "models": {
        "claude-sonnet-4.5": 30,
        "gemini-2.5-pro": 12
      }
    }
  }
}

Use Cases:

Track daily/monthly usage
Model distribution analysis
Cost estimation

Related:

Dashboard Analytics page
/api/usage/* endpoints

`~/.ccs/.cache/usage-cache.json`

Purpose: Persistent usage cache (disk format) Format: JSON Created: On shutdown/periodic sync Delete: Safe (will rebuild from sessions) Difference from cache/usage.json:

cache/usage.json - In-memory, fast access
.cache/usage-cache.json - Persistent, survives restarts

Structure: Same as cache/usage.json Sync Behavior:

Write on graceful shutdown
Periodic sync every 5 minutes (if dirty)
Load on startup

`~/.ccs/cache/update-check.json`

Purpose: Update notification cache Format: JSON Created: First update check Delete: Safe (will re-check immediately) Structure:

{
  "lastCheck": "2025-12-15T10:00:00Z",
  "latestVersion": "7.3.0",
  "currentVersion": "7.2.5",
  "updateAvailable": true,
  "releaseUrl": "https://github.com/kaitranntt/ccs/releases/tag/v7.3.0"
}

Cache Duration: 24 hours Related:

ccs update - Manual update
Startup update notifications

Logs

`~/.ccs/logs/`

Purpose: CCS-owned structured runtime logs Format: JSONL Created: As CCS runtime events are written Delete: Safe (though you lose local history) Primary files:

current.jsonl - active structured log stream
archive/ - rotated segments pruned by logging.retain_days

Controlled by:

logging:
  enabled: true
  level: info
  rotate_mb: 10
  retain_days: 7
  redact: true
  live_buffer_size: 250

Structured logs may still contain sensitive operational context. Keep redaction enabled unless you are debugging locally and understand the tradeoff.

`~/.ccs/cliproxy/logs/`

Purpose: CLIProxy runtime log files Format: Plain text Created: When cliproxy.logging.enabled: true Delete: Safe (via ccs cleanup) Configuration:

cliproxy:
  logging:
    enabled: false # Default: false
    request_log: false # Verbose request/response logging

CLIProxy logs can consume significant disk space. Enable only for debugging.

Log Types:

error.log - Error messages only
request.log - HTTP request/response (if request_log: true)
debug.log - Verbose debug output

Related:

Legacy Files (Pre-v8)

`~/.ccs/config.json` (deprecated)

Status: Deprecated in v8 Migration: Automatically migrated to config.yaml Delete: After successful migration Related:

Migration Guide
ccs migrate command

`~/.ccs/profiles.json` (deprecated)

Status: Deprecated in v8 Migration: Merged into config.yaml under accounts section Delete: After successful migration

Backup Files

`~/.ccs/backup-v1-YYYY-MM-DD/`

Purpose: Migration backups Created: During config migration (v1 → v8) Delete: Safe after verifying migration success Contains:

config.json - Legacy config
profiles.json - Legacy profiles
usage-cache.json - Pre-v8 cache

Recovery:

ccs migrate --rollback ~/.ccs/backup-v1-2025-12-15/

List Backups:

ls -la ~/.ccs/backup-*/

Shared Data

`~/.ccs/shared/`

Shared profiles use ~/.ccs/shared/ as the managed access layer for resources whose canonical source is under ~/.claude/:

~/.ccs/shared/
├── commands/       -> ~/.claude/commands/
├── skills/         -> ~/.claude/skills/
├── agents/         -> ~/.claude/agents/
├── plugins/        # Managed shared plugin layout
├── settings.json   -> ~/.claude/settings.json
└── CLAUDE.md       -> ~/.claude/CLAUDE.md

On macOS and Linux these entries are symlinks. Windows can fall back to copies when symlinks are unavailable. ccs sync repairs the shared access layer. CLAUDE.md is shared by default for non-bare account profiles. CCS creates an empty canonical file when no copy exists. If the canonical file is missing, one unique existing variant is adopted; multiple distinct variants are kept as CLAUDE.md.ccs-shared-conflict[-N] files for explicit recovery. When the canonical file exists, it always wins and any divergent copy is also preserved with that suffix.

ccs sync

Instance Directories (Account Profiles)

`~/.ccs/instances/<name>/`

Account profiles use independent CLAUDE_CONFIG_DIR roots. Credentials, sessions, and history remain profile-specific, while non-bare profiles link managed shared resources at the instance root:

~/.ccs/instances/work/
├── .credentials.json       # Profile credentials
├── settings.json           -> ~/.ccs/shared/settings.json
├── CLAUDE.md               -> ~/.ccs/shared/CLAUDE.md
├── commands/               -> ~/.ccs/shared/commands/
├── skills/                 -> ~/.ccs/shared/skills/
├── agents/                 -> ~/.ccs/shared/agents/
├── session-env/            # Profile session state
├── todos/                  # Profile todo state
└── logs/                   # Profile logs

Profiles created with --bare, or switched to profile-local, do not use the managed shared links. See Claude Accounts.

Temporary Files

`~/.ccs/tmp/`

Purpose: Temporary files during operations Format: Various Created: During migrations, updates, etc. Delete: Safe (auto-cleaned) Auto-Cleanup:

On successful operation completion
Via ccs cleanup
On startup (files older than 24h)

Quick Reference Table

Path	Purpose	Format	Delete Safe?
`~/.ccs/config.yaml`	Main config	YAML	No (reset CCS)
`~/.ccs/*.settings.json`	API profile env vars	JSON	Yes (profile breaks)
`~/.ccs/xai.settings.json`	xAI provider settings	JSON	Yes (provider resets)
`~/.ccs/cliproxy/auth/xai-*.json`	xAI OAuth credentials	JSON	No (re-auth needed)
`~/.ccs/cliproxy/sessions.json`	Session tracking	JSON	Yes (sessions reset)
`~/.ccs/cliproxy/sessions-{port}.json`	Port-specific sessions	JSON	Yes
`~/.ccs/cliproxy/accounts.json`	OAuth accounts	JSON	No (re-auth needed)
`~/.ccs/cliproxy/config-{port}.yaml`	Port configs	YAML	Yes (regenerates)
`~/.ccs/cliproxy/bin/original/`	CLIProxyAPI binary dir	Binary	Yes (reinstalls)
`~/.ccs/cliproxy/bin/plus/`	CLIProxyAPIPlus binary dir	Binary	Yes (reinstalls)
`~/.ccs/browser/chrome-user-data/`	Browser attach profile	Dir	Yes
`~/.ccs/mcp/ccs-browser-server.cjs`	Browser MCP runtime	JS	Yes (recreates)
`~/.ccs/cache/usage.json`	In-memory cache	JSON	Yes (rebuilds)
`~/.ccs/.cache/usage-cache.json`	Persistent cache	JSON	Yes (rebuilds)
`~/.ccs/logs/`	Debug logs	Text	Yes
`~/.ccs/cliproxy/logs/`	CLIProxy logs	Text	Yes
`~/.ccs/backup-*/`	Migration backups	Mixed	Yes (after verify)
`~/.claude/CLAUDE.md`	Canonical user instructions	Markdown	No
`~/.claude/channels/telegram/.env`	Telegram bot token	.env	Yes (disables channel)
`~/.claude/channels/discord/.env`	Discord bot token	.env	Yes (disables channel)

Cleanup Strategy

Regular Cleanup

ccs cleanup

Run monthly or when disk space is low.

Deep Cleanup

rm -rf ~/.ccs/logs/*
rm -rf ~/.ccs/cliproxy/logs/*
rm -rf ~/.ccs/tmp/*
rm -rf ~/.ccs/backup-*/

Run if troubleshooting or resetting environment.

Complete Reset

rm -rf ~/.ccs/
ccs setup

Only if reinstalling CCS completely.

​File Locations

​Overview

​Configuration Files

​~/.ccs/config.yaml

​~/.ccs/*.settings.json

​CLIProxy Files

​~/.ccs/cliproxy/auth/xai-*.json

​~/.ccs/cliproxy/sessions.json

​~/.ccs/cliproxy/sessions-{port}.json

​~/.ccs/cliproxy/accounts.json

​~/.ccs/cliproxy/config-{port}.yaml

​~/.ccs/cliproxy/bin/original/

​~/.ccs/cliproxy/bin/plus/

​~/.ccs/model-catalog-cache.json

​~/.ccs/browser/chrome-user-data/

​~/.ccs/mcp/ccs-browser-server.cjs

​Claude Channel Token Files

​~/.claude/channels/telegram/.env

​~/.claude/channels/discord/.env

​Cache Files

​~/.ccs/cache/usage.json

​~/.ccs/.cache/usage-cache.json

​~/.ccs/cache/update-check.json

​Logs

​~/.ccs/logs/

​~/.ccs/cliproxy/logs/

​Legacy Files (Pre-v8)

​~/.ccs/config.json (deprecated)

​~/.ccs/profiles.json (deprecated)

​Backup Files

​~/.ccs/backup-v1-YYYY-MM-DD/

​Shared Data

​~/.ccs/shared/

​Instance Directories (Account Profiles)

​~/.ccs/instances/<name>/

​Temporary Files

​~/.ccs/tmp/

​Quick Reference Table

​Cleanup Strategy

​Related Resources

File Locations

Overview

Configuration Files

`~/.ccs/config.yaml`

`~/.ccs/*.settings.json`

CLIProxy Files

`~/.ccs/cliproxy/auth/xai-*.json`

`~/.ccs/cliproxy/sessions.json`

`~/.ccs/cliproxy/sessions-{port}.json`

`~/.ccs/cliproxy/accounts.json`

`~/.ccs/cliproxy/config-{port}.yaml`

`~/.ccs/cliproxy/bin/original/`

`~/.ccs/cliproxy/bin/plus/`

`~/.ccs/model-catalog-cache.json`

`~/.ccs/browser/chrome-user-data/`

`~/.ccs/mcp/ccs-browser-server.cjs`

Claude Channel Token Files

`~/.claude/channels/telegram/.env`

`~/.claude/channels/discord/.env`

Cache Files

`~/.ccs/cache/usage.json`

`~/.ccs/.cache/usage-cache.json`

`~/.ccs/cache/update-check.json`

Logs

`~/.ccs/logs/`

`~/.ccs/cliproxy/logs/`

Legacy Files (Pre-v8)

`~/.ccs/config.json` (deprecated)

`~/.ccs/profiles.json` (deprecated)

Backup Files

`~/.ccs/backup-v1-YYYY-MM-DD/`

Shared Data

`~/.ccs/shared/`

Instance Directories (Account Profiles)

`~/.ccs/instances/<name>/`

Temporary Files

`~/.ccs/tmp/`

Quick Reference Table

Cleanup Strategy

Related Resources