diff --git a/README.md b/README.md index 28fb6657..a6cd0ef9 100644 --- a/README.md +++ b/README.md @@ -26,7 +26,7 @@ One command. Zero downtime. No file editing. Right model, right task. ## Quick Start -**Install**: +### Install: **macOS / Linux**: ```bash @@ -35,24 +35,11 @@ curl -fsSL ccs.kaitran.ca/install | bash **Windows PowerShell**: ```powershell -irm ccs.kaitran.ca/install.ps1 | iex +irm ccs.kaitran.ca/install | iex ``` -**What Gets Installed**: -```bash -~/.ccs/ -├── ccs # Main executable -├── config.json # Profile configuration -├── glm.settings.json # GLM profile -└── .claude/ # Claude Code integration - ├── commands/ccs.md # /ccs meta-command - └── skills/ # Delegation skills -``` - -**Configure**: +**~/.ccs/config.json** (auto-created during install): ```json -# Installer creates config automatically -# Config: ~/.ccs/config.json { "profiles": { "glm": "~/.ccs/glm.settings.json", @@ -61,579 +48,38 @@ irm ccs.kaitran.ca/install.ps1 | iex } ``` -**Use**: +### Use: ```bash ccs # Use Claude subscription (default) ccs glm # Use GLM fallback - -# Utility commands ccs --version # Show CCS version -ccs --help # Show Claude CLI help ``` -## Why CCS? - -**Built for developers with both Claude subscription and GLM Coding Plan.** - -### Two Real Use Cases - -#### 1. Task-Appropriate Model Selection -**Claude Sonnet 4.5** excels at: -- Complex architectural decisions -- System design and planning -- Debugging tricky issues -- Code reviews requiring deep reasoning - -**GLM 4.6** works great for: -- Simple bug fixes -- Straightforward implementations -- Routine refactoring -- Documentation writing - -**With CCS**: Switch models based on task complexity, maximize quality while managing costs. - -```bash -ccs # Planning new feature architecture -# Got the plan? Implement with GLM: -ccs glm # Write the straightforward code -``` - -#### 2. Rate Limit Management -If you have both Claude subscription and GLM Coding Plan, you know the pain: -- Claude hits rate limit mid-project -- You manually copy GLM config to `~/.claude/settings.json` -- 5 minutes later, need to switch back -- Repeat 10x per day - -**CCS solves this**: -- One command to switch: `ccs` (default) or `ccs glm` (fallback) -- Keep both configs saved as profiles -- Switch in <1 second -- No file editing, no copy-paste, no mistakes - -### Features -- Instant profile switching (Claude ↔ GLM) -- Pass-through all Claude CLI args -- Smart setup: detects your current provider -- Auto-creates configs during install -- No proxies, no magic—just bash + jq - -## New: Task Delegation - -**CCS now includes intelligent task delegation** via the `/ccs` meta-command: - -```bash -# Delegate planning to GLM (saves Sonnet tokens) -/ccs glm /plan "add user authentication" - -# Delegate coding to GLM -/ccs glm /code "implement auth endpoints" - -# Quick questions with Haiku -/ccs haiku /ask "explain this error" -``` - -**Documentation**: -- Command reference: [`commands/ccs.md`](commands/ccs.md) -- Delegation patterns: [`skills/ccs-delegation.md`](skills/ccs-delegation.md) - -**Benefits**: -- ✅ Save tokens by delegating simple tasks to cheaper models -- ✅ Use right model for each task automatically -- ✅ Reusable commands across all projects (user-scope) -- ✅ Seamless integration with existing workflows - -## Installation - -### One-Liner (Recommended) - -**macOS / Linux**: -```bash -# Short URL (via CloudFlare) -curl -fsSL ccs.kaitran.ca/install | bash - -# Or direct from GitHub -curl -fsSL https://raw.githubusercontent.com/kaitranntt/ccs/main/installers/install.sh | bash -``` - -**Windows PowerShell**: -```powershell -# Short URL (via CloudFlare) -irm ccs.kaitran.ca/install.ps1 | iex - -# Or direct from GitHub -irm https://raw.githubusercontent.com/kaitranntt/ccs/main/installers/install.ps1 | iex -``` - -**Note**: -- Unix installer supports both direct execution (`./install.sh`) and piped installation (`curl | bash`) -- Windows installer requires PowerShell 5.1+ (pre-installed on Windows 10+) - -### Git Clone - -**macOS / Linux**: -```bash -git clone https://github.com/kaitranntt/ccs.git -cd ccs -./installers/install.sh -``` - -**Windows PowerShell**: -```powershell -git clone https://github.com/kaitranntt/ccs.git -cd ccs -.\installers\install.ps1 -``` - -**Note**: Works with git worktrees and submodules - the installer detects both `.git` directory and `.git` file. - -### Manual - -**macOS / Linux**: -```bash -# Download script -curl -fsSL https://raw.githubusercontent.com/kaitranntt/ccs/main/ccs -o ~/.local/bin/ccs -chmod +x ~/.local/bin/ccs - -# Ensure ~/.local/bin in PATH -export PATH="$HOME/.local/bin:$PATH" -``` - -**Windows PowerShell**: -```powershell -# Create directory -New-Item -ItemType Directory -Force -Path "$env:USERPROFILE\.ccs" - -# Download script -Invoke-WebRequest -Uri "https://raw.githubusercontent.com/kaitranntt/ccs/main/ccs.ps1" -OutFile "$env:USERPROFILE\.ccs\ccs.ps1" - -# Add to PATH (restart terminal after) -$Path = [Environment]::GetEnvironmentVariable("Path", "User") -[Environment]::SetEnvironmentVariable("Path", "$Path;$env:USERPROFILE\.ccs", "User") -``` - -### Upgrade - -**macOS / Linux**: -```bash -# From git clone -cd ccs && git pull && ./install.sh - -# From curl install -curl -fsSL ccs.kaitran.ca/install | bash -``` - -**Windows PowerShell**: -```powershell -# From git clone -cd ccs -git pull -.\install.ps1 - -# From irm install -irm ccs.kaitran.ca/install.ps1 | iex -``` - -## Configuration - -The installer auto-creates config and profile templates during installation: - -**macOS / Linux**: `~/.ccs/config.json` -**Windows**: `%USERPROFILE%\.ccs\config.json` - -### macOS / Linux Configuration - -Uses settings file paths: - -```json -{ - "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](https://docs.claude.com/en/docs/claude-code/installation). - -### Windows Configuration - -Windows uses the same file structure and approach as Linux/macOS. - -**Config format** (`~/.ccs/config.json`): -```json -{ - "profiles": { - "glm": "~/.ccs/glm.settings.json", - "default": "~/.claude/settings.json" - } -} -``` - -**GLM profile** (`~/.ccs/glm.settings.json`): -```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)**: -- Uses `~/.claude/settings.json` (your existing Claude CLI config) -- CCS never modifies this file (non-invasive approach) - -**How it works**: -- CCS reads the config to find your profile's settings file -- Executes `claude --settings ` with your selected profile -- Simple, clean, cross-platform - -## Usage - -### Basic - -```bash -# Works on macOS, Linux, and Windows -ccs # Use Claude subscription (default) -ccs glm # Use GLM fallback -``` - -**Windows Note**: Commands work identically in PowerShell, CMD, and Git Bash. - -### With Arguments - -All args after profile name pass directly to Claude CLI: - -```bash -ccs glm --verbose -ccs /plan "add feature" -ccs glm /code "implement feature" -``` - -### Custom Config Location - -```bash -export CCS_CONFIG=~/my-custom-config.json -ccs glm -``` - -## Use Cases - -### Real Workflow: Task-Based Model Selection - -**Scenario**: Building a new payment integration feature - -```bash -# Step 1: Architecture & Planning (needs Claude's intelligence) -ccs -/plan "Design payment integration with Stripe, handle webhooks, errors, retries" -# → Claude Sonnet 4.5 thinks deeply about edge cases, security, architecture - -# Step 2: Implementation (straightforward coding, use GLM) -ccs glm -/code "implement the payment webhook handler from the plan" -# → GLM 4.6 writes the code efficiently, saves Claude usage - -# Step 3: Code Review (needs deep analysis) -ccs -/review "check the payment handler for security issues" -# → Claude Sonnet 4.5 catches subtle vulnerabilities - -# Step 4: Bug Fixes (simple) -ccs glm -/fix "update error message formatting" -# → GLM 4.6 handles routine fixes -``` - -**Result**: Best model for each task, lower costs, better quality. - -### Real Workflow: Rate Limit Management - -```bash -# Working on complex refactoring with Claude -ccs -/plan "refactor authentication system" - -# Claude hits rate limit mid-task -# → Error: Rate limit exceeded - -# Switch to GLM instantly -ccs glm -# Continue working without interruption - -# Rate limit resets? Switch back -ccs -``` - -### Configuration Examples - -**Standard setup** (Claude sub + GLM): -```json -{ - "profiles": { - "glm": "~/.ccs/glm.settings.json", - "default": "~/.claude/settings.json" - } -} -``` - -**Advanced setup** (multiple profiles): -```json -{ - "profiles": { - "glm": "~/.ccs/glm.settings.json", - "haiku": "~/.ccs/haiku.settings.json", - "custom": "~/.ccs/custom.settings.json", - "default": "~/.claude/settings.json" - } -} -``` - -## How It Works - -1. Reads profile name (defaults to "default" if omitted) -2. Looks up settings file path in `~/.ccs/config.json` -3. Executes `claude --settings [remaining-args]` - -No magic. No file modification. Pure delegation. Works identically across all platforms. - -## Requirements - -### macOS / Linux -- `bash` 3.2+ -- `jq` (JSON processor) -- [Claude CLI](https://docs.claude.com/en/docs/claude-code/installation) - -### Windows -- PowerShell 5.1+ (pre-installed on Windows 10+) -- [Claude CLI](https://docs.claude.com/en/docs/claude-code/installation) - -### Installing jq (macOS / Linux only) - -```bash -# macOS -brew install jq - -# Ubuntu/Debian -sudo apt install jq - -# Fedora -sudo dnf install jq - -# Arch -sudo pacman -S jq -``` - -**Note**: Windows version uses PowerShell's built-in JSON support - no jq required. - -## Troubleshooting - -### Windows-Specific Issues - -#### PowerShell Execution Policy - -If you see "cannot be loaded because running scripts is disabled": - -```powershell -# 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) - -```powershell -# 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: -```bash -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`: -```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 Requirements). - -**Note**: The installer creates basic templates even without jq, but enhanced features require jq. - -### Environment Issues - -#### PATH not set - -``` -⚠️ Warning: ~/.local/bin is not in PATH -``` - -**Fix**: Add to `~/.bashrc` or `~/.zshrc`: -```bash -export PATH="$HOME/.local/bin:$PATH" -``` -Then `source ~/.bashrc` or restart shell. - -#### Default profile missing - -``` -Error: Profile 'default' not found in ~/.ccs/config.json -``` - -**Fix**: Add "default" profile or always specify profile name: -```json -{ - "profiles": { - "default": "~/.claude/settings.json" - } -} -``` - -## Uninstallation - -### macOS / Linux - -**Using installed command**: -```bash -ccs-uninstall -``` - -**One-liner**: -```bash -# Short URL -curl -fsSL ccs.kaitran.ca/uninstall | bash - -# Or direct from GitHub -curl -fsSL https://raw.githubusercontent.com/kaitranntt/ccs/main/installers/uninstall.sh | bash -``` - -**Manual**: -```bash -rm ~/.local/bin/ccs -rm ~/.local/bin/ccs-uninstall -rm -rf ~/.ccs # If you want to remove all CCS files -``` - -### Windows PowerShell - -**Using installed command**: -```powershell -ccs-uninstall -``` - -**One-liner**: -```powershell -# Short URL -irm ccs.kaitran.ca/uninstall.ps1 | iex - -# Or direct from GitHub -irm https://raw.githubusercontent.com/kaitranntt/ccs/main/installers/uninstall.ps1 | iex -``` - -**Manual**: -```powershell -# Remove scripts -Remove-Item "$env:USERPROFILE\.ccs\ccs.ps1" -Force -Remove-Item "$env:USERPROFILE\.ccs\uninstall.ps1" -Force - -# Remove from PATH -$Path = [Environment]::GetEnvironmentVariable("Path", "User") -$NewPath = ($Path -split ';' | Where-Object { $_ -ne "$env:USERPROFILE\.ccs" }) -join ';' -[Environment]::SetEnvironmentVariable("Path", $NewPath, "User") - -# Optional: Remove all CCS files -Remove-Item "$env:USERPROFILE\.ccs" -Recurse -Force -``` - -## Contributing - -PRs welcome! Keep it simple (KISS principle). - -**Guidelines**: -- Maintain bash 3.2+ compatibility (Unix) and PowerShell 5.1+ (Windows) -- No dependencies beyond jq (Unix) or built-in PowerShell (Windows) -- Test on macOS, Linux, and Windows -- Follow existing code style - ## Philosophy - **YAGNI**: No features "just in case" - **KISS**: Simple bash, no complexity - **DRY**: One source of truth (config) -This tool does ONE thing well: map profile names to settings files. +## Uninstall -## License +**macOS / Linux**: +```bash +curl -fsSL ccs.kaitran.ca/uninstall | bash +``` -MIT © [Kai Tran](https://github.com/kaitranntt) +**Windows PowerShell**: +```powershell +irm ccs.kaitran.ca/uninstall | iex +``` -## Links +**Learn more**: Complete documentation in [docs/](./docs/) +- [Installation Guide](./docs/installation.md) +- [Configuration](./docs/configuration.md) +- [Usage Examples](./docs/usage.md) +- [Troubleshooting](./docs/troubleshooting.md) +- [Contributing](./docs/contributing.md) -- [Claude CLI Docs](https://docs.claude.com/en/docs/claude-code/installation) -- [Report Issues](https://github.com/kaitranntt/ccs/issues) -- [Changelog](https://github.com/kaitranntt/ccs/releases) +--- + +*Built with ❤️ by [Kai Tran](https://github.com/kaitranntt)* \ No newline at end of file diff --git a/VERSION b/VERSION index eca07e4c..ac2cdeba 100644 --- a/VERSION +++ b/VERSION @@ -1 +1 @@ -2.1.2 +2.1.3 diff --git a/docs/configuration.md b/docs/configuration.md new file mode 100644 index 00000000..1c0bcdfb --- /dev/null +++ b/docs/configuration.md @@ -0,0 +1,145 @@ +# CCS Configuration Guide + +## Automatic Configuration + +The installer auto-creates config and profile templates during installation: + +**macOS / Linux**: `~/.ccs/config.json` + +**Windows**: `%USERPROFILE%\.ccs\config.json` + +## Configuration Format + +### Basic Setup + +```json +{ + "profiles": { + "glm": "~/.ccs/glm.settings.json", + "default": "~/.claude/settings.json" + } +} +``` + +### Advanced Setup (Multiple Profiles) + +```json +{ + "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` + +```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 [remaining-args]` + +No magic. No file modification. Pure delegation. Works identically across all platforms. + +## Custom Config Location + +```bash +export CCS_CONFIG=~/my-custom-config.json +ccs glm +``` + +## Platform-Specific Notes + +### Windows Configuration + +Windows uses the same file structure and approach as Linux/macOS. + +**Config format** (`~/.ccs/config.json`): +```json +{ + "profiles": { + "glm": "~/.ccs/glm.settings.json", + "default": "~/.claude/settings.json" + } +} +``` + +### macOS / Linux Configuration + +Uses settings file paths with `~` expansion: + +```json +{ + "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](https://docs.claude.com/en/docs/claude-code/installation). + +## Configuration Issues + +### Profile not found + +``` +Error: Profile 'foo' not found in ~/.ccs/config.json +``` + +**Fix**: Add profile to `~/.ccs/config.json`: +```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: +```json +{ + "profiles": { + "default": "~/.claude/settings.json" + } +} +``` \ No newline at end of file diff --git a/docs/contributing.md b/docs/contributing.md new file mode 100644 index 00000000..3757ecde --- /dev/null +++ b/docs/contributing.md @@ -0,0 +1,182 @@ +# CCS Contributing Guide + +## Development Guidelines + +### Philosophy + +CCS follows these core principles: + +- **YAGNI**: No features "just in case" +- **KISS**: Simple bash, no complexity +- **DRY**: One source of truth (config) + +This tool does ONE thing well: map profile names to settings files. + +### Code Standards + +#### Compatibility Requirements + +- **Unix**: bash 3.2+ compatibility +- **Windows**: PowerShell 5.1+ compatibility +- **Dependencies**: Only jq (Unix) or built-in PowerShell (Windows) + +#### Code Style + +**Bash (Unix)**: +- Use `#!/usr/bin/env bash` shebang +- Quote variables: `"$VAR"` not `$VAR` +- Use `[[ ]]` for tests, not `[ ]` +- Follow existing indentation and naming patterns + +**PowerShell (Windows)**: +- Use `CmdletBinding` and proper parameter handling +- Follow PowerShell verb-noun convention +- Use proper error handling with `try/catch` +- Maintain compatibility with PowerShell 5.1+ + +### Testing + +#### Platform Testing + +Test on all platforms before submitting PR: +- macOS (bash) +- Linux (bash) +- Windows (PowerShell, CMD, Git Bash) + +#### Test Scenarios + +1. **Basic functionality**: + ```bash + ccs # Should use default profile + ccs glm # Should use GLM profile + ccs --version # Should show version + ``` + +2. **With arguments**: + ```bash + ccs glm --help + ccs /plan "test" + ``` + +3. **Error handling**: + ```bash + ccs invalid-profile # Should show error + ccs --invalid-flag # Should pass through to Claude + ``` + +### Submission Process + +#### Before Submitting + +1. Fork the repository +2. Create a feature branch: `git checkout -b feature-name` +3. Make your changes +4. Test on all platforms +5. Ensure existing tests pass + +#### Pull Request Requirements + +- Clear description of changes +- Testing instructions if applicable +- Link to relevant issues +- Follow existing commit message style + +#### Commit Message Style + +``` +type(scope): description + +[optional body] + +[optional footer] +``` + +Examples: +``` +fix(installer): handle git worktree detection +feat(config): support custom config location +docs(readme): update installation instructions +``` + +### Development Setup + +#### Local Development + +```bash +# Clone your fork +git clone https://github.com/yourusername/ccs.git +cd ccs + +# Create feature branch +git checkout -b your-feature-name + +# Make changes +# Test locally with ./ccs + +# Run tests +./test.sh # if available +``` + +#### Testing Installer + +```bash +# Test Unix installer +./installers/install.sh + +# Test Windows installer (in PowerShell) +.\installers\install.ps1 +``` + +### Areas for Contribution + +#### Wanted Features + +1. **Additional profile support**: + - Custom profile validation + - Profile switching shortcuts + +2. **Enhanced error handling**: + - Better error messages + - Recovery suggestions + +3. **Documentation**: + - More examples + - Integration guides + +#### Bug Fixes + +- Installer issues on different platforms +- Edge cases in config parsing +- Windows-specific compatibility + +### Review Process + +1. **Automated checks**: + - Syntax validation + - Basic functionality tests + +2. **Manual review**: + - Code quality and style + - Platform compatibility + - Philosophy alignment + +3. **Testing**: + - Cross-platform verification + - Integration testing + +### Community + +#### Getting Help + +- GitHub Issues: Report bugs or request features +- Discussions: Ask questions or share ideas + +#### Code of Conduct + +Be respectful, constructive, and focused on the project's philosophy of simplicity and reliability. + +--- + +**Thank you for contributing to CCS!** + +Remember: Keep it simple, test thoroughly, and stay true to the YAGNI/KISS/DRY philosophy. \ No newline at end of file diff --git a/docs/installation.md b/docs/installation.md new file mode 100644 index 00000000..e4aa7f7b --- /dev/null +++ b/docs/installation.md @@ -0,0 +1,139 @@ +# CCS Installation Guide + +## One-Liner Installation (Recommended) + +### macOS / Linux + +```bash +# Short URL (via CloudFlare) +curl -fsSL ccs.kaitran.ca/install | bash + +# Or direct from GitHub +curl -fsSL https://raw.githubusercontent.com/kaitranntt/ccs/main/installers/install.sh | bash +``` + +### Windows PowerShell + +```powershell +# Short URL (via CloudFlare) +irm ccs.kaitran.ca/install.ps1 | iex + +# Or direct from GitHub +irm https://raw.githubusercontent.com/kaitranntt/ccs/main/installers/install.ps1 | iex +``` + +**Note**: +- Unix installer supports both direct execution (`./install.sh`) and piped installation (`curl | bash`) +- Windows installer requires PowerShell 5.1+ (pre-installed on Windows 10+) + +## Git Clone Installation + +### macOS / Linux + +```bash +git clone https://github.com/kaitranntt/ccs.git +cd ccs +./installers/install.sh +``` + +### Windows PowerShell + +```powershell +git clone https://github.com/kaitranntt/ccs.git +cd ccs +.\installers\install.ps1 +``` + +**Note**: Works with git worktrees and submodules - the installer detects both `.git` directory and `.git` file. + +## Manual Installation + +### macOS / Linux + +```bash +# Download script +curl -fsSL https://raw.githubusercontent.com/kaitranntt/ccs/main/ccs -o ~/.local/bin/ccs +chmod +x ~/.local/bin/ccs + +# Ensure ~/.local/bin in PATH +export PATH="$HOME/.local/bin:$PATH" +``` + +### Windows PowerShell + +```powershell +# Create directory +New-Item -ItemType Directory -Force -Path "$env:USERPROFILE\.ccs" + +# Download script +Invoke-WebRequest -Uri "https://raw.githubusercontent.com/kaitranntt/ccs/main/ccs.ps1" -OutFile "$env:USERPROFILE\.ccs\ccs.ps1" + +# Add to PATH (restart terminal after) +$Path = [Environment]::GetEnvironmentVariable("Path", "User") +[Environment]::SetEnvironmentVariable("Path", "$Path;$env:USERPROFILE\.ccs", "User") +``` + +## What Gets Installed + +```bash +~/.ccs/ +├── ccs # Main executable +├── config.json # Profile configuration +├── glm.settings.json # GLM profile +└── .claude/ # Claude Code integration + ├── commands/ccs.md # /ccs meta-command + └── skills/ # Delegation skills +``` + +## Upgrade CCS + +### macOS / Linux + +```bash +# From git clone +cd ccs && git pull && ./install.sh + +# From curl install +curl -fsSL ccs.kaitran.ca/install | bash +``` + +### Windows PowerShell + +```powershell +# From git clone +cd ccs +git pull +.\install.ps1 + +# From irm install +irm ccs.kaitran.ca/install.ps1 | iex +``` + +## Requirements + +### macOS / Linux +- `bash` 3.2+ +- `jq` (JSON processor) +- [Claude CLI](https://docs.claude.com/en/docs/claude-code/installation) + +### Windows +- PowerShell 5.1+ (pre-installed on Windows 10+) +- [Claude CLI](https://docs.claude.com/en/docs/claude-code/installation) + +### Installing jq (macOS / Linux only) + +```bash +# macOS +brew install jq + +# Ubuntu/Debian +sudo apt install jq + +# Fedora +sudo dnf install jq + +# Arch +sudo pacman -S jq +``` + +**Note**: Windows version uses PowerShell's built-in JSON support - no jq required. \ No newline at end of file diff --git a/docs/troubleshooting.md b/docs/troubleshooting.md new file mode 100644 index 00000000..cd28dcc4 --- /dev/null +++ b/docs/troubleshooting.md @@ -0,0 +1,180 @@ +# CCS Troubleshooting Guide + +## Windows-Specific Issues + +### PowerShell Execution Policy + +If you see "cannot be loaded because running scripts is disabled": + +```powershell +# 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) + +```powershell +# 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: +```bash +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`: +```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. + +## Environment Issues + +### PATH not set + +``` +⚠️ Warning: ~/.local/bin is not in PATH +``` + +**Fix**: Add to `~/.bashrc` or `~/.zshrc`: +```bash +export PATH="$HOME/.local/bin:$PATH" +``` +Then `source ~/.bashrc` or restart shell. + +### Default profile missing + +``` +Error: Profile 'default' not found in ~/.ccs/config.json +``` + +**Fix**: Add "default" profile or always specify profile name: +```json +{ + "profiles": { + "default": "~/.claude/settings.json" + } +} +``` + +## Common Problems + +### Claude CLI not found + +``` +Error: claude command not found +``` + +**Solution**: Install Claude CLI from [official documentation](https://docs.claude.com/en/docs/claude-code/installation). + +### Permission denied (Unix) + +``` +Error: Permission denied: ~/.local/bin/ccs +``` + +**Solution**: Make the script executable: +```bash +chmod +x ~/.local/bin/ccs +``` + +### Config file not found + +``` +Error: Config file not found: ~/.ccs/config.json +``` + +**Solution**: Re-run installer or create config manually: +```bash +mkdir -p ~/.ccs +echo '{"profiles":{"default":"~/.claude/settings.json"}}' > ~/.ccs/config.json +``` + +## Getting Help + +If you encounter issues not covered here: + +1. Check the [GitHub Issues](https://github.com/kaitranntt/ccs/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: + +```bash +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 \ No newline at end of file diff --git a/docs/usage.md b/docs/usage.md new file mode 100644 index 00000000..a2ad73a2 --- /dev/null +++ b/docs/usage.md @@ -0,0 +1,157 @@ +# CCS Usage Guide + +## Why CCS? + +**Built for developers with both Claude subscription and GLM Coding Plan.** + +### Two Real Use Cases + +#### 1. Task-Appropriate Model Selection + +**Claude Sonnet 4.5** excels at: +- Complex architectural decisions +- System design and planning +- Debugging tricky issues +- Code reviews requiring deep reasoning + +**GLM 4.6** works great for: +- Simple bug fixes +- Straightforward implementations +- Routine refactoring +- Documentation writing + +**With CCS**: Switch models based on task complexity, maximize quality while managing costs. + +```bash +ccs # Planning new feature architecture +# Got the plan? Implement with GLM: +ccs glm # Write the straightforward code +``` + +#### 2. Rate Limit Management + +If you have both Claude subscription and GLM Coding Plan, you know the pain: +- Claude hits rate limit mid-project +- You manually copy GLM config to `~/.claude/settings.json` +- 5 minutes later, need to switch back +- Repeat 10x per day + +**CCS solves this**: +- One command to switch: `ccs` (default) or `ccs glm` (fallback) +- Keep both configs saved as profiles +- Switch in <1 second +- No file editing, no copy-paste, no mistakes + +### Features + +- Instant profile switching (Claude ↔ GLM) +- Pass-through all Claude CLI args +- Smart setup: detects your current provider +- Auto-creates configs during install +- No proxies, no magic—just bash + jq + +## Basic Usage + +### Switching Profiles + +```bash +# Works on macOS, Linux, and Windows +ccs # Use Claude subscription (default) +ccs glm # Use GLM fallback +``` + +**Windows Note**: Commands work identically in PowerShell, CMD, and Git Bash. + +### With Arguments + +All args after profile name pass directly to Claude CLI: + +```bash +ccs glm --verbose +ccs /plan "add feature" +ccs glm /code "implement feature" +``` + +### Utility Commands + +```bash +ccs --version # Show CCS version +ccs --help # Show Claude CLI help +``` + +## Task Delegation + +**CCS includes intelligent task delegation** via the `/ccs` meta-command: + +```bash +# Delegate planning to GLM (saves Sonnet tokens) +/ccs glm /plan "add user authentication" + +# Delegate coding to GLM +/ccs glm /code "implement auth endpoints" + +# Quick questions with Haiku +/ccs haiku /ask "explain this error" +``` + +**Benefits**: +- ✅ Save tokens by delegating simple tasks to cheaper models +- ✅ Use right model for each task automatically +- ✅ Reusable commands across all projects (user-scope) +- ✅ Seamless integration with existing workflows + +## Real Workflows + +### Task-Based Model Selection + +**Scenario**: Building a new payment integration feature + +```bash +# Step 1: Architecture & Planning (needs Claude's intelligence) +ccs +/plan "Design payment integration with Stripe, handle webhooks, errors, retries" +# → Claude Sonnet 4.5 thinks deeply about edge cases, security, architecture + +# Step 2: Implementation (straightforward coding, use GLM) +ccs glm +/code "implement the payment webhook handler from the plan" +# → GLM 4.6 writes the code efficiently, saves Claude usage + +# Step 3: Code Review (needs deep analysis) +ccs +/review "check the payment handler for security issues" +# → Claude Sonnet 4.5 catches subtle vulnerabilities + +# Step 4: Bug Fixes (simple) +ccs glm +/fix "update error message formatting" +# → GLM 4.6 handles routine fixes +``` + +**Result**: Best model for each task, lower costs, better quality. + +### Rate Limit Management + +```bash +# Working on complex refactoring with Claude +ccs +/plan "refactor authentication system" + +# Claude hits rate limit mid-task +# → Error: Rate limit exceeded + +# Switch to GLM instantly +ccs glm +# Continue working without interruption + +# Rate limit resets? Switch back +ccs +``` + +## How It Works + +1. Reads profile name (defaults to "default" if omitted) +2. Looks up settings file path in `~/.ccs/config.json` +3. Executes `claude --settings [remaining-args]` + +No magic. No file modification. Pure delegation. Works identically across all platforms. \ No newline at end of file diff --git a/docs/version-management.md b/docs/version-management.md index 16c09c4a..16858fcb 100644 --- a/docs/version-management.md +++ b/docs/version-management.md @@ -43,7 +43,6 @@ This updates: - VERSION file - installers/install.sh (hardcoded version) - installers/install.ps1 (hardcoded version) -- Creates git tag (if in git repo) ### Manual Method @@ -68,12 +67,11 @@ If updating manually, update version in ALL three locations: When releasing a new version: -- [ ] Update version using `./scripts/update-version.sh X.Y.Z` +- [ ] Update version using `./scripts/bump-version.sh X.Y.Z` - [ ] Review changes: `git diff` - [ ] Update CHANGELOG.md with release notes - [ ] Commit changes: `git commit -am "chore: bump version to X.Y.Z"` -- [ ] Create tag: `git tag -a vX.Y.Z -m "Release vX.Y.Z"` -- [ ] Push: `git push && git push --tags` +- [ ] Push: `git push` - [ ] Verify CloudFlare worker serves updated installer ## Version Display diff --git a/installers/install.ps1 b/installers/install.ps1 index 99e10360..a5f3fa17 100644 --- a/installers/install.ps1 +++ b/installers/install.ps1 @@ -30,7 +30,7 @@ $InstallMethod = if ($ScriptDir -and ((Test-Path "$ScriptDir\ccs.ps1") -or (Test # IMPORTANT: Update this version when releasing new versions! # This hardcoded version is used for standalone installations (irm | iex) # For git installations, VERSION file is read if available -$CcsVersion = "2.1.2" +$CcsVersion = "2.1.3" # Try to read VERSION file for git installations if ($ScriptDir) { @@ -232,7 +232,7 @@ if ($ScriptDir -and (Test-Path "$ScriptDir\uninstall.ps1")) { try { $BaseUrl = "https://raw.githubusercontent.com/kaitranntt/ccs/main" # Download uninstall.ps1 as ccs-uninstall.ps1 - Invoke-WebRequest -Uri "$BaseUrl/uninstall.ps1" -OutFile "$CcsDir\ccs-uninstall.ps1" -UseBasicParsing + Invoke-WebRequest -Uri "$BaseUrl/installers/uninstall.ps1" -OutFile "$CcsDir\ccs-uninstall.ps1" -UseBasicParsing # Clean up old uninstall.ps1 from previous installations if (Test-Path "$CcsDir\uninstall.ps1") { Remove-Item "$CcsDir\uninstall.ps1" -Force -ErrorAction SilentlyContinue diff --git a/installers/install.sh b/installers/install.sh index d2e33aa9..fa78fea1 100755 --- a/installers/install.sh +++ b/installers/install.sh @@ -31,7 +31,7 @@ fi # IMPORTANT: Update this version when releasing new versions! # This hardcoded version is used for standalone installations (curl | bash) # For git installations, VERSION file is read if available -CCS_VERSION="2.1.2" +CCS_VERSION="2.1.3" # Try to read VERSION file for git installations if [[ -f "$SCRIPT_DIR/VERSION" ]]; then diff --git a/scripts/bump-version.sh b/scripts/bump-version.sh index 7cf385a3..ccf86222 100755 --- a/scripts/bump-version.sh +++ b/scripts/bump-version.sh @@ -60,7 +60,6 @@ echo "This will:" echo " 1. Update VERSION file" echo " 2. Update installers/install.sh (hardcoded version)" echo " 3. Update installers/install.ps1 (hardcoded version)" -echo " 4. Create git tag v$NEW_VERSION (if in git repo)" echo "" read -p "Continue? (y/N) " -n 1 -r echo @@ -94,19 +93,5 @@ else echo "⚠ installers/install.ps1 not found, skipping" fi -# Create git tag if in repo -if git rev-parse --git-dir > /dev/null 2>&1; then - if git tag -a "v$NEW_VERSION" -m "Release v$NEW_VERSION"; then - echo "✓ Created git tag v$NEW_VERSION" - echo "" - echo "Next steps:" - echo " git push origin v$NEW_VERSION" - else - echo "⚠ Failed to create git tag (may already exist)" - fi -else - echo "ℹ Not in git repository, skipping tag creation" -fi - echo "" echo "✓ Version bumped to $NEW_VERSION"