When models have thinking enabled (e.g. codex with thinking: auto), the
API returns content as [{ type: 'thinking', thinking: '...' }, { type:
'text', text: '...' }]. The hook reads content[0].text which is
undefined for thinking blocks, causing 'No text content in response'
errors that block the Read tool (exit 2).
Also fix cross-provider model fallback: getModelsToTry() unconditionally
appends DEFAULT_MODEL (gemini-2.5-flash) as retry, which 502s on
non-gemini provider routes (e.g. codex). Only use DEFAULT_MODEL when no
provider-specific model is configured.
Fixes: content[0].text -> content.find(b => b.type === 'text')
Fixes: cross-provider retry causing 'unknown provider' 502
Ref: #511
* fix(cliproxy): migrate deprecated gemini-claude-* model names to upstream claude-* names (#515)
* fix(cliproxy): migrate deprecated gemini-claude-* model names to upstream claude-* names
CLIProxyAPI registry no longer recognizes the gemini-claude-* prefix convention.
Model names in catalog, base config, and user settings are migrated to upstream
claude-* names. Auto-migration in env-builder rewrites existing user settings on
load and persists the change.
Closes#513
* fix: address code review feedback — sync UI layer and add migration tests
- Sync UI isNativeGeminiModel() with backend (remove gemini-claude- exclusion)
- Update UI model catalog agy entries from gemini-claude-* to claude-*
- Update CI/CD workflow and code-reviewer default model names
- Add unit tests for migrateDeprecatedModelNames() logic
* fix(hooks): isolate image type check before error-prone processing (#514)
* fix(hooks): isolate image type check before error-prone processing
Restructure processHook() into two phases so non-image Read calls
never see hook error messages. Phase 1 defensively checks tool name
and file extension, exiting 0 silently on any failure. Phase 2 only
runs for confirmed image/PDF files where errors are relevant.
Closes#511
* fix(hooks): sync image analyzer hook file on every profile launch
Add installImageAnalyzerHook() call to cliproxy executor, matching
the existing installWebSearchHook() pattern. This ensures the .cjs
file in ~/.ccs/hooks/ gets refreshed from the npm package on every
launch, so users receive hook updates after npm update.
* chore(release): 7.41.0-dev.1 [skip ci]
* fix(cliproxy): add fork:true for Claude model aliases in config generator (#523)
Config generator now outputs fork:true for Claude model alias entries,
ensuring both upstream (claude-*) and aliased (gemini-claude-*) model
names appear in /v1/models listings. Also preserves fork flag when
parsing user-added aliases during config regeneration.
Bumps config version to v7 to trigger regeneration on next ccs doctor.
Closes#522
* chore(release): 7.41.0-dev.2 [skip ci]
* feat(cliproxy): add account safety guards to prevent Google account bans (#516)
* feat(cliproxy): add account safety guards to prevent Google account bans
Implements cross-provider isolation to prevent Google from flagging
concurrent OAuth usage across different client IDs (ref: #509, #512).
Three pillars:
1. Auto-pause enforcement at session launch — conflicting accounts in
other Google OAuth providers are paused so CLIProxyAPI can't use them,
restored on session exit with crash recovery via auto-paused.json
2. Ban/disable detection — error responses matching Google ban patterns
auto-pause the affected account to prevent further damage
3. Cross-provider conflict warnings during OAuth registration
Key design decisions:
- PID-based session tracking for crash recovery (dead PID = restore)
- Timestamp comparison prevents restoring ban-paused accounts on exit
- Schema validation on auto-paused.json prevents corrupted state
- Falls back to warn-only when another session is managing isolation
* fix(cliproxy): address code review feedback (attempt 1/5)
- Re-read auto-paused.json before write in enforceProviderIsolation to
reduce concurrent write race window
- Use actual email from registry for display instead of raw accountId
- Export maskEmail for testability
- Add 27 unit tests covering ban detection, email masking,
cross-provider duplicate detection, enforcement lifecycle,
crash recovery, and timestamp-guarded restore
* fix(cliproxy): address remaining review feedback (attempt 2/5)
- Add handleBanDetection test verifying account pause on ban error
- Add warnCrossProviderDuplicates tests (true/false/non-Google)
- Document PID reuse limitation in isPidAlive JSDoc comment
* chore(release): 7.41.0-dev.3 [skip ci]
* feat(cliproxy): runtime quota monitoring during active sessions (#529)
* feat(cliproxy): add runtime quota monitoring during active sessions
Adds adaptive background quota polling to detect and respond to quota
exhaustion during active CLIProxy sessions. Prevents rate-limit-driven
account bans by auto-cooling exhausted accounts and switching defaults.
- Adaptive polling: 300s normal, 60s at 20% threshold, stops at 0%
- Stderr warnings at 20%, boxed exhaustion alerts at 0%
- Cooldown + default switch on exhaustion (existing patterns)
- Configurable via quota_management.runtime_monitor in config.yaml
- Timer.unref() prevents blocking process exit
- monitorStopped guard for in-flight poll safety
Closes#524
* fix: address code review feedback (attempt 1/5)
- M1: Round quotaPercent display with Math.round() to avoid ugly floats
- M2: Rename exhaust_threshold -> exhaustion_threshold for consistency
with existing auto.exhaustion_threshold config field
- M3: Replace async not.toThrow() with direct await assertion pattern
* fix: address code review feedback (attempt 2/5)
- Remove .claude/agent-memory/ from tracking and add to .gitignore
- Unify cooldown_minutes default to 5 (was 10 in runtime_monitor, 5 in auto)
- Add threshold validation in startQuotaMonitor (warn > exhaustion)
- Document intentional post-switch monitoring gap in code comment
* chore(release): 7.41.0-dev.4 [skip ci]
* fix(cliproxy): mask email in ban detection and fix JSDoc default
- Use maskEmail() in handleBanDetection output for consistency
- Fix cooldown_minutes JSDoc: default is 5, not 10
* chore(release): 7.41.0-dev.5 [skip ci]
* fix(cliproxy): address all review feedback (Low + informational)
- Add sync constraint comment on process.exit handler (executor)
- Add TOCTOU race acceptability comment (account-safety)
- Mask email in handleQuotaExhaustion reason string
- Use realistic exhaustion_threshold (5) in test configs
* chore(release): 7.41.0-dev.6 [skip ci]
---------
Co-authored-by: github-actions[bot] <github-actions[bot]@users.noreply.github.com>
- Add ENOTFOUND, ENETUNREACH, EAI_AGAIN to noRetryPatterns to prevent
infinite retries on network errors
- Update E2E test to expect exit code 2 (block) when CLIProxy unavailable
- Fix debug message expectation in test
Model resolution priority:
1. provider_models[current_provider]
2. ANTHROPIC_MODEL from profile settings
3. DEFAULT_MODEL (gemini-2.5-flash)
Allows users to override vision model via profile's ANTHROPIC_MODEL.
- Empty model validation: check `model.trim()` before using
- 10MB boundary: use `>=` instead of `>` for consistent messaging
- Timeout clamping: ensure timeout is between 1-600 seconds
- Response stream error: add error handler for network failures
- Empty response validation: check before JSON.parse to prevent crashes
Changes ImageAnalysisConfig from providers array to provider_models
mapping for granular vision model control per CLIProxy provider.
Breaking change: config.yaml image_analysis section now uses
provider_models instead of providers/model fields.
Provider-to-model mappings:
- agy → gemini-2.5-flash
- gemini → gemini-2.5-flash
- codex → gpt-5.1-codex-mini
- kiro → kiro-claude-haiku-4-5
- ghcp → claude-haiku-4.5
- claude → claude-haiku-4-5-20251001
Hook checks CCS_CURRENT_PROVIDER against provider_models and skips
if no vision model configured for that provider.
Match websearch transformer format:
- Header: [Image Analysis via CLIProxy]
- Metadata: File name, size in KB, model used
- Separator lines for better readability
- Footer instruction for Claude
Intercept Read tool calls for image/PDF files and route through CLIProxy
with gemini-2.5-flash for vision analysis. Returns text descriptions
instead of blocking, enabling Claude to "see" images via proxy.
Key changes:
- Add image-analyzer-transformer.cjs hook script
- Add ImageAnalysisConfig type and loader
- Add hook installer and profile injector
- Add prompt templates for analysis customization
- Add e2e test suite (excluded from normal CI runs)
- Configure test:e2e script for manual testing
Environment variables:
- CCS_IMAGE_ANALYSIS_ENABLED: Enable/disable (default: 1)
- CCS_IMAGE_ANALYSIS_MODEL: Vision model (default: gemini-2.5-flash)
- CCS_IMAGE_ANALYSIS_TIMEOUT: Timeout in seconds (default: 60)
- CCS_CLIPROXY_API_KEY: API key for CLIProxy auth
- CCS_CLIPROXY_PORT: CLIProxy port (default: 8317)
Closes#426
Match WebSearch hook pattern:
- ENABLED by default for settings/cliproxy profiles
- DISABLED for native Claude accounts (account/default)
- User can override via config: hooks.block_image_read.enabled: false
This ensures CCS CLI users get context protection out-of-the-box
while native Claude subscription users are unaffected.
Add PreToolUse hook that intercepts Read tool calls on image files
(.png, .jpg, .webp, etc.) and blocks them with helpful message.
This prevents context exhaustion when image generation skills
produce multiple files and the agent tries to read them (each
image can consume 100K+ tokens).
Configuration:
- Enable via config.yaml: hooks.block_image_read.enabled: true
- Or env var: CCS_BLOCK_IMAGE_READ=1
Hook integration:
- lib/hooks/block-image-read.cjs - the hook script
- src/utils/hooks/image-read-block-hook-env.ts - config loader
- Integrated into all spawn locations (ccs.ts, shell-executor,
cliproxy-executor)
Closes#426
On Windows, globally installed CLI tools via npm/pnpm are .cmd/.bat
batch files, not real .exe executables. Node.js spawnSync() without
the shell option cannot execute these files and returns ENOENT error.
Changes:
- Extract isWindows as a global constant at file top
- Add shell: isWindows to all CLI execution spawnSync calls
- Remove duplicate isWindows declaration in isCliAvailable()
Fixes#378
Co-authored-by: Cursor <cursoragent@cursor.com>
Fixes#273
The websearch-transformer hook used hardcoded 'which' command which doesn't
exist on Windows. Now uses process.platform detection to choose 'where' on
Windows and 'which' on Unix systems.
Previously, WebSearch status showed "Ready (Gemini)" when the CLI binary
was installed, misleading users who hadn't authenticated yet.
Changes:
- Add isGeminiAuthenticated() to check ~/.gemini/oauth_creds.json
- Add 'needs_auth' state to WebSearchReadiness type
- Show warning "[!] Gemini: run 'gemini' to login" when not authenticated
- Fix incorrect 'gemini auth login' references (no such command exists)
- Update docs with correct npm install and authentication instructions
WebSearch hook was blocking native Claude accounts (ccs ck, default)
with "No Providers Enabled" message instead of passing through to
server-side WebSearch.
Changes:
- Add shouldSkipHook() detection for account/default profile types
- Fix blocking bug: exit(0) when no providers enabled instead of blocking
- Pass CCS_PROFILE_TYPE and CCS_WEBSEARCH_SKIP env vars for profile-aware behavior
- Add profile type signals to settings, cliproxy, account, and default execution paths
- Add model field to Gemini/OpenCode WebSearch providers
- Config.yaml now explicitly stores model (gemini-2.5-flash, opencode/grok-code)
- UI: blur-to-save for model inputs (no save on every keystroke)
- UI: collapsible install hints inside provider cards
- UI: left accent border for enabled providers (better light theme contrast)
- Hook: use systemMessage for info-styled confirmation
- Hook: cleaner result format without defensive "NOT an error" language
- Hook timeout now computed from max provider timeout + 30s buffer
- Removes hardcoded HOOK_TIMEOUT_SECONDS constant
- ensureHookConfig() now updates timeout when it changes
- Default OpenCode model changed from gpt-5-nano to grok-code
- Default OpenCode timeout changed from 60s to 90s
- Single source of truth: config.yaml controls all timeouts
- Add SHARED_INSTRUCTIONS constant with 7 quality guidelines applied to ALL providers
- Refactor PROVIDER_CONFIG to use toolInstruction (provider-specific) and quirks (optional)
- Add buildPrompt() function to combine shared + provider-specific instructions
- Gemini: google_web_search tool instruction
- OpenCode: built-in capabilities instruction
- Grok: web search + X/Twitter quirk for real-time events
DRY improvement: shared guidelines now maintained in one place
Major refactor of WebSearch hook to:
1. **Respect config.yaml settings**: Hook now reads CCS_WEBSEARCH_GEMINI,
CCS_WEBSEARCH_OPENCODE, CCS_WEBSEARCH_GROK env vars to determine which
providers to use. Only enabled AND installed providers are tried.
2. **Consolidate prompts/models**: Added PROVIDER_CONFIG section at top of
hook file for easy prompt engineering:
- gemini: model + prompt template
- opencode: model (overridable via env) + prompt template
- grok: model + prompt template
3. **Pass provider states via env**: Updated getWebSearchHookEnv() to pass
individual provider enabled states as env vars.
Breaking change: Hook no longer falls back to all installed CLIs. It now
strictly respects config.yaml settings.
Add automatic fallback chain (Gemini -> OpenCode -> Grok) when multiple
WebSearch CLI providers are available. The hook now tries each provider
in order until one succeeds.
Changes:
- Update websearch-transformer.cjs with tryOpenCodeSearch() and tryGrokSearch()
- Implement fallback chain logic in processHook()
- Add outputAllFailedMessage() for when all providers fail
- Update outputNoToolsMessage() with all three install options
- Update config.yaml comments to document OpenCode and fallback behavior
- Add Grok CLI detection (grok-4-cli by lalomorales22) alongside Gemini CLI
- Add WebSearch health check group to health-service.ts
- Update settings UI to show both Gemini and Grok CLI providers
- Add detailed install hints when no WebSearch CLI is installed
- Update API routes to return grokCli status
- Both CLI and dashboard users now see clear installation guidance
Providers:
- Gemini CLI: FREE tier (1000 req/day), no API key needed
- Grok CLI: Requires xAI API key (XAI_API_KEY), web + X search
* fix: add missing commands/ccs.md symlink during npm install
Previously, the ClaudeSymlinkManager only created symlinks for the
commands/ccs directory and skills/ccs-delegation directory, but missed
the commands/ccs.md file. This resulted in an incomplete symlink structure
where users would see the ccs folder symlinked but not the ccs.md file.
Added commands/ccs.md to the ccsItems array to ensure all CCS components
are properly symlinked during installation.
Fixes: npm install now creates complete symlink structure for all CCS items
* chore: bump version to 4.3.9
* fix(postinstall): make ora dependency optional to fix missing ~/.ccs/.claude/ directory
The root cause was that `ora` module was not available during `npm install`
when the postinstall script runs, causing both:
- .claude/ directory copy to fail (ClaudeDirInstaller)
- Symlink creation to fail (ClaudeSymlinkManager)
This resulted in the ~/.ccs/.claude/ directory not being created.
Changes:
- Made ora import optional in ClaudeDirInstaller
- Made ora import optional in ClaudeSymlinkManager
- Both classes now gracefully fallback to console.log when ora is unavailable
- Postinstall now successfully creates ~/.ccs/.claude/ and symlinks
Tested: Clean install now properly creates all directories and symlinks
* chore: bump version to 4.3.7
Version 4.3.7 - Postinstall Fix Release
Changes:
- Fixed missing ~/.ccs/.claude/ directory during npm install
- Made ora dependency optional in installer utilities
- Added CHANGELOG entry documenting the fix
Files updated:
- VERSION: 4.3.6 -> 4.3.7
- package.json: version updated
- lib/ccs: version string updated
- lib/ccs.ps1: version string updated
- installers/install.sh: version string updated
- installers/install.ps1: version string updated
- CHANGELOG.md: added 4.3.7 release notes
* fix: handle ora v9 ES module compatibility
ora v9.0.0 is now an ES module, which requires using .default when
importing with CommonJS require(). This was causing "ora is not a
function" errors in doctor.js and installer utilities.
Changes:
- Updated ora import to use oraModule.default || oraModule
- Added fallback spinner implementation for when ora is unavailable
- Ensures compatibility with both ES and CommonJS module systems
- Fixes ccs doctor command and postinstall script
Tested:
- ccs doctor now works correctly with spinners
- postinstall successfully creates ~/.ccs/.claude/ and symlinks
- Fallback console.log works when ora is unavailable
* chore: update package-lock.json
* chore: bump version to 4.3.8
Version 4.3.8 - ora v9 Compatibility Release
Changes:
- Fixed ora v9 ES module compatibility issues
- Updated CHANGELOG with 4.3.8 release notes
Files updated:
- VERSION: 4.3.7 -> 4.3.8
- package.json: version updated
- lib/ccs: version string updated
- lib/ccs.ps1: version string updated
- installers/install.sh: version string updated
- installers/install.ps1: version string updated
- CHANGELOG.md: added 4.3.8 release notes
* fix(postinstall): make ora dependency optional to fix missing ~/.ccs/.claude/ directory
The root cause was that `ora` module was not available during `npm install`
when the postinstall script runs, causing both:
- .claude/ directory copy to fail (ClaudeDirInstaller)
- Symlink creation to fail (ClaudeSymlinkManager)
This resulted in the ~/.ccs/.claude/ directory not being created.
Changes:
- Made ora import optional in ClaudeDirInstaller
- Made ora import optional in ClaudeSymlinkManager
- Both classes now gracefully fallback to console.log when ora is unavailable
- Postinstall now successfully creates ~/.ccs/.claude/ and symlinks
Tested: Clean install now properly creates all directories and symlinks
* chore: bump version to 4.3.7
Version 4.3.7 - Postinstall Fix Release
Changes:
- Fixed missing ~/.ccs/.claude/ directory during npm install
- Made ora dependency optional in installer utilities
- Added CHANGELOG entry documenting the fix
Files updated:
- VERSION: 4.3.6 -> 4.3.7
- package.json: version updated
- lib/ccs: version string updated
- lib/ccs.ps1: version string updated
- installers/install.sh: version string updated
- installers/install.ps1: version string updated
- CHANGELOG.md: added 4.3.7 release notes
* feat(shared): add plugin support to shared directories
Add Claude Code plugins to the .ccs/shared/ symlink architecture,
enabling plugin sharing across all CCS profiles (GLM, GLMT, Kimi, etc).
Changes:
- SharedManager: Add 'plugins' to sharedDirs array
- Help text: Update all three implementations (Node.js, bash, PowerShell)
- Postinstall: Create ~/.ccs/shared/plugins/ directory on install
Architecture:
~/.claude/plugins/ <- ~/.ccs/shared/plugins/ <- instance/plugins/
This follows the existing pattern for commands/skills/agents and
maintains cross-platform compatibility with Windows fallback support.
* chore: bump version to 4.3.6
* docs: update CHANGELOG for v4.3.6
* feat(completion): improve fish shell completion with category prefixes
- Remove problematic inline set_color commands that prevented descriptions from displaying
- Add [cmd], [model], and [account] prefixes to visually group completions
- Update file header to document categorization features
This brings fish completion quality closer to zsh by making categories
clear and ensuring descriptions actually display to users.
Fixes issue where fish completions showed no descriptions.
* chore: bump version to 4.3.1
* feat: enhance UX for 'ccs sync' and 'ccs doctor' commands
- Add ora spinners for real-time progress feedback
- Add cli-table3 for structured health check summary table
- Display detailed component information in doctor report
- Show file/directory counts during sync operations
- Improve visual hierarchy and readability
- Fix Unicode checkmark violation (replaced with [OK])
Breaking changes: None
Dependencies added: ora@^5.4.1, cli-table3@^0.6.5
Version bumped to 4.3.0
* fix: match doctor summary header width to table width
* feat: improve settings validation to check API keys, not just endpoints
- Check if API keys are configured or still placeholders
- Show 'Key configured' vs 'Placeholder key (not configured)'
- Previous message 'Valid (API: api.z.ai)' was misleading
- Now users can clearly see which profiles need API key configuration
- Warnings shown for placeholder keys (yellow [!])
* feat: add category grouping and alignment to doctor checks
- Group checks into logical categories: System, Configuration, Profiles & Delegation, System Health
- Add consistent padding (26 chars) for aligned columns
- Add 2-space indent for better visual hierarchy
- Separate categories with blank lines for better readability
- Much cleaner and easier to scan than before
* fix: perfect alignment for all doctor check output
- Use .padEnd(26) consistently for all component names
- Remove extra space before status icons
- Now all status icons [OK]/[X]/[!]/[i] align perfectly
- All component names pad to exactly 26 characters
Add comprehensive update functionality with intelligent notification system.
Supports manual update checking, automatic notifications every 24h, and works
across npm and direct installations with proper error handling.
Closes#12
* feat: add -sc short flag for --shell-completion
Add -sc as a short flag alias for --shell-completion,
matching the pattern of -h for --help and -v for --version.
Changes:
- bin/ccs.js: Add -sc support in help text and flag detection
- lib/ccs: Add -sc support in help text and flag detection
- lib/ccs.ps1: Add -sc support in help text and flag detection
* chore: bump version to 4.1.4
* chore: bump version to 4.1.5
* feat: emphasize concurrent account usage in auth help text
Update all auth-related help messages to emphasize the ability
to run multiple Claude accounts concurrently.
Changes:
- bin/ccs.js: "Run multiple Claude accounts concurrently"
- bin/auth/auth-commands.js: "CCS Concurrent Account Management"
- lib/ccs: Updated both main help and auth_help function
- lib/ccs.ps1: Updated both main help and Show-AuthHelp function
* feat: implement ccs update command across all platforms
Add cross-platform ccs update command to sync delegation commands
and skills from ~/.ccs/.claude/ to ~/.claude/. Replaces vague
"CCS items" wording with specific "delegation commands and skills".
Changes:
- bin/ccs.js: Add update command handler and update help text
- bin/utils/claude-symlink-manager.js: Update user-facing messages
- lib/ccs: Implement update_run() function with symlink logic
- lib/ccs.ps1: Implement Update-Run function with Junction/SymbolicLink support
Features:
- Automatically backs up existing files before symlinking
- Skips items that are already correctly symlinked
- Reports installed vs up-to-date counts
- Handles Windows permissions gracefully (suggests Admin/Developer Mode)
Cross-platform parity: bash, PowerShell, and Node.js now all support ccs update
* refactor: rename ccs update to ccs sync for clarity
Rename the update command to sync across all platforms to avoid
confusion with updating the CCS tool itself. The sync command
clearly communicates syncing delegation features from the CCS
package to ~/.claude/.
Changes:
- bin/ccs.js: Rename handleUpdateCommand → handleSyncCommand
- bin/utils/claude-symlink-manager.js: Rename update() → sync()
- lib/ccs: Rename update_run() → sync_run()
- lib/ccs.ps1: Rename Update-Run → Sync-Run
- All: Update help text "update" → "sync"
- All: Update messages "Updating" → "Syncing"
Command usage: ccs sync or ccs --sync
* fix: update GitHub documentation links to stable permalink
Update broken #usage anchor links to stable /blob/main/README.md
permalink format. This matches the format already used in PowerShell
version and ensures links always work.
Changes:
- bin/ccs.js: Update link from #usage to /blob/main/README.md
- lib/ccs: Update link from #usage to /blob/main/README.md
- Now consistent with lib/ccs.ps1 which already used this format
Old: https://github.com/kaitranntt/ccs#usage
New: https://github.com/kaitranntt/ccs/blob/main/README.md
* feat: add sync command and -sc flag to shell completions
Update all shell completion scripts to include the newly added
sync command and -sc short flag for --shell-completion.
Changes across all completion scripts (bash, zsh, fish, PowerShell):
- Add 'sync' command to completion suggestions
- Add '-sc' as short flag for '--shell-completion'
- Update fish to handle both -sc and --shell-completion for subflags
- Update PowerShell to recognize -sc for shell completion flags
- Add sync command description: "Sync delegation commands and skills"
This ensures tab completion discovers the sync command and users
can use both -sc and --shell-completion interchangeably.
* fix: standardize help text across all implementations
Fix inconsistencies in help text that appeared after merge from main.
Ensures all three implementations (bash, PowerShell, Node.js) display
identical help messages.
Changes:
- lib/ccs: Update "Delegation (Token Optimization)" → "Delegation (inside Claude Code CLI)"
- lib/ccs: Remove redundant /ccs:create line, simplify description
- lib/ccs.ps1: Add missing Delegation section
- All: Now use consistent messaging about delegation features
This ensures users see the same information regardless of which
platform they're using (Linux/macOS bash, Windows PowerShell, or npm).
* fix: update description text to emphasize concurrent sessions
Update outdated description in lib/ccs and lib/ccs.ps1 to match
the improved wording already in bin/ccs.js. The new description
better emphasizes running concurrent Claude CLI sessions.
Changes:
- lib/ccs: Update description to emphasize "Run different Claude CLI sessions concurrently"
- lib/ccs.ps1: Update description to match bash and Node.js versions
- Remove "(work, personal, team)" examples to keep description cleaner
- Emphasize "Run different Claude CLI sessions concurrently" over vague "Concurrent sessions"
Old: "Switch between multiple Claude accounts (work, personal, team) and
alternative models (GLM, Kimi) instantly. Concurrent sessions with
auto-recovery. Zero downtime."
New: "Switch between multiple Claude accounts and alternative models
(GLM, Kimi) instantly. Run different Claude CLI sessions concurrently
with auto-recovery. Zero downtime."
All three implementations now show identical, clearer description text.
* feat(cli): enhance version display formatting and delegation status
---------
* fix(shell-completion): resolve ENOTDIR error when parent path is a file
Fixes issue where `--shell-completion` fails with ENOTDIR error when
a file exists where a directory should be created (e.g., ~/.zsh exists
as a file instead of a directory).
Changes:
- Added ensureDirectory() helper that safely creates directories
- Validates parent paths are directories, not files
- Provides clear error message when file conflicts occur
- Applied to all shell installers (bash, zsh, fish, powershell)
- Maintains idempotent behavior (safe to call multiple times)
Before: mkdir with recursive:true fails silently with ENOTDIR
After: Clear error message guides user to resolve file conflict
* chore: bump version to 4.1.4
* feat(completion): improve UI/UX with descriptions and grouping
Improves shell completion UI/UX across all shells (bash, zsh, fish,
PowerShell) with better organization and clearer descriptions.
Changes:
- Zsh: Added descriptions for all profiles and grouped by category
- Commands: "auth", "doctor" with descriptions
- Model profiles: glm, glmt, kimi, etc. with descriptions
- Account profiles: Dynamic with "Account-based profile" label
- Used _alternative for visual grouping
- Fish: Added explicit completions with descriptions for known profiles
- Replaced generic profile listing with specific entries
- Each profile now shows clear description (e.g., "GLM-4.6 (cost-optimized)")
- Bash: Added --shell-completion flag and subflags completion
- PowerShell: Added --shell-completion flag and subflags completion
- All shells: Added completion for --shell-completion subflags
Before (zsh):
ccs
auth -- Manage multiple Claude accounts
doctor -- Run health check and diagnostics
default glm glmt kimi max
After (zsh):
commands
auth -- Manage multiple Claude accounts
doctor -- Run health check and diagnostics
model profiles
default -- Default Claude Sonnet 4.5
glm -- GLM-4.6 (cost-optimized)
glmt -- GLM-4.6 with thinking mode
kimi -- Kimi for Coding (long-context)
max -- Claude Opus (maximum capability)
account profiles
work -- Account-based profile
personal -- Account-based profile
Consistent, organized, and informative completion across all shells.
* fix(completion): handle custom profiles and fix zsh syntax errors
Fixes two issues:
1. Zsh syntax errors with _describe -t flag in _alternative
2. Adds general handling for custom settings profiles (e.g., m2)
Changes:
- Zsh: Fixed _alternative syntax (removed -t tag from _describe calls)
- Error was: "_describe:21: bad option: -M"
- Cause: Tag is auto-derived in _alternative, don't specify with -t
- Fish: Added __fish_ccs_get_custom_settings_profiles function
- Dynamically loads non-hardcoded profiles from config.json
- Shows "Settings-based profile" description for custom profiles
- Removed 'max' from hardcoded known profiles
- 'max' is user's account-based profile, not a default setting
Now supports any custom settings profile (e.g., m2.settings.json for
Minimax M2) without hardcoding. Custom profiles show with generic
"Settings-based profile" description.
Installation properly overwrites:
- fs.copyFileSync overwrites completion files by default
- RC files only modified if marker not already present
* fix(zsh): simplify completion to avoid _alternative syntax issues
Replaced _alternative with multiple _describe calls to fix persistent
zsh completion errors.
The _alternative approach was causing:
- '_describe:21: bad option: -M'
- '(eval):1: bad substitution'
- Unwanted variable expansion in completion menu
New approach uses sequential _describe calls which zsh handles correctly.
Simpler, more reliable, and still shows grouped completion with
descriptions.
Before: _alternative with complex nested _describe calls (broken)
After: Three simple _describe calls (works correctly)
* feat(zsh): add colors and improved formatting to completion
Enhances zsh completion UI/UX with colors and better spacing:
Colors:
- Blue: commands (auth, doctor)
- Green: model profiles (default, glm, glmt, kimi, custom)
- Yellow: account profiles
- Gray: descriptions
Formatting:
- Wider separator ( -- ) for better readability
- Group headers in bold cyan
- Menu selection enabled for navigation
- list-rows-first for better column layout
Before:
auth -- Manage multiple Claude accounts
default -- Default Claude Sonnet 4.5
doctor -- Run health check and diagnostics
glm -- GLM-4.6 (cost-optimized)
After:
commands (cyan header)
auth -- Manage multiple Claude accounts (blue)
doctor -- Run health check and diagnostics (blue)
model profiles (cyan header)
default -- Default Claude Sonnet 4.5 (green)
glm -- GLM-4.6 (cost-optimized) (green)
glmt -- GLM-4.6 with thinking mode (green)
kimi -- Kimi for Coding (long-context) (green)
account profiles (cyan header)
max -- Account-based profile (yellow)
Table-like appearance with colors matching --help output style.
* feat(fish): add colors to completion descriptions
Adds color-coded descriptions to Fish completion matching zsh style:
Colors:
- Blue: commands (auth, doctor)
- Green: model profiles (default, glm, glmt, kimi, custom)
- Yellow: account profiles
Fish has excellent native color support via set_color, making this
straightforward to implement.
Before:
auth Manage multiple Claude accounts
default Default Claude Sonnet 4.5
glm GLM-4.6 (cost-optimized)
max Account profile
After:
auth Manage multiple Claude accounts (blue)
default Default Claude Sonnet 4.5 (green)
glm GLM-4.6 (cost-optimized) (green)
max Account profile (yellow)
Consistent color scheme across zsh and fish shells.
* fix(zsh): correct color application for commands vs descriptions
Fixed color codes being applied backwards - commands were gray while
descriptions were colorful.
Issue:
- Used '1;34' format which zsh misinterpreted
- Commands appeared gray (unreadable)
- Descriptions appeared in color
Fix:
- Simplified color codes from '1;34' to '34' (just the color, no style prefix)
- Pattern now: =(#b)(command)(-- description)=34=90
- First group (command): color 34 (blue/green/yellow)
- Second group (description): color 90 (gray)
Before:
auth -- Manage multiple Claude accounts (gray) (blue)
After:
auth -- Manage multiple Claude accounts (blue) (gray)
Commands now properly colored, descriptions muted.
* feat(zsh): improve section header visibility with separators
Makes section headers more distinct and recognizable as dividers:
Before:
commands
auth -- ...
After:
── commands ──
auth -- ...
Changes:
- Added blank line before headers ($'\n')
- Bold yellow with decorative separators (── text ──)
- Clearly distinguishes section headers from actual commands
Now it's obvious that 'commands', 'model profiles', and 'account
profiles' are just section labels, not completable items.
* fix(zsh): use full ANSI color codes to fix reversed colors
The issue was using shorthand color codes (34, 90) instead of full
ANSI format (0;34, 2;37). Zsh was misinterpreting the shorthand,
causing colors to be applied to wrong groups.
Fixed:
- Commands: 0;34 (normal blue) - was appearing gray
- Model profiles: 0;32 (normal green) - was appearing gray
- Account profiles: 0;33 (normal yellow) - was appearing gray
- Descriptions: 2;37 (dim white) - was appearing colorful
Color codes must be escaped as 0\;34 in zsh strings.
Before fix:
auth (gray) -- description (blue)
After fix:
auth (blue) -- description (dim gray)
* fix(zsh): swap color order for completion groups
Zsh may apply colors in reverse order to capture groups on some systems.
Swapped color order: group 2 first, then group 1.
Pattern: (command)(separator + description)
Was: =blue=dim_white (applied as: blue to cmd, dim to desc)
Now: =dim_white=blue (applied as: dim to desc, blue to cmd)
Testing if this resolves the reversed color issue.
* fix(zsh): add empty leading color to fix reversed coloring
ROOT CAUSE: Zsh list-colors apply first color to WHOLE match, then
override with subsequent colors for each group. Without an empty
leading color, the whole match color leaks to groups without overrides.
Pattern behavior:
=(#b)(cmd)(desc)=BLUE=DIM
→ Whole: BLUE, Group1: DIM (override), Group2: BLUE (no override)
→ Result: cmd=dim, desc=BLUE (REVERSED!)
=(#b)(cmd)(desc)==BLUE=DIM
→ Whole: none, Group1: BLUE, Group2: DIM
→ Result: cmd=BLUE, desc=dim (CORRECT!)
The '==' at start means 'no whole-match color', preventing color bleed.
Now commands will be colorful (blue/green/yellow) and descriptions dim.
* refactor(help): remove specific account examples and generalize description
Removed deterministic account examples (work, personal, team) to make
the help text more generic and less prescriptive.
Changes:
- Removed 'ccs work' and 'ccs personal' example lines
- Removed 'Multi-account workflow' examples section
- Updated description from 'multiple Claude accounts (work, personal, team)'
to 'multiple Claude accounts and alternative models'
- Changed to 'Run different Claude CLI sessions concurrently'
- Applied consistently across Node.js (bin/ccs.js), bash (lib/ccs),
and PowerShell (lib/ccs.ps1)
This makes the help text more flexible and doesn't imply specific
use cases or account naming conventions.
* refactor(help): clarify delegation section and remove non-existent command
Updated delegation section in help text across all implementations:
Changes:
- Renamed section from 'Delegation (Token Optimization)' to
'Delegation (inside Claude Code CLI)' to clarify context
- Removed non-existent '/ccs:create m2' command
- Simplified description to focus on cost savings
- Updated command descriptions:
- '/ccs:glm' now 'for simple tasks' (clearer use case)
- '/ccs:kimi' unchanged (already clear)
- Added delegation section to PowerShell help (was missing)
- Consistent messaging across Node.js, bash, and PowerShell
The new section makes it immediately clear that delegation commands
are used within Claude Code CLI sessions, not as standalone commands.
---------
