File Locations

Complete reference for all CCS file paths and data storage locations. Understand where CCS stores configuration, credentials, cache, logs, and runtime data. Base Directory: ~/.ccs/ (override with CCS_DIR, or with legacy CCS_HOME which appends .ccs)

Overview

~/.ccs/
├── config.yaml                    # Main config (v12 schema)
├── profiles.json                  # Profile registry (legacy, deprecated)
├── instances/                     # Account instances (isolated Claude dirs)
│   ├── work/
│   └── personal/
├── cliproxy/
│   ├── auth/                      # OAuth tokens (per provider)
│   ├── 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)
├── docker/                        # Docker deployment assets (auto-generated)
├── logs/
│   ├── current.jsonl              # CCS-owned structured log stream
│   └── archive/                   # Rotated structured log segments
└── *.settings.json                # API profile settings files

~/.claude/
├── settings.json                  # Claude Code settings (written by ccs persist)
└── 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 (v12) 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+)
Copilot integration settings
Remote/local proxy configuration

Example:

version: 12
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

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/custom-api.settings.json - Custom API profile

CLIProxy Files

`~/.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:

{
  "gemini": {
    "accounts": [
      {
        "nickname": "kai-personal",
        "email": "kai@example.com",
        "isDefault": true,
        "createdAt": "2025-12-01T10:00:00Z"
      }
    ]
  },
  "codex": {
    "accounts": [...]
  }
}

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, agy, qwen, iflow, kimi
Minimal install without Kiro/ghcp support

`~/.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 — CLIProxyAPIPlus binary
version.txt — Installed version string

Use Cases:

All providers including Kiro and ghcp
Recommended default (backend: plus)

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)

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/`

Purpose: Shared resources across profiles Format: Symlinks (macOS/Linux) or copies (Windows) Created: First run, or via ccs sync Delete: Breaks shared resources Structure:

~/.ccs/shared/
├── commands/    # Custom commands
├── skills/      # Custom skills
└── agents/      # Custom agents

Sync Command:

ccs sync    # Recreate symlinks/copies

Related:

Shared Data Architecture

Instance Directories (Account Profiles)

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

Purpose: Isolated Claude instances for account profiles Created: Via ccs auth create <name> Delete: Via ccs auth remove <name> --force Structure:

~/.ccs/instances/work/
├── .claude/
│   ├── settings.json    # Isolated settings
│   ├── sessions/        # Session data
│   ├── todolists/       # Todo lists
│   └── logs/            # Claude logs
└── shared/              # Symlinks to ~/.ccs/shared/

Isolation:

Each instance has independent CLAUDE_CONFIG_DIR
No config sharing between instances
Independent session management

Related:

Account Profiles Guide

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/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/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/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    # Remove old logs, temp files

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.

Disk Space Estimates

Component	Typical Size	Max Size
`config.yaml`	5-10 KB	50 KB
`*.settings.json`	1-2 KB each	10 KB
`sessions.json`	5-20 KB	100 KB
`accounts.json`	2-10 KB	50 KB
`cache/usage.json`	50-200 KB	5 MB
`logs/` (disabled)	0 KB	N/A
`logs/` (enabled)	100 KB-10 MB	50 MB
`cliproxy/logs/` (disabled)	0 KB	N/A
`cliproxy/logs/` (enabled)	1-100 MB	500 MB
Total (typical)	500 KB-1 MB	5-10 MB
Total (debug enabled)	100-500 MB	1-2 GB

Keep cliproxy.logging.enabled: false (default) to prevent disk bloat.

CLI Reference

Config Reference

API Reference

Troubleshooting

Architecture

​File Locations

​Overview

​Configuration Files

​~/.ccs/config.yaml

​~/.ccs/*.settings.json

​CLIProxy Files

​~/.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

​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

​Disk Space Estimates

​Related Resources

File Locations

Overview

Configuration Files

`~/.ccs/config.yaml`

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

CLIProxy Files

`~/.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`

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

Disk Space Estimates

Related Resources