ccs/docs/troubleshooting.md

CCS Troubleshooting Guide

npm Installation Issues

Config File Not Found After npm Install

Symptom: After npm install -g @kaitranntt/ccs, running ccs --version shows error:

Config file not found: /home/user/.ccs/config.json

Cause: You may have installed with --ignore-scripts flag, which skips the postinstall script that creates config files.

Solution:

# Reinstall without --ignore-scripts
npm install -g @kaitranntt/ccs --force

# Or manually run postinstall
node $(npm root -g)/@kaitranntt/ccs/scripts/postinstall.js

# Or use traditional installer
curl -fsSL ccs.kaitran.ca/install | bash  # macOS/Linux
irm ccs.kaitran.ca/install | iex           # Windows

Verify:

ls -la ~/.ccs/
# Should show: config.json, glm.settings.json

Check npm ignore-scripts Setting

# Check if ignore-scripts is enabled
npm config get ignore-scripts

# If true, disable it (or use --force on install)
npm config set ignore-scripts false

Windows-Specific Issues

PowerShell Execution Policy

If you see "cannot be loaded because running scripts is disabled":

# Check current policy
Get-ExecutionPolicy

# Allow current user to run scripts (recommended)
Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

# Or run with bypass (one-time)
powershell -ExecutionPolicy Bypass -File "$env:USERPROFILE\.ccs\ccs.ps1" glm

PATH not updated (Windows)

If ccs command not found after installation:

1. Restart your terminal
2. Or manually add to PATH:
   • Open "Edit environment variables for your account"
   • Add %USERPROFILE%\.ccs to User PATH
   • Restart terminal

Claude CLI not found (Windows)

# Check Claude CLI
where.exe claude

# If missing, install from Claude docs

Claude CLI in Non-Standard Location

If Claude CLI is installed on a different drive or custom location (common on Windows systems with D: drives):

Symptoms

╔═════════════════════════════════════════════╗
║  ERROR                                      ║
╚═════════════════════════════════════════════╝

Claude CLI not found

Searched:
  - CCS_CLAUDE_PATH: (not set)
  - System PATH: not found
  - Common locations: not found

Solution: Set CCS_CLAUDE_PATH

Step 1: Find Claude CLI Location

Windows:

# Search all drives
Get-ChildItem -Path C:\,D:\,E:\ -Filter claude.exe -Recurse -ErrorAction SilentlyContinue | Select-Object FullName

# Common locations to check manually
D:\Program Files\Claude\claude.exe
D:\Tools\Claude\claude.exe
D:\Users\<Username>\AppData\Local\Claude\claude.exe

Unix/Linux/macOS:

# Search system
sudo find / -name claude 2>/dev/null

# Or check specific locations
ls -la /usr/local/bin/claude
ls -la ~/.local/bin/claude
ls -la /opt/homebrew/bin/claude

Step 2: Set Environment Variable

Windows (PowerShell) - Permanent:

# Replace with your actual path
$ClaudePath = "D:\Program Files\Claude\claude.exe"

# Set for current session
$env:CCS_CLAUDE_PATH = $ClaudePath

# Set permanently for user
[Environment]::SetEnvironmentVariable("CCS_CLAUDE_PATH", $ClaudePath, "User")

# Restart terminal to apply

Unix (bash) - Permanent:

# Replace with your actual path
CLAUDE_PATH="/opt/custom/location/claude"

# Add to shell profile
echo "export CCS_CLAUDE_PATH=\"$CLAUDE_PATH\"" >> ~/.bashrc

# Reload profile
source ~/.bashrc

Unix (zsh) - Permanent:

# Replace with your actual path
CLAUDE_PATH="/opt/custom/location/claude"

# Add to shell profile
echo "export CCS_CLAUDE_PATH=\"$CLAUDE_PATH\"" >> ~/.zshrc

# Reload profile
source ~/.zshrc

Step 3: Verify Configuration

# Check environment variable is set
echo $CCS_CLAUDE_PATH        # Unix
$env:CCS_CLAUDE_PATH         # Windows

# Test CCS can find Claude
ccs --version

# Test with actual profile
ccs glm --version

Common Issues

Invalid Path:

Error: File not found: D:\Program Files\Claude\claude.exe

Fix: Double-check path, ensure file exists:

Test-Path "D:\Program Files\Claude\claude.exe"  # Windows
ls -la "/path/to/claude"                         # Unix

Directory Instead of File:

Error: Path is a directory: D:\Program Files\Claude

Fix: Path must point to claude.exe file, not directory:

# Wrong
$env:CCS_CLAUDE_PATH = "D:\Program Files\Claude"

# Right
$env:CCS_CLAUDE_PATH = "D:\Program Files\Claude\claude.exe"

Not Executable:

Error: File is not executable: /path/to/claude

Fix (Unix only):

chmod +x /path/to/claude

WSL-Specific Configuration

When using Windows Claude from WSL:

# Mount path format: /mnt/d/ for D: drive
export CCS_CLAUDE_PATH="/mnt/d/Program Files/Claude/claude.exe"

# Add to ~/.bashrc for persistence
echo 'export CCS_CLAUDE_PATH="/mnt/d/Program Files/Claude/claude.exe"' >> ~/.bashrc
source ~/.bashrc

Note: Spaces in Windows paths work correctly from WSL when quoted properly.

Debugging Detection

To see what CCS checked:

# Temporarily move claude out of PATH to test
# Then run ccs - error message shows what was checked

ccs --version
# Will show:
#   - CCS_CLAUDE_PATH: (status)
#   - System PATH: not found
#   - Common locations: not found

Alternative: Add to PATH Instead

If you prefer not using CCS_CLAUDE_PATH, add Claude directory to PATH:

Windows (PowerShell):

# Add D:\Program Files\Claude to PATH
$ClaudeDir = "D:\Program Files\Claude"
$env:Path += ";$ClaudeDir"
[Environment]::SetEnvironmentVariable("Path", $env:Path, "User")

# Restart terminal

Unix (bash):

# Add /opt/claude/bin to PATH
echo 'export PATH="/opt/claude/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc

Note: CCS_CLAUDE_PATH takes priority over PATH, allowing per-project overrides.

Installation Issues

BASH_SOURCE unbound variable error

This error occurs when running the installer in some shells or environments.

Fixed in latest version: The installer now handles both piped execution (curl | bash) and direct execution (./install.sh).

Solution: Upgrade to the latest version:

curl -fsSL https://raw.githubusercontent.com/kaitranntt/ccs/main/installers/install.sh | bash

Git worktree not detected

If installing from a git worktree or submodule, older versions may fail to detect the git repository.

Fixed in latest version: The installer now detects both .git directory (standard clone) and .git file (worktree/submodule).

Solution: Upgrade to the latest version or use the curl installation method.

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.

jq not installed

Error: jq is required but not installed

Fix: Install jq (see installation guide).

Note: The installer creates basic templates even without jq, but enhanced features require jq.

PATH Configuration Issues

Auto PATH Configuration

v2.2.0+ automatically configures shell PATH. If you see reload instructions after install, follow them:

For bash:

source ~/.bashrc

For zsh:

source ~/.zshrc

For fish:

source ~/.config/fish/config.fish

Or open new terminal window (PATH auto-loaded).

PATH Not Configured

If ccs command not found after install and reload:

Verify PATH entry exists:

# For bash/zsh
grep "\.local/bin" ~/.bashrc ~/.zshrc

# For fish
grep "\.local/bin" ~/.config/fish/config.fish

Manual fix (if auto-config failed):

Bash:

echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc

Zsh:

echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc

Fish:

echo 'set -gx PATH $HOME/.local/bin $PATH' >> ~/.config/fish/config.fish
source ~/.config/fish/config.fish

Wrong Shell Profile

If auto-config added to wrong file:

Find active profile:

echo $SHELL  # Shows current shell

Common scenarios:

• macOS bash uses ~/.bash_profile (not ~/.bashrc)
• Custom shells need manual config
• Tmux/screen may use different shell

Solution: Manually add PATH to correct profile file.

Shell Not Detected

If installer couldn't detect shell:

Symptoms:

• No PATH warning shown
• ccs command not found after install

Solution: Manual PATH setup (see above).

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"
  }
}

Common Problems

Claude CLI not found

Error Message:

╔═════════════════════════════════════════════╗
║  ERROR                                      ║
╚═════════════════════════════════════════════╝

claude command not found

Solution: Install Claude CLI from official documentation.

Permission denied

Error: Permission denied: ~/.local/bin/ccs

Solution: Make the script executable:

chmod +x ~/.local/bin/ccs

Config file not found

Error Message:

╔═════════════════════════════════════════════╗
║  ERROR                                      ║
╚═════════════════════════════════════════════╝

Config file not found: ~/.ccs/config.json

Solutions:
  1. Reinstall CCS:
     curl -fsSL ccs.kaitran.ca/install | bash

  2. Or create config manually:
     mkdir -p ~/.ccs
     cat > ~/.ccs/config.json << 'EOF'
{
  "profiles": {
    "glm": "~/.ccs/glm.settings.json",
    "default": "~/.claude/settings.json"
  }
}
EOF

Solution: Re-run installer or create config manually:

mkdir -p ~/.ccs
cat > ~/.ccs/config.json << 'EOF'
{
  "profiles": {
    "glm": "~/.ccs/glm.settings.json",
    "default": "~/.claude/settings.json"
  }
}
EOF

Getting Help

If you encounter issues not covered here:

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

Debug Mode

Enable verbose output to troubleshoot issues:

ccs --verbose glm

This will show:

• Which config file is being read
• Which profile is being selected
• Which settings file is being used
• The exact command being executed

Disable Colored Output

If color output causes issues in your terminal or logs:

export NO_COLOR=1
ccs glm

Use Cases:

• CI/CD environments
• Log file generation
• Terminals without color support
• Accessibility preferences