> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ccs.kaitran.ca/llms.txt
> Use this file to discover all available pages before exploring further.

# File Locations

> Complete filesystem structure for CCS configuration, credentials, and data

# 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 (v13 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
```

<Note>
  Path precedence is `--config-dir` → `CCS_DIR` → legacy `CCS_HOME/.ccs` →
  default `~/.ccs/`.
</Note>

***

## 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:**

```yaml theme={null}
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:**

* [Configuration Schema](/reference/config-schema)
* [Migration Guide](/reference/migration-v6-v7)

***

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

```json theme={null}
{
  "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:**

```json theme={null}
{
  "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:**

```json theme={null}
{
  "my-gemini": {
    "activeCount": 1,
    "sessions": [...]
  }
}
```

**When Created:**

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

**Related:**

* [Port Isolation Pattern](/reference/config-schema#variant-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:**

```json theme={null}
{
  "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](/providers/concepts/overview#multi-account)
* `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](/reference/config-schema#variant-isolation-pattern)
* 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, 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](/reference/cli-commands#official-channels-configuration)
* `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](/reference/cli-commands#official-channels-configuration)
* `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:**

```json theme={null}
{
  "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:**

```json theme={null}
{
  "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:**

```yaml theme={null}
logging:
  enabled: true
  level: info
  rotate_mb: 10
  retain_days: 7
  redact: true
  live_buffer_size: 250
```

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

***

### `~/.ccs/cliproxy/logs/`

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

**Configuration:**

```yaml theme={null}
cliproxy:
  logging:
    enabled: false # Default: false
    request_log: false # Verbose request/response logging
```

<Warning>
  CLIProxy logs can consume significant disk space. Enable only for debugging.
</Warning>

**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](/reference/config-schema#cliproxyloggingenabled)
* [Dashboard Logs](/features/dashboard/logs)

***

## 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](/reference/migration-v6-v7)
* `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:**

```bash theme={null}
ccs migrate --rollback ~/.ccs/backup-v1-2025-12-15/
```

**List Backups:**

```bash theme={null}
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:**

```bash theme={null}
ccs sync    # Recreate symlinks/copies
```

**Related:**

* [Shared Data Architecture](/reference/architecture#shared-data)

***

## 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](/providers/concepts/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/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/channels/telegram/.env`     | Telegram bot token         | .env   | Yes (disables channel) |
| `~/.claude/channels/discord/.env`      | Discord bot token          | .env   | Yes (disables channel) |

***

## Cleanup Strategy

<Steps>
  <Step title="Regular Cleanup">
    ```bash theme={null}
    ccs cleanup
    ```

    Run monthly or when disk space is low.
  </Step>

  <Step title="Deep Cleanup">
    ```bash theme={null}
    rm -rf ~/.ccs/logs/*
    rm -rf ~/.ccs/cliproxy/logs/*
    rm -rf ~/.ccs/tmp/*
    rm -rf ~/.ccs/backup-*/
    ```

    Run if troubleshooting or resetting environment.
  </Step>

  <Step title="Complete Reset">
    ```bash theme={null}
    rm -rf ~/.ccs/
    ccs setup
    ```

    Only if reinstalling CCS completely.
  </Step>
</Steps>

***

## 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**  |

<Note>
  Keep `cliproxy.logging.enabled: false` (default) to prevent disk bloat.
</Note>

***

## Related Resources

* [Configuration Schema](/reference/config-schema)
* [Migration Guide](/reference/migration-v6-v7)
* [Troubleshooting](/reference/troubleshooting)
* [CLI Commands](/reference/cli-commands)