File Locations Reference

Complete reference for all CCS file paths and data storage locations. Understand where CCS stores configuration, cache, logs, and runtime data. Base Directory: ~/.ccs/

Configuration Files

`~/.ccs/config.yaml`

Purpose: Main unified configuration file (v6) 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
Copilot integration settings
Remote/local proxy configuration

Example:

version: 6
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/kimi.settings.json - Kimi 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 gemini --auth --add
List accounts: ccs gemini --accounts
Switch account: ccs gemini --use <nickname>
Rename account: ccs gemini --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/version.txt`

Purpose: Installed CLIProxyAPI binary version Format: Plain text (version string) Created: During CLIProxy installation Delete: Safe (will reinstall on next use) Content Example:

6.5.53

Use Cases:

Version mismatch detection
Auto-restart proxy on version change
Debug version conflicts

Related Commands:

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

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: Debug logs for CCS operations Format: Plain text log files Created: When CCS_DEBUG=1 is set Delete: Safe (via ccs cleanup) Log Files:

ccs.log - Main CCS operations
cliproxy.log - CLIProxy operations
auth.log - OAuth authentication flows
migration.log - Config migration operations

Rotation:

Max size: 10MB per file
Rotates to .log.1, .log.2, etc.
Keep last 5 rotations

Debug logs may contain sensitive information. Do not share logs without redacting credentials.

Cleanup:

ccs cleanup           # Remove old logs
rm -rf ~/.ccs/logs/*  # Manual cleanup

Enable Logging:

CCS_DEBUG=1 ccs gemini    # One-time
export CCS_DEBUG=1        # Persistent

`~/.ccs/cliproxy/logs/`

Purpose: CLIProxyAPI binary logs 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:

Config Schema: cliproxy.logging

Legacy Files (Pre-v6)

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

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

Migration Guide
ccs migrate command

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

Status: Deprecated in v6 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 → v6) Delete: Safe after verifying migration success Contains:

config.json - Legacy config
profiles.json - Legacy profiles
usage-cache.json - Pre-v6 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?
`config.yaml`	Main config	YAML	No (reset CCS)
`*.settings.json`	API profile env vars	JSON	Yes (profile breaks)
`cliproxy/sessions.json`	Session tracking	JSON	Yes (sessions reset)
`cliproxy/sessions-{port}.json`	Port-specific sessions	JSON	Yes
`cliproxy/accounts.json`	OAuth accounts	JSON	No (re-auth needed)
`cliproxy/config-{port}.yaml`	Port configs	YAML	Yes (regenerates)
`cliproxy/bin/version.txt`	Binary version	Text	Yes (reinstalls)
`cache/usage.json`	In-memory cache	JSON	Yes (rebuilds)
`.cache/usage-cache.json`	Persistent cache	JSON	Yes (rebuilds)
`logs/`	Debug logs	Text	Yes
`cliproxy/logs/`	CLIProxy logs	Text	Yes
`backup-*/`	Migration backups	Mixed	Yes (after verify)

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 Reference

File Locations Reference

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/version.txt`

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-v6)

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

CLI Reference

Config Reference

API Reference

Troubleshooting

Architecture

​File Locations Reference

​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/version.txt

​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-v6)

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

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/version.txt`

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-v6)

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