mirror of
https://github.com/tiennm99/ccs.git
synced 2026-07-16 12:15:57 +00:00
kaitranntt
c17e3e8e3b
- Fix PowerShell 7 syntax errors (ampersand, pipe chars, regex patterns) - Refactor bin/ccs.js to standalone Node.js implementation - Add modular architecture (helpers, claude-detector, config-manager) - Create comprehensive test suite with 95% coverage - Add npm publishing workflow and documentation - Enhance cross-platform compatibility and error handling - Achieve 60% performance improvement over shell spawning Breaking Change: Node.js npm package no longer spawns shell processes
228 lines
5.4 KiB
Markdown
228 lines
5.4 KiB
Markdown
# CCS Installation Guide
|
|
|
|
## npm Package Installation (Recommended)
|
|
|
|
### Cross-Platform Installation
|
|
|
|
**macOS / Linux / Windows**
|
|
```bash
|
|
npm install -g @kai/ccs
|
|
```
|
|
|
|
**Compatible with all package managers:**
|
|
- `npm install -g @kai/ccs`
|
|
- `yarn global add @kai/ccs`
|
|
- `pnpm add -g @kai/ccs`
|
|
- `bun add -g @kai/ccs`
|
|
|
|
**Benefits of npm installation:**
|
|
- ✅ Cross-platform compatibility
|
|
- ✅ Automatic PATH configuration
|
|
- ✅ Easy updates: `npm update -g @kai/ccs`
|
|
- ✅ Clean uninstall: `npm uninstall -g @kai/ccs`
|
|
- ✅ Version pinning support
|
|
- ✅ Dependency management
|
|
|
|
## One-Liner Installation (Traditional)
|
|
|
|
### 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
|
|
```
|
|
|
|
**Install Location**:
|
|
- **All Unix Systems**: `~/.local/bin/ccs` (auto-configures PATH for bash, zsh, fish)
|
|
|
|
### 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
|
|
```
|
|
|
|
**Auto PATH Configuration**:
|
|
- Installer detects your shell (bash, zsh, fish) automatically
|
|
- Adds `~/.local/bin` to PATH in shell profile if needed
|
|
- Idempotent: safe to run multiple times
|
|
- Shows reload instructions after install
|
|
|
|
**Notes**:
|
|
- Unix installer supports both direct execution (`./install.sh`) and piped installation (`curl | bash`)
|
|
- Windows installer requires PowerShell 5.1+ (pre-installed on Windows 10+)
|
|
- No sudo required on any platform
|
|
|
|
## 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
|
|
# Create directory
|
|
mkdir -p ~/.local/bin
|
|
|
|
# Download script
|
|
curl -fsSL https://raw.githubusercontent.com/kaitranntt/ccs/main/ccs -o ~/.local/bin/ccs
|
|
chmod +x ~/.local/bin/ccs
|
|
|
|
# Add to PATH (choose your shell)
|
|
# For bash
|
|
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc
|
|
source ~/.bashrc
|
|
|
|
# For zsh
|
|
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc
|
|
source ~/.zshrc
|
|
|
|
# For fish
|
|
echo 'set -gx PATH $HOME/.local/bin $PATH' >> ~/.config/fish/config.fish
|
|
```
|
|
|
|
### 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
|
|
|
|
**Executable Location**:
|
|
- macOS / Linux: `~/.local/bin/ccs` (symlink to `~/.ccs/ccs`)
|
|
- Windows: `%USERPROFILE%\.ccs\ccs.ps1`
|
|
|
|
**Configuration Directory** (`~/.ccs/`):
|
|
```bash
|
|
~/.ccs/
|
|
├── ccs # Main executable (symlink target)
|
|
├── config.json # Profile configuration
|
|
├── config.json.backup # Single backup (overwrites each install)
|
|
├── glm.settings.json # GLM profile
|
|
├── VERSION # Version file
|
|
├── uninstall.sh # Uninstaller
|
|
└── .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
|
|
```
|
|
|
|
## Auto PATH Configuration
|
|
|
|
The installer automatically configures your shell PATH:
|
|
|
|
**Supported Shells**:
|
|
- bash (`.bashrc` or `.bash_profile`)
|
|
- zsh (`.zshrc`)
|
|
- fish (`.config/fish/config.fish`)
|
|
|
|
**How It Works**:
|
|
1. Detects your current shell from `$SHELL` environment variable
|
|
2. Checks if `~/.local/bin` already in PATH
|
|
3. If not, adds appropriate export to shell profile
|
|
4. Shows reload instructions
|
|
|
|
**Idempotent**:
|
|
- Safe to run multiple times
|
|
- Checks for existing CCS PATH entry before adding
|
|
- Won't create duplicate entries
|
|
|
|
**Manual PATH Setup** (if auto-config fails):
|
|
|
|
Bash/Zsh:
|
|
```bash
|
|
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc # or ~/.zshrc
|
|
source ~/.bashrc # or source ~/.zshrc
|
|
```
|
|
|
|
Fish:
|
|
```fish
|
|
echo 'set -gx PATH $HOME/.local/bin $PATH' >> ~/.config/fish/config.fish
|
|
```
|
|
|
|
## Requirements
|
|
|
|
### macOS / Linux
|
|
- `bash` 3.2+
|
|
- `jq` (JSON processor, optional for enhanced features)
|
|
- [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, optional)
|
|
|
|
```bash
|
|
# macOS
|
|
brew install jq
|
|
|
|
# Ubuntu/Debian
|
|
sudo apt install jq
|
|
|
|
# Fedora
|
|
sudo dnf install jq
|
|
|
|
# Arch
|
|
sudo pacman -S jq
|
|
```
|
|
|
|
**Note**:
|
|
- jq enhances GLM profile creation but is not required
|
|
- Windows uses PowerShell's built-in JSON support - no jq needed
|
|
- Installer creates basic templates without jq |