ccs/docs/en/configuration.md

CCS Configuration Guide

Automatic Configuration

The installer auto-creates config and profile templates during installation. The configuration system has been simplified for better maintainability and performance while maintaining all functionality.

macOS / Linux: ~/.ccs/config.json

Windows: %USERPROFILE%\.ccs\config.json

Recent Simplification Improvements

The configuration system has been optimized with these key improvements:

• Streamlined validation: Removed redundant security checks while maintaining essential validation
• Simplified error handling: Direct error messages instead of complex formatting
• Improved performance: Reduced function call overhead and complexity
• Enhanced maintainability: Consolidated logic with single sources of truth

Configuration Format

Basic Setup

{
  "profiles": {
    "glm": "~/.ccs/glm.settings.json",
    "default": "~/.claude/settings.json"
  }
}

Advanced Setup (Multiple Profiles)

{
  "profiles": {
    "glm": "~/.ccs/glm.settings.json",
    "haiku": "~/.ccs/haiku.settings.json",
    "custom": "~/.ccs/custom.settings.json",
    "default": "~/.claude/settings.json"
  }
}

Profile Configuration

GLM Profile Example

Location: ~/.ccs/glm.settings.json

{
  "env": {
    "ANTHROPIC_BASE_URL": "https://api.z.ai/api/anthropic",
    "ANTHROPIC_AUTH_TOKEN": "your_glm_api_key",
    "ANTHROPIC_MODEL": "glm-4.6",
    "ANTHROPIC_DEFAULT_OPUS_MODEL": "glm-4.6",
    "ANTHROPIC_DEFAULT_SONNET_MODEL": "glm-4.6",
    "ANTHROPIC_DEFAULT_HAIKU_MODEL": "glm-4.6"
  }
}

Claude (Default) Profile

• Uses ~/.claude/settings.json (your existing Claude CLI config)
• CCS never modifies this file (non-invasive approach)

How Configuration Works

1. CCS reads profile name from command line (defaults to "default")
2. Looks up settings file path in ~/.ccs/config.json
3. Executes claude --settings <file> [remaining-args]

No magic. No file modification. Pure delegation. Works identically across all platforms.

Environment Variables

CCS_CONFIG

Override default config location:

export CCS_CONFIG=~/my-custom-config.json
ccs glm

NO_COLOR

Disable colored terminal output:

export NO_COLOR=1
ccs glm

Use Cases:

• CI/CD pipelines
• Log files
• Terminals without color support
• Accessibility preferences

When NO_COLOR is set, CCS uses plain ASCII output without ANSI color codes.

Platform-Specific Notes

Windows Configuration

Windows uses the same file structure and approach as Linux/macOS.

Config format (~/.ccs/config.json):

{
  "profiles": {
    "glm": "~/.ccs/glm.settings.json",
    "default": "~/.claude/settings.json"
  }
}

macOS / Linux Configuration

Uses settings file paths with ~ expansion:

{
  "profiles": {
    "glm": "~/.ccs/glm.settings.json",
    "default": "~/.claude/settings.json"
  }
}

Each profile points to a Claude settings JSON file. Create settings files per Claude CLI docs.

Configuration Issues

Profile not found

Error: Profile 'foo' not found in ~/.ccs/config.json

Fix: Add profile to ~/.ccs/config.json:

{
  "profiles": {
    "foo": "~/.ccs/foo.settings.json"
  }
}

Settings file missing

Error: Settings file not found: ~/.ccs/foo.settings.json

Fix: Create settings file or fix path in config.

Default profile missing

Error: Profile 'default' not found in ~/.ccs/config.json

Fix: Add "default" profile or always specify profile name:

{
  "profiles": {
    "default": "~/.claude/settings.json"
  }
}