Skip to main content

​
Troubleshooting

Common issues and their solutions.

​
Installation Issues

​
Config File Not Found After npm Install

Symptom: 
Config file not found: /home/user/.ccs/config.json
Cause: Installed with --ignore-scripts flag. Solution: 
npm install -g @kaitranntt/ccs --force

​
PATH Not Updated

Symptom: ccs command not found after install. Solution:
  1. Restart your terminal
  2. Or manually add to PATH:
    • macOS/Linux: Add ~/.local/bin to PATH
    • Windows: Add %USERPROFILE%\.ccs to PATH

​
Windows-Specific

​
PowerShell Execution Policy

Error: “cannot be loaded because running scripts is disabled” Solution: 
Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

​
Claude CLI Not Found

where.exe claude
If missing, install from Claude docs.

​
Claude CLI in Non-Standard Location

​
Set CCS_CLAUDE_PATH

$env:CCS_CLAUDE_PATH = "D:\Program Files\Claude\claude.exe"
[Environment]::SetEnvironmentVariable("CCS_CLAUDE_PATH", $env:CCS_CLAUDE_PATH, "User")

​
Configuration Issues

​
Profile Not Found

Error: Profile 'foo' not found in ~/.ccs/config.json Solution: Add profile to config: 
{
  "profiles": {
    "foo": "~/.ccs/foo.settings.json"
  }
}

​
Settings File Missing

Error: Settings file not found: ~/.ccs/foo.settings.json Solution: Create the settings file or fix path in config.

​
Default Profile Missing

Error: Profile 'default' not found Solution: Add default profile: 
{
  "profiles": {
    "default": "~/.claude/settings.json"
  }
}

​
Common Problems

​
Claude CLI Not Found

Solution: Install from official documentation.

​
Permission Denied

chmod +x ~/.local/bin/ccs

​
Debug Mode

Enable verbose output: 
ccs --verbose glm
Shows:
  • Config file being read
  • Profile being selected
  • Settings file being used
  • Command being executed

​
Disable Colors

export NO_COLOR=1
ccs glm

​
Getting Help

  1. Check GitHub Issues
  2. Create new issue with:
    • Operating system
    • CCS version (ccs --version)
    • Exact error message
    • Steps to reproduce