ccs/docs/troubleshooting.md

CCS Troubleshooting Guide

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

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