Skip to main content

​
Installation

​
Prerequisites

macOS / Linux

Windows

  • PowerShell 5.1+ (pre-installed on Windows 10+)
  • Node.js 18+
  • Claude CLI

​
Install CCS

​
Verify Installation

ccs --version
# ccs/7.x.x darwin-arm64 node-v22.x.x

​
First Run

# Opens OAuth for default Claude account
ccs

# Or open the dashboard to configure providers and profiles
ccs config

# Run setup wizard
ccs setup

​
What Gets Installed

The postinstall script creates ~/.ccs/ with default templates: 
~/.ccs/
├── config.yaml             # Unified config (schema v12)
├── glm.settings.json       # Z.AI GLM profile template
├── instances/              # Claude account instances
├── cliproxy/               # OAuth provider auth tokens
└── shared/                 # Shared commands/skills/agents
If you run npm install --ignore-scripts, config files won’t be created automatically. Re-run without that flag or run ccs setup manually.

​
Upgrade

npm update -g @kaitranntt/ccs

# Or force reinstall
ccs update --force

​
Uninstall

npm uninstall -g @kaitranntt/ccs
This removes the CCS command but preserves your ~/.ccs/ configuration directory.

​
Platform Notes

​
macOS / Linux

No special configuration needed. CCS detects Claude CLI from PATH. 
# Override Claude CLI location if detection fails
export CCS_CLAUDE_PATH="/custom/path/to/claude"

​
Windows (PowerShell 5.1+)

CCS auto-detects Claude CLI via these paths in order: 
%USERPROFILE%\.local\bin\claude.exe
%APPDATA%\npm\claude.cmd
If detection fails, override with: 
$env:CCS_CLAUDE_PATH = "C:\custom\path\to\Claude.exe"

​
Docker

CCS can run in Docker containers. Mount your ~/.ccs and ~/.claude directories: 
docker run -v ~/.ccs:/root/.ccs -v ~/.claude:/root/.claude \
  node:22 npx @kaitranntt/ccs codex "your task"

​
Troubleshooting

​
ccs: command not found

npm global bin directory is not in PATH. Add it: 
# Find npm global bin
npm config get prefix
# e.g. /usr/local

# Add to PATH in ~/.bashrc or ~/.zshrc
export PATH="$(npm config get prefix)/bin:$PATH"

​
Permission Denied (Linux/macOS)

# Fix npm global permissions (recommended)
mkdir -p ~/.npm-global
npm config set prefix '~/.npm-global'
export PATH=~/.npm-global/bin:$PATH

# Then reinstall
npm install -g @kaitranntt/ccs

​
Next Steps

First Session

Authenticate and run your first query

Configuration

Understand config format and options

Provider Overview

Choose your first provider

Product Tour

See the dashboard and workflow surfaces before deeper setup