From f4cd32baf0cad77c3481bfe0709c819af27a611a Mon Sep 17 00:00:00 2001 From: kaitranntt Date: Thu, 13 Nov 2025 21:29:17 -0500 Subject: [PATCH] docs: update README files with improved structure and GLMT experimental warnings - Reorganized README structure with collapsible sections for better readability - Added comprehensive GLMT experimental warnings and troubleshooting guides - Updated installation instructions with traditional vs npm options - Added parallel workflow examples and detailed feature comparisons - Enhanced documentation with proper acknowledgments and security limits - Standardized language and formatting across all README variants --- README.ja.md | 545 ++++++++++++++++++++++++++++++----------------- README.md | 329 +++++++++++++++++++--------- README.vi.md | 589 ++++++++++++++++++++++++++++++++------------------- 3 files changed, 939 insertions(+), 524 deletions(-) diff --git a/README.ja.md b/README.ja.md index d5a6d461..819121ae 100644 --- a/README.ja.md +++ b/README.ja.md @@ -1,45 +1,39 @@ -# CCS - Claude Code Switch -
+# CCS - Claude Code Switch + ![CCS Logo](docs/assets/ccs-logo-medium.png) -**1コマンド、ダウンタイムなし、複数アカウント** +### 1コマンド、ダウンタイムなし、複数アカウント -複数のClaudeアカウント、GLM、Kimiを瞬時に切り替え。
+**複数のClaudeアカウント、GLM、Kimiを瞬時に切り替え。** レート制限を回避し、継続的に作業。 +
[![License](https://img.shields.io/badge/license-MIT-C15F3C?style=for-the-badge)](LICENSE) [![Platform](https://img.shields.io/badge/platform-macOS%20%7C%20Linux%20%7C%20Windows-lightgrey?style=for-the-badge)]() [![npm](https://img.shields.io/npm/v/@kaitranntt/ccs?style=for-the-badge&logo=npm)](https://www.npmjs.com/package/@kaitranntt/ccs) [![PoweredBy](https://img.shields.io/badge/PoweredBy-ClaudeKit-C15F3C?style=for-the-badge)](https://claudekit.cc?ref=HMNKXOHN) -**Languages**: [English](README.md) | [Tiếng Việt](README.vi.md) | [日本語](README.ja.md) +**Languages**: [English](README.md) · [Tiếng Việt](README.vi.md) · [日本語](README.ja.md)
---- +
-## 🚀 クイックスタート +## クイックスタート -### 🔑 前提条件 +### インストール -**CCSをインストールする前に、サブスクリプションアカウントでClaude CLIにログインしていることを確認してください：** -```bash -claude /login -``` - -### 主なインストール方法 - -#### オプション1: npmパッケージ（推奨） +**npmパッケージ（推奨）** **macOS / Linux / Windows** ```bash npm install -g @kaitranntt/ccs ``` -主要なパッケージマネージャーすべてに対応： +**主要なパッケージマネージャーすべてに対応：** ```bash # yarn @@ -52,7 +46,10 @@ pnpm add -g @kaitranntt/ccs bun add -g @kaitranntt/ccs ``` -#### オプション2: 直接インストール（従来型） +
+代替案：直接インストール（従来型） + +
**macOS / Linux** ```bash @@ -64,7 +61,11 @@ curl -fsSL ccs.kaitran.ca/install | bash irm ccs.kaitran.ca/install | iex ``` -> **💡 パフォーマンス**: 従来型インストールはNode.jsルーティングをバイパスし起動が高速ですが、デプロイ自動化が容易なためnpm更新を優先します。 +**注**: 従来型インストールはNode.jsルーティングをバイパスし起動が高速ですが、デプロイ自動化が容易なためnpmを優先します。 + +
+ +
### 設定（自動作成） @@ -82,18 +83,29 @@ irm ccs.kaitran.ca/install | iex } ``` -### カスタムClaude CLIパス +
+

カスタムClaude CLIパス

 + +
Claude CLIが標準以外の場所（Dドライブ、カスタムディレクトリ）にインストールされている場合は、`CCS_CLAUDE_PATH`を設定してください： ```bash -export CCS_CLAUDE_PATH="/path/to/claude" # Unix -$env:CCS_CLAUDE_PATH = "D:\Tools\Claude\claude.exe" # Windows +# Unix/Linux/macOS +export CCS_CLAUDE_PATH="/path/to/claude" + +# Windows PowerShell +$env:CCS_CLAUDE_PATH = "D:\Tools\Claude\claude.exe" ``` -**詳細な設定手順については、[トラブルシューティングガイド](./docs/en/troubleshooting.md#claude-cli-in-non-standard-location)を参照してください。** +**参照**: [トラブルシューティングガイド](./docs/en/troubleshooting.md#claude-cli-in-non-standard-location) 詳細な設定手順 -### Windowsシンボリックリンクサポート（開発者モード） +
+ +
+

Windowsシンボリックリンクサポート（開発者モード）

 + +
**Windowsユーザー**: 本物のシンボリックリンクで高速な動作と即時同期を得るために開発者モードを有効にしてください： @@ -101,50 +113,73 @@ $env:CCS_CLAUDE_PATH = "D:\Tools\Claude\claude.exe" # Windows 2. **開発者モード** を有効にする 3. CCSを再インストール: `npm install -g @kaitranntt/ccs` -**開発者モードなし**: CCSは自動的にディレクトリコピーにフォールバック（動作しますが、プロファイル間の即時同期はありません） +**警告**: 開発者モードなしの場合、CCSは自動的にディレクトリコピーにフォールバック（動作しますが、プロファイル間の即時同期はありません） ---- +
+ +
### 最初の切り替え -> **⚠️ 重要**: GLM、GLMT、Kimiプロファイルを使用する前に、設定ファイルでAPIキーを更新してください： -> - **GLM**: `~/.ccs/glm.settings.json`を編集してGLM APIキーを追加 -> - **GLMT**: `~/.ccs/glmt.settings.json`を編集してZ.AI APIキーを追加（coding planが必要） +> [!IMPORTANT] +> **代替モデルを使用する前に、設定ファイルでAPIキーを更新してください：** +> +> - **GLM**: `~/.ccs/glm.settings.json`を編集してZ.AI Coding Plan APIキーを追加 +> - **GLMT**: `~/.ccs/glmt.settings.json`を編集してZ.AI Coding Plan APIキーを追加 > - **Kimi**: `~/.ccs/kimi.settings.json`を編集してKimi APIキーを追加 +
+ +**並列ワークフロー：計画 + 実行** + ```bash -# Claudeサブスクリプション（デフォルト） -ccs "マイクロサービスアーキテクチャの計画" +# Terminal 1 - 計画（Claude Sonnet） +ccs "認証とレート制限付きREST APIの計画" -# GLMに切り替え（コスト最適化） -ccs glm "REST APIを作成" - -# GLM with thinkingモード -ccs glmt "アルゴリズム問題を解決" - -# Kimi for Coding -ccs kimi "統合テストを作成" +# Terminal 2 - 実行（GLM、コスト最適化） +ccs glm "計画からユーザー認証エンドポイントを実装" ``` ---- +
+思考モデル（Kimi & GLMT） -## 日常の開発者の課題 +
+ +```bash +# Kimi - 安定した思考サポート +ccs kimi "トレードオフ分析付きキャッシュ戦略の設計" + +# GLMT - 実験的（詳細は下記参照） +ccs glmt "推論ステップ付き複雑なアルゴリズムのデバッグ" +``` + +**注**: GLMTは実験的で不安定です。詳細については下記の[GLM with Thinking (GLMT)](#glm-with-thinking-glmt)セクションを参照してください。 + +
+ +
+ +## 開発者の日常的な課題 + +**セッション制限がフロー状態を殺すべきではありません。** 開発者は日々多くのサブスクリプションシナリオに直面します： -1. **アカウント分離**: 会社のClaudeアカウントと個人のClaude → 業務と個人のコンテキストを手動で切り替える必要 -2. **レート制限**: Claudeがプロジェクト途中で停止 → 手動で`~/.claude/settings.json`を編集 -3. **コスト管理**: 2-3つのProサブスクリプション（月$20） vs Claude Maxの5倍コスト（月$100）→ Pro階層が実用的な上限 -4. **モデル選択**: タスクごとに異なるモデルの強みを活用 → 手動切り替え +1. **アカウント分離** - 会社のClaudeアカウント vs 個人Claude → 業務と個人のコンテキストを手動で切り替える必要 +2. **レート制限** - Claudeがプロジェクト途中で停止 → 手動で`~/.claude/settings.json`を編集 +3. **コスト管理** - 2-3つのProサブスクリプション（月$20） vs Claude Maxの5倍コスト（月$100）→ Pro階層が実用的な上限 +4. **モデル選択** - タスクごとに異なるモデルの強みを活用 → 手動切り替え -手動コンテキスト切り替えはワークフローを中断します。**CCSがシームレスに管理します**。 +**手動コンテキスト切り替えはワークフローを中断します。CCSがシームレスに管理します。** + +
## 手動切り替えではなくCCSを使う理由は？
-| 機能 | メリット | -|---------|---------| +| 機能 | 利益 | +|:--------|:--------| | **アカウント分離** | 業務と個人を分離 | | **コスト最適化** | 2-3つのProアカウント vs Max 5倍コスト | | **即座の切り替え** | 1コマンド、ファイル編集不要 | @@ -154,127 +189,91 @@ ccs kimi "統合テストを作成"
-**ソリューション**: -```bash -ccs work # 会社のClaudeアカウントを使用 -ccs personal # 個人Claudeアカウントに切り替え -ccs glm # コスト効率の良いタスク用にGLMに切り替え -ccs kimi # 代替オプション用にKimiに切り替え -# レート制限に達した？即座に切り替え： -ccs glm # GLMで作業を続行 -# 別の会社アカウントが必要？ -ccs work-2 # 2番目の会社アカウントに切り替え -``` +
---- +## アーキテクチャ -## 🏗️ アーキテクチャ概要 +### プロファイルタイプ -**v3.0 Login-Per-Profileモデル**: 各プロファイルは独立したClaudeインスタンスで、ユーザーが直接ログインします。資格情報のコピーやvault暗号化は不要です。 +**設定ベース**: GLM, GLMT, Kimi, default +- 設定ファイルを指す`--settings`フラグを使用 +- GLMT: 思考モードサポートの埋め込みプロキシ -```mermaid -flowchart TD - subgraph "ユーザー入力" - USER["ユーザー実行: ccs <profile> [args...]"] - end +**アカウントベース**: work, personal, team +- 分離されたインスタンスに`CLAUDE_CONFIG_DIR`を使用 +- `ccs auth create `で作成 - subgraph "プロファイル検出エンジン" - DETECT[ProfileDetector] - PROFILE_CHECK{プロファイル存在?} +### 共有データ（v3.1） - subgraph "プロファイルタイプ" - SETTINGS["Settings-based
glm, kimi, default"] - ACCOUNT["Account-based
work, personal, team"] - end - end +コマンドとスキルは`~/.ccs/shared/`からシンボリックリンク - プロファイル間の重複なし。 - subgraph "CCSコア処理" - CONFIG["config.jsonと
profiles.jsonを読み込み"] - - subgraph "プロファイルハンドラー" - SETTINGS_MGR["SettingsManager
→ --settings flag"] - INSTANCE_MGR["InstanceManager
→ CLAUDE_CONFIG_DIR"] - end - end - - subgraph "Claude CLI実行" - CLAUDE_DETECT["Claude CLI検出
CCS_CLAUDE_PATHサポート"] - - subgraph "実行方法" - SETTINGS_EXEC["claude --settings <path>"] - INSTANCE_EXEC["CLAUDE_CONFIG_DIR=<instance> claude"] - end - end - - subgraph "APIレイヤー" - API["API Response
Claude Sonnet 4.5
GLM 4.6
Kimi K2 Thinking"] - end - - %% Flow connections - USER --> DETECT - DETECT --> PROFILE_CHECK - PROFILE_CHECK -->|はい| SETTINGS - PROFILE_CHECK -->|はい| ACCOUNT - - SETTINGS --> CONFIG - ACCOUNT --> CONFIG - - CONFIG --> SETTINGS_MGR - CONFIG --> INSTANCE_MGR - - SETTINGS_MGR --> SETTINGS_EXEC - INSTANCE_MGR --> INSTANCE_EXEC - - SETTINGS_EXEC --> CLAUDE_DETECT - INSTANCE_EXEC --> CLAUDE_DETECT - - CLAUDE_DETECT --> API -``` - ---- - -## Architecture - -### Profile Types - -**Settings-based**: GLM, GLMT, Kimi, default -- Uses `--settings` flag pointing to config files -- GLMT: Embedded proxy for thinking mode support - -**Account-based**: work, personal, team -- Uses `CLAUDE_CONFIG_DIR` for isolated instances -- Create with `ccs auth create ` - -### Shared Data (v3.1) - -Commands and skills symlinked from `~/.ccs/shared/` - no duplication across profiles. - -``` +```plaintext ~/.ccs/ -├── shared/ # Shared across all profiles +├── shared/ # すべてのプロファイルで共有 │ ├── agents/ │ ├── commands/ │ └── skills/ -├── instances/ # Profile-specific data +├── instances/ # プロファイル固有のデータ │ └── work/ │ ├── agents@ → shared/agents/ │ ├── commands@ → shared/commands/ │ ├── skills@ → shared/skills/ -│ ├── settings.json # API keys, credentials -│ └── sessions/ # Conversation history +│ ├── settings.json # APIキー、認証情報 +│ ├── sessions/ # 会話履歴 │ └── ... ``` -**Shared**: commands/, skills/, agents/ -**Profile-specific**: settings.json, sessions/, todolists/, logs/ +| タイプ | ファイル | +|:-----|:------| +| **共有** | `commands/`, `skills/`, `agents/` | +| **プロファイル固有** | `settings.json`, `sessions/`, `todolists/`, `logs/` | -**[i] Windows**: Copies dirs if symlinks unavailable (enable Developer Mode for true symlinks) +> [!NOTE] +> **Windows**: シンボリックリンクが利用できない場合はディレクトリをコピー（本物のシンボリックリンクには開発者モードを有効にしてください） ---- +
+ +## 使用例 + +### 基本的な切り替え + +```bash +ccs # Claudeサブスクリプション（デフォルト） +ccs glm # GLM（コスト最適化） +ccs kimi # Kimi（思考サポート付き） +``` + +### マルチアカウント設定 + +```bash +# アカウントを作成 +ccs auth create work +ccs auth create personal +``` + +**別々のターミナルで同時に実行：** + +```bash +# Terminal 1 - 業務用 +ccs work "機能を実装" + +# Terminal 2 - 個人用（同時） +ccs personal "コードレビュー" +``` + +### ヘルプとバージョン + +```bash +ccs --version # バージョンを表示 +ccs --help # すべてのコマンドとオプションを表示 +``` + +
## GLM with Thinking (GLMT) -> **[!] 警告：本番環境未対応** +> [!CAUTION] +> ### 本番環境未対応 - 実験的機能 > > **GLMTは実験的で広範なデバッグが必要です**： > - ストリーミングとツールサポートはまだ開発中 @@ -282,14 +281,33 @@ Commands and skills symlinked from `~/.ccs/shared/` - no duplication across prof > - 頻繁なデバッグと手動介入が必要 > - **重要なワークフローや本番使用には推奨されません** > -> **GLM Thinkingの代替案**: **CCR hustle**と**BedollaのTransformer**（ZaiTransformer）を通じて、より安定した実装を検討してください。 -> -> **[!] 重要**: GLMTはnpmインストールが必要です（`npm install -g @kaitranntt/ccs`）。ネイティブシェルバージョンでは利用できません（Node.js HTTPサーバーが必要）。 +> **GLM Thinkingの代替案**: **CCR hustle**と**BedollaのTransformer**（[ZaiTransformer](https://github.com/Bedolla/ZaiTransformer/)）を通じて、より安定した実装を検討してください。 -### GLM vs GLMT +> [!IMPORTANT] +> GLMTはnpmインストールが必要です（`npm install -g @kaitranntt/ccs`）。ネイティブシェルバージョンでは利用できません（Node.js HTTPサーバーが必要）。 + +
+ +> [!NOTE] +> ### 謝辞：GLMTを可能にした基盤 +> +> **CCSのGLMT実装は、[@Bedolla](https://github.com/Bedolla)の画期的な仕事に存在を負っています**。彼は[Claude Code Router (CCR)](https://github.com/musistudio/claude-code-router)とZ.AIの推論能力をブリッジする[最初の統合](https://github.com/Bedolla/ZaiTransformer/)を作成しました。 +> +> ZaiTransformer以前、誰もZ.AIの思考モードとClaude Codeのワークフローを正常に統合できませんでした。Bedollaの仕事は単なる有用なものではなく、**基盤的**でした。彼のリクエスト/レスポンストランスフォーメーションアーキテクチャ、思考モード制御メカニズム、埋め込みプロキシ設計の実装は、GLMTの設計に直接インスピレーションを与え、可能にしました。 +> +> **ZaiTransformerの先駆的な仕事なしでは、GLMTは現在の形では存在しませんでした。** GLMTの思考能力から利益を得る場合は、Claude Codeエコシステムでの先駆的な仕事をサポートするために[ZaiTransformer](https://github.com/Bedolla/ZaiTransformer/)にスターを付けてください。 + +
+ +
+

GLM vs GLMT 比較

 + +
+ +
| 機能 | GLM (`ccs glm`) | GLMT (`ccs glmt`) | -|-----|-----------------|-------------------| +|:--------|:----------------|:------------------| | **エンドポイント** | Anthropic互換 | OpenAI互換 | | **思考** | なし | 実験的（reasoning_content） | | **ツールサポート** | 基本的 | **不安定（v3.5+）** | @@ -298,48 +316,173 @@ Commands and skills symlinked from `~/.ccs/shared/` - no duplication across prof | **TTFB** | <500ms | <500ms（時々）、2-10秒+（頻繁） | | **使用例** | 信頼性の高い作業 | **デバッグ実験のみ** | ---- +
-## ⚡ 機能 +
-- **即座の切り替え** - `ccs glm`でGLMに切り替え、設定編集不要 -- **同時セッション** - 複数のプロファイルを異なるターミナルで同時実行 -- **独立したインスタンス** - 各プロファイルが独自の設定を保持 (`~/.ccs/instances//`) -- **クロスプラットフォーム** - macOS、Linux、Windows - 同一動作 -- **ダウンタイムなし** - 即座に切り替え、ワークフロー中断なし +
+
+

ツールサポート（v3.5） - 実験的

 ---- +
-## 💻 使用例 +**GLMTはMCPツールと関数呼び出しを試行：** + +- **双方向トランスフォーメーション**: Anthropicツール ↔ OpenAI形式（不安定） +- **MCP統合**: MCPツールが時々実行（多くの場合XMLガベージを出力） +- **ストリーミングツール呼び出し**: リアルタイムツール呼び出し（クラッシュしない場合） +- **後方互換**: 既存の思考サポートを破壊する可能性 +- **設定が必要**: 頻繁な手動デバッグが必要 + +
+ +
+

ストリーミングサポート（v3.4） - しばしば失敗

 + +
+ +**GLMTは増分推論コンテンツ配信でリアルタイムストリーミングを試行：** + +- **デフォルト**: ストリーミング有効（動作時TTFB <500ms） +- **自動フォールバック**: エラーにより頻繁にバッファモードに切り替え +- **思考パラメータ**: Claude CLI `thinking`パラメータが時々動作 + - `thinking.type`と`budget_tokens`を無視する場合 + - 優先順位: CLIパラメータ > メッセージタグ > デフォルト（破壊されていない場合） + +**ステータス**: Z.AI（テスト済み、ツール呼び出しが頻繁に破壊、継続的なデバッグが必要） + +
+ +
+

動作原理（動作時）

 + +
+ +1. CCSがlocalhostに埋め込みHTTPプロキシを生成（クラッシュしない場合） +2. プロキシがAnthropic形式 → OpenAI形式への変換を試行（多くの場合失敗） +3. Anthropicツール → OpenAI関数呼び出し形式への変換を試行（バグあり） +4. 推論パラメータとツールを付けてZ.AIに転送（タイムアウトしない場合） +5. `reasoning_content` → 思考ブロックへの変換を試行（部分的または破壊） +6. OpenAI `tool_calls` → Anthropic `tool_use` ブロックへの変換を試行（XMLガベージが一般的） +7. 思考とツール呼び出しが時々Claude Code UIに表示（破壊されていない場合） + +
+ +
+

制御タグとキーワード

 + +
+ +**制御タグ**: +- `` - 推論ブロックの有効/無効（デフォルト: On） +- `` - 推論深度の制御（非推奨 - Z.AIはバイナリ思考のみサポート） + +**思考キーワード**（不安定なアクティベーション）: +- `think` - 時々推論を有効化（低労力） +- `think hard` - 時々推論を有効化（中労力） +- `think harder` - 時々推論を有効化（高労力） +- `ultrathink` - 最大推論深度を試行（多くの場合破壊） + +
+ +
+

環境変数

 + +
+ +**GLMT機能**（すべて実験的）: +- 強制的な英語出力強制（時々動作） +- ランダムな思考モードアクティベーション（予測不可能） +- 頻繁なバッファモードへのフォールバック付きストリーミング試行 + +**一般**: +- `CCS_DEBUG_LOG=1` - デバッグファイルロギングを有効化 +- `CCS_CLAUDE_PATH=/path/to/claude` - カスタムClaude CLIパス + +
+ +
+

APIキー設定

 + +
```bash -ccs # Claudeサブスクリプション（デフォルト） -ccs glm # GLM（thinkingなし） -ccs glmt # GLM with thinking -ccs kimi # Kimi for Coding -ccs --version # バージョン表示 +# GLMT設定を編集 +nano ~/.ccs/glmt.settings.json ``` -### 同時セッション (Multi-Account) +Z.AI APIキーを設定（コーディングプランが必要）： + +```json +{ + "env": { + "ANTHROPIC_AUTH_TOKEN": "your-z-ai-api-key" + } +} +``` + +
+ +
+

セキュリティ制限（DoS保護）

 + +
+ +**v3.4 保護制限**: + +| 制限 | 値 | 目的 | +|:------|:------|:--------| +| **SSEバッファ** | イベントあたり最大1MB | バッファオーバーフローを防止 | +| **コンテンツバッファ** | ブロックあたり最大10MB | 思考/テキストブロックを制限 | +| **コンテンツブロック** | メッセージあたり最大100 | DoS攻撃を防止 | +| **リクエストタイムアウト** | 120秒 | ストリーミングとバッファの両方 | + +
+ +
+

デバッグ

 + +
+ +**詳細ロギングを有効化**: ```bash -# 複数のClaudeアカウントを作成 -ccs auth create work # 業務用アカウント -ccs auth create personal # 個人用アカウント -ccs auth create team # チーム用アカウント - -# ターミナル1 - 業務用アカウント -ccs work "implement feature" - -# ターミナル2 - 個人用アカウント（同時実行） -ccs personal "review code" +ccs glmt --verbose "your prompt" ``` ---- +**デバッグファイルロギングを有効化**: +```bash +export CCS_DEBUG_LOG=1 +ccs glmt --verbose "your prompt" +# ログ: ~/.ccs/logs/ +``` -### 🗑️ アンインストール +**GLMTデバッグ**: +```bash +# 詳細ロギングでストリーミングステータスと推論詳細を表示 +ccs glmt --verbose "test" +``` + +**推論コンテンツを確認**: +```bash +cat ~/.ccs/logs/*response-openai.json | jq '.choices[0].message.reasoning_content' +``` + +**トラブルシューティング**: +- **存在しない場合**: Z.AI APIの問題（キー、アカウントステータスを確認） +- **存在する場合**: トランスフォーメーションの問題（`response-anthropic.json`を確認） + +
+ +
+ +## アンインストール + +
+

パッケージマネージャー

 + +
-**パッケージマネージャー** ```bash # npm npm uninstall -g @kaitranntt/ccs @@ -354,19 +497,24 @@ pnpm remove -g @kaitranntt/ccs bun remove -g @kaitranntt/ccs ``` -**公式アンインストーラー** +
+ +
+

公式アンインストーラー

 + +
-**macOS / Linux** ```bash +# macOS / Linux curl -fsSL ccs.kaitran.ca/uninstall | bash -``` -**Windows PowerShell** -```powershell +# Windows PowerShell irm ccs.kaitran.ca/uninstall | iex ``` ---- +
+ +
## 🎯 哲学 @@ -374,37 +522,38 @@ irm ccs.kaitran.ca/uninstall | iex - **KISS**: シンプルなbash、複雑さなし - **DRY**: 単一の情報源（設定） ---- - ## 📖 ドキュメント **[docs/](./docs/)の完全なドキュメント**: - [インストールガイド](./docs/en/installation.md) - [設定](./docs/en/configuration.md) - [使用例](./docs/en/usage.md) -- [System Architecture](./docs/system-architecture.md) -- [GLMT Control Mechanisms](./docs/glmt-controls.md) +- [システムアーキテクチャ](./docs/system-architecture.md) +- [GLMT制御メカニズム](./docs/glmt-controls.md) - [トラブルシューティング](./docs/en/troubleshooting.md) -- [コントリビューション](./CONTRIBUTING.md) +- [貢献](./CONTRIBUTING.md) ---- +## 🤝 貢献 -## 🤝 コントリビューション +貢献を歓迎します！詳細については[貢献ガイド](./CONTRIBUTING.md)をご覧ください。 -コントリビューションを歓迎します！詳細については[コントリビューションガイド](./CONTRIBUTING.md)をご覧ください。 +## Star History ---- +
-## 📄 ライセンス +Star History Chart + +
+ + +## ライセンス CCSは[MITライセンス](LICENSE)の下でライセンスされています。 ---- -
**レート制限に頻繁に遭遇する開発者のために ❤️ を込めて作成** [⭐ このリポジトリにスター](https://github.com/kaitranntt/ccs) | [🐛 問題を報告](https://github.com/kaitranntt/ccs/issues) | [📖 ドキュメントを読む](./docs/en/) -
+ \ No newline at end of file diff --git a/README.md b/README.md index 007955e4..a3d51069 100644 --- a/README.md +++ b/README.md @@ -1,12 +1,12 @@ -# CCS - Claude Code Switch -
+# CCS - Claude Code Switch + ![CCS Logo](docs/assets/ccs-logo-medium.png) -**One command, zero downtime, multiple accounts** +### One command, zero downtime, multiple accounts -Switch between multiple Claude accounts, GLM, and Kimi instantly.
+**Switch between multiple Claude accounts, GLM, and Kimi instantly.**
Stop hitting rate limits. Keep working continuously. @@ -19,27 +19,20 @@ Stop hitting rate limits. Keep working continuously.
---- +
-## 🚀 Quick Start - -### 🔑 Prerequisites - -**Before installing CCS, make sure you're logged into Claude CLI with your subscription account:** -```bash -claude /login -``` +## Quick Start ### Installation -#### Option 1: npm Package (Recommended) +**npm Package (Recommended)** **macOS / Linux / Windows** ```bash npm install -g @kaitranntt/ccs ``` -All major package managers are supported: +**All major package managers are supported:** ```bash # yarn @@ -52,7 +45,10 @@ pnpm add -g @kaitranntt/ccs bun add -g @kaitranntt/ccs ``` -#### Option 2: Direct Install (Traditional) +
+Alternative: Direct Install (Traditional) + +
**macOS / Linux** ```bash @@ -64,7 +60,11 @@ curl -fsSL ccs.kaitran.ca/install | bash irm ccs.kaitran.ca/install | iex ``` -> **💡 Performance Tip**: Traditional installs bypass Node.js routing for faster startup, but I prioritize npm updates due to easier deployment automation. +**Note:** Traditional installs bypass Node.js routing for faster startup, but npm is prioritized for easier deployment automation. + +
+ +
### Configuration (Auto-created) @@ -82,7 +82,10 @@ irm ccs.kaitran.ca/install | iex } ``` -### Custom Claude CLI Path +
+

Custom Claude CLI Path

 + +
If Claude CLI is installed in a non-standard location (D drive, custom directory), set `CCS_CLAUDE_PATH`: @@ -91,9 +94,14 @@ export CCS_CLAUDE_PATH="/path/to/claude" # Unix $env:CCS_CLAUDE_PATH = "D:\Tools\Claude\claude.exe" # Windows ``` -**See [Troubleshooting Guide](./docs/en/troubleshooting.md#claude-cli-in-non-standard-location) for detailed setup instructions.** +**See also:** [Troubleshooting Guide](./docs/en/troubleshooting.md#claude-cli-in-non-standard-location) for detailed setup instructions. -### Windows Symlink Support (Developer Mode) +
+ +
+

Windows Symlink Support (Developer Mode)

 + +
**Windows users**: Enable Developer Mode for true symlinks (better performance, instant sync): @@ -101,50 +109,73 @@ $env:CCS_CLAUDE_PATH = "D:\Tools\Claude\claude.exe" # Windows 2. Enable **Developer Mode** 3. Reinstall CCS: `npm install -g @kaitranntt/ccs` -**Without Developer Mode**: CCS automatically falls back to copying directories (works but no instant sync across profiles). +**Warning:** Without Developer Mode, CCS automatically falls back to copying directories (works but no instant sync across profiles). ---- +
+ +
### Your First Switch -> **⚠️ Important**: Before using GLM/GLMT or Kimi profiles, update API keys in settings files: -> - **GLM**: Edit `~/.ccs/glm.settings.json` and add your GLM API key -> - **GLMT**: Edit `~/.ccs/glmt.settings.json` and add your Z.AI API key (requires coding plan) +> [!IMPORTANT] +> **Before using alternative models, update API keys in settings files:** +> +> - **GLM**: Edit `~/.ccs/glm.settings.json` and add your Z.AI Coding Plan API Key +> - **GLMT**: Edit `~/.ccs/glmt.settings.json` and add your Z.AI Coding Plan API Key > - **Kimi**: Edit `~/.ccs/kimi.settings.json` and add your Kimi API key +
+ +**Parallel Workflow: Planning + Execution** + ```bash -# Default Claude subscription -ccs "Plan microservices architecture" +# Terminal 1 - Planning (Claude Sonnet) +ccs "Plan a REST API with authentication and rate limiting" -# Switch to GLM (cost-optimized) -ccs glm "Create REST API" - -# GLM with thinking mode -ccs glmt "Solve algorithmic problem" - -# Kimi for coding -ccs kimi "Write integration tests" +# Terminal 2 - Execution (GLM, cost-optimized) +ccs glm "Implement the user authentication endpoints from the plan" ``` ---- +
+Thinking Models (Kimi & GLMT) + +
+ +```bash +# Kimi - Stable thinking support +ccs kimi "Design a caching strategy with trade-off analysis" + +# GLMT - Experimental (see full disclaimer below) +ccs glmt "Debug complex algorithm with reasoning steps" +``` + +**Note:** GLMT is experimental and unstable. See [GLM with Thinking (GLMT)](#glm-with-thinking-glmt) section below for full details. + +
+ +
## The Daily Developer Pain Point +**Session limits shouldn't kill your flow state.** + Developers face multiple subscription scenarios daily: -1. **Account Separation**: Company Claude account vs personal Claude → you must manually switch contexts to keep work and personal separate -2. **Rate Limits Hit**: Claude stops mid-project → you manually edit `~/.claude/settings.json` -3. **Cost Management**: 2-3 Pro subscriptions ($20/month each) vs Claude Max at 5x cost ($100/month) → Pro tier is the practical ceiling for most developers -4. **Model Choice**: Different tasks benefit from different model strengths → manual switching +1. **Account Separation** - Company Claude account vs personal Claude → you must manually switch contexts to keep work and personal separate +2. **Rate Limits Hit** - Claude stops mid-project → you manually edit `~/.claude/settings.json` +3. **Cost Management** - 2-3 Pro subscriptions ($20/month each) vs Claude Max at 5x cost ($100/month) → Pro tier is the practical ceiling for most developers +4. **Model Choice** - Different tasks benefit from different model strengths → manual switching -Manual context switching breaks your workflow. **CCS manages it seamlessly**. +**Manual context switching breaks your workflow. CCS manages it seamlessly.** + +
## Why CCS Instead of Manual Switching?
| Feature | Benefit | -|---------|---------| +|:--------|:--------| | **Account Isolation** | Keep work separate from personal | | **Cost Optimization** | 2-3 Pro accounts vs Max at 5x cost | | **Instant Switching** | One command, no file editing | @@ -154,7 +185,7 @@ Manual context switching breaks your workflow. **CCS manages it seamlessly**.
---- +
## Architecture @@ -170,9 +201,9 @@ Manual context switching breaks your workflow. **CCS manages it seamlessly**. ### Shared Data (v3.1) -Commands and skills symlinked from `~/.ccs/shared/` - no duplication across profiles. +Commands and skills symlinked from `~/.ccs/shared/` - **no duplication across profiles**. -``` +```plaintext ~/.ccs/ ├── shared/ # Shared across all profiles │ ├── agents/ @@ -184,56 +215,61 @@ Commands and skills symlinked from `~/.ccs/shared/` - no duplication across prof │ ├── commands@ → shared/commands/ │ ├── skills@ → shared/skills/ │ ├── settings.json # API keys, credentials -│ └── sessions/ # Conversation history +│ ├── sessions/ # Conversation history │ └── ... ``` -**Shared**: commands/, skills/, agents/ -**Profile-specific**: settings.json, sessions/, todolists/, logs/ +| Type | Files | +|:-----|:------| +| **Shared** | `commands/`, `skills/`, `agents/` | +| **Profile-specific** | `settings.json`, `sessions/`, `todolists/`, `logs/` | -**[i] Windows**: Copies dirs if symlinks unavailable (enable Developer Mode for true symlinks) +> [!NOTE] +> **Windows**: Copies directories if symlinks unavailable (enable Developer Mode for true symlinks) ---- +
## Usage Examples ### Basic Switching + ```bash ccs # Claude subscription (default) -ccs glm # GLM (no thinking) -ccs glmt # GLM with thinking -ccs kimi # Kimi for Coding -ccs --version # Show version +ccs glm # GLM (cost-optimized) +ccs kimi # Kimi (with thinking support) ``` ### Multi-Account Setup + ```bash # Create accounts ccs auth create work ccs auth create personal +``` -# Terminal 1 +**Run concurrently in separate terminals:** + +```bash +# Terminal 1 - Work ccs work "implement feature" -# Terminal 2 (concurrent) +# Terminal 2 - Personal (concurrent) ccs personal "review code" ``` -### Custom Claude CLI Path +### Help & Version -Non-standard installation location: ```bash -export CCS_CLAUDE_PATH="/path/to/claude" # Unix -$env:CCS_CLAUDE_PATH = "D:\Tools\Claude\claude.exe" # Windows +ccs --version # Show version +ccs --help # Show all commands and options ``` -See [Troubleshooting Guide](./docs/en/troubleshooting.md#claude-cli-in-non-standard-location) - ---- +
## GLM with Thinking (GLMT) -> **[!] WARNING: NOT PRODUCTION READY** +> [!CAUTION] +> ### NOT PRODUCTION READY - EXPERIMENTAL FEATURE > > **GLMT is experimental and requires extensive debugging**: > - Streaming and tool support still under active development @@ -241,13 +277,15 @@ See [Troubleshooting Guide](./docs/en/troubleshooting.md#claude-cli-in-non-stand > - Requires frequent debugging and manual intervention > - **Not recommended for critical workflows or production use** > -> **Alternative for GLM Thinking**: Consider going through the **CCR hustle** with the **Transformer of Bedolla** (ZaiTransformer) for a more stable implementation. -> -> **[!] Important**: GLMT requires npm installation (`npm install -g @kaitranntt/ccs`). Not available in native shell versions (requires Node.js HTTP server). +> **Alternative for GLM Thinking**: Consider going through the **CCR hustle** with the **Transformer of Bedolla** ([ZaiTransformer](https://github.com/Bedolla/ZaiTransformer/)) for a more stable implementation. -### Acknowledgments: The Foundation That Made GLMT Possible +> [!IMPORTANT] +> GLMT requires npm installation (`npm install -g @kaitranntt/ccs`). Not available in native shell versions (requires Node.js HTTP server). -> **[i] Pioneering Work by [@Bedolla](https://github.com/Bedolla)** +
+ +> [!NOTE] +> ### Acknowledgments: The Foundation That Made GLMT Possible > > **CCS's GLMT implementation owes its existence to the groundbreaking work of [@Bedolla](https://github.com/Bedolla)**, who created [ZaiTransformer](https://github.com/Bedolla/ZaiTransformer/) - the **first integration** to bridge [Claude Code Router (CCR)](https://github.com/musistudio/claude-code-router) with Z.AI's reasoning capabilities. > @@ -261,23 +299,37 @@ See [Troubleshooting Guide](./docs/en/troubleshooting.md#claude-cli-in-non-stand > > **Recognition**: If you benefit from GLMT's thinking capabilities, you're benefiting from Bedolla's vision and engineering. Please consider starring [ZaiTransformer](https://github.com/Bedolla/ZaiTransformer/) to support pioneering work in the Claude Code ecosystem. ---- +
-### GLM vs GLMT +
+

GLM vs GLMT Comparison

 + +
+ +
| Feature | GLM (`ccs glm`) | GLMT (`ccs glmt`) | -|---------|-----------------|-------------------| +|:--------|:----------------|:------------------| | **Endpoint** | Anthropic-compatible | OpenAI-compatible | -| **Thinking** | No | Experimental (reasoning_content) | +| **Thinking** | No | Experimental (`reasoning_content`) | | **Tool Support** | Basic | **Unstable (v3.5+)** | | **MCP Tools** | Limited | **Buggy (v3.5+)** | | **Streaming** | Stable | **Experimental (v3.4+)** | | **TTFB** | <500ms | <500ms (sometimes), 2-10s+ (often) | | **Use Case** | Reliable work | **Debugging experiments only** | -### Tool Support (v3.5) +
-**GLMT attempts MCP tools and function calling (EXPERIMENTAL)**: +
+ +
+ +
+

Tool Support (v3.5) - EXPERIMENTAL

 + +
+ +**GLMT attempts MCP tools and function calling:** - **Bidirectional Transformation**: Anthropic tools ↔ OpenAI format (unstable) - **MCP Integration**: MCP tools sometimes execute (often output XML garbage) @@ -285,9 +337,14 @@ See [Troubleshooting Guide](./docs/en/troubleshooting.md#claude-cli-in-non-stand - **Backward Compatible**: May break existing thinking support - **Configuration Required**: Frequent manual debugging needed -### Streaming Support (v3.4) +
-**GLMT attempts real-time streaming** with incremental reasoning content delivery (OFTEN FAILS). +
+

Streaming Support (v3.4) - OFTEN FAILS

 + +
+ +**GLMT attempts real-time streaming** with incremental reasoning content delivery: - **Default**: Streaming enabled (TTFB <500ms when it works) - **Auto-fallback**: Frequently switches to buffered mode due to errors @@ -295,19 +352,29 @@ See [Troubleshooting Guide](./docs/en/troubleshooting.md#claude-cli-in-non-stand - May ignore `thinking.type` and `budget_tokens` - Precedence: CLI parameter > message tags > default (when not broken) -**Barely working**: Z.AI (tested, tool calls frequently break, requires constant debugging) +**Status**: Z.AI (tested, tool calls frequently break, requires constant debugging) -### How It Works (When It Works) +
+ +
+

How It Works (When It Works)

 + +
1. CCS spawns embedded HTTP proxy on localhost (if not crashing) 2. Proxy attempts to convert Anthropic format → OpenAI format (often fails) 3. Tries to transform Anthropic tools → OpenAI function calling format (buggy) 4. Forwards to Z.AI with reasoning parameters and tools (when not timing out) 5. Attempts to convert `reasoning_content` → thinking blocks (partial or broken) -6. Attempts to convert OpenAI `tool_calls` → Anthropic tool_use blocks (XML garbage common) +6. Attempts to convert OpenAI `tool_calls` → Anthropic `tool_use` blocks (XML garbage common) 7. Thinking and tool calls sometimes appear in Claude Code UI (when not broken) -### Control Tags & Keywords +
+ +
+

Control Tags & Keywords

 + +
**Control Tags**: - `` - Enable/disable reasoning blocks (default: On) @@ -319,7 +386,12 @@ See [Troubleshooting Guide](./docs/en/troubleshooting.md#claude-cli-in-non-stand - `think harder` - Sometimes enables reasoning (high effort) - `ultrathink` - Attempts maximum reasoning depth (often breaks) -### Environment Variables +
+ +
+

Environment Variables

 + +
**GLMT features** (all experimental): - Forced English output enforcement (sometimes works) @@ -330,13 +402,21 @@ See [Troubleshooting Guide](./docs/en/troubleshooting.md#claude-cli-in-non-stand - `CCS_DEBUG_LOG=1` - Enable debug file logging - `CCS_CLAUDE_PATH=/path/to/claude` - Custom Claude CLI path -### API Key Setup +
+ +
+

API Key Setup

 + +
```bash # Edit GLMT settings nano ~/.ccs/glmt.settings.json +``` -# Set Z.AI API key (requires coding plan) +Set Z.AI API key (requires coding plan): + +```json { "env": { "ANTHROPIC_AUTH_TOKEN": "your-z-ai-api-key" @@ -344,15 +424,28 @@ nano ~/.ccs/glmt.settings.json } ``` -### Security Limits +
-**DoS protection** (v3.4): -- SSE buffer: 1MB max per event -- Content buffer: 10MB max per block (thinking/text) -- Content blocks: 100 max per message -- Request timeout: 120s (both streaming and buffered) +
+

Security Limits (DoS Protection)

 -### Debugging +
+ +**v3.4 Protection Limits**: + +| Limit | Value | Purpose | +|:------|:------|:--------| +| **SSE buffer** | 1MB max per event | Prevent buffer overflow | +| **Content buffer** | 10MB max per block | Limit thinking/text blocks | +| **Content blocks** | 100 max per message | Prevent DoS attacks | +| **Request timeout** | 120s | Both streaming and buffered | + +
+ +
+

Debugging

 + +
**Enable verbose logging**: ```bash @@ -377,31 +470,53 @@ ccs glmt --verbose "test" cat ~/.ccs/logs/*response-openai.json | jq '.choices[0].message.reasoning_content' ``` -**If absent**: Z.AI API issue (verify key, account status) -**If present**: Transformation issue (check response-anthropic.json) +**Troubleshooting**: +- **If absent**: Z.AI API issue (verify key, account status) +- **If present**: Transformation issue (check `response-anthropic.json`) ---- +
+ +
## Uninstall -**Package Managers** +
+

Package Managers

 + +
+ ```bash +# npm npm uninstall -g @kaitranntt/ccs + +# yarn yarn global remove @kaitranntt/ccs + +# pnpm pnpm remove -g @kaitranntt/ccs + +# bun bun remove -g @kaitranntt/ccs ``` -**Official Uninstaller** +
+ +
+

Official Uninstaller

 + +
+ ```bash # macOS / Linux curl -fsSL ccs.kaitran.ca/uninstall | bash -# Windows +# Windows PowerShell irm ccs.kaitran.ca/uninstall | iex ``` ---- +
+ +
## 🎯 Philosophy @@ -409,8 +524,6 @@ irm ccs.kaitran.ca/uninstall | iex - **KISS**: Simple bash, no complexity - **DRY**: One source of truth (config) ---- - ## 📖 Documentation **Complete documentation in [docs/](./docs/)**: @@ -422,20 +535,24 @@ irm ccs.kaitran.ca/uninstall | iex - [Troubleshooting](./docs/en/troubleshooting.md) - [Contributing](./CONTRIBUTING.md) ---- - ## 🤝 Contributing We welcome contributions! Please see our [Contributing Guide](./CONTRIBUTING.md) for details. ---- -## 📄 License +## Star History + +
+ +Star History Chart + +
+ + +## License CCS is licensed under the [MIT License](LICENSE). ---- -
**Made with ❤️ for developers who hit rate limits too often** diff --git a/README.vi.md b/README.vi.md index 0a93693d..15c7ff5f 100644 --- a/README.vi.md +++ b/README.vi.md @@ -1,45 +1,39 @@ -# CCS - Claude Code Switch -
+# CCS - Claude Code Switch + ![CCS Logo](docs/assets/ccs-logo-medium.png) -**Một lệnh, không downtime, nhiều tài khoản** +### Một lệnh, không downtime, nhiều tài khoản -Chuyển đổi giữa nhiều tài khoản Claude, GLM, và Kimi ngay lập tức.
+**Chuyển đổi giữa nhiều tài khoản Claude, GLM, và Kimi ngay lập tức.** Ngừng hitting rate limits. Làm việc liên tục. +
[![License](https://img.shields.io/badge/license-MIT-C15F3C?style=for-the-badge)](LICENSE) [![Platform](https://img.shields.io/badge/platform-macOS%20%7C%20Linux%20%7C%20Windows-lightgrey?style=for-the-badge)]() [![npm](https://img.shields.io/npm/v/@kaitranntt/ccs?style=for-the-badge&logo=npm)](https://www.npmjs.com/package/@kaitranntt/ccs) [![PoweredBy](https://img.shields.io/badge/PoweredBy-ClaudeKit-C15F3C?style=for-the-badge)](https://claudekit.cc?ref=HMNKXOHN) -**Ngôn ngữ**: [English](README.md) | [Tiếng Việt](README.vi.md) | [日本語](README.ja.md) +**Languages**: [English](README.md) · [Tiếng Việt](README.vi.md) · [日本語](README.ja.md)
---- +
-## 🚀 Bắt Đầu Nhanh +## Bắt Đầu Nhanh -### 🔑 Điều Kiện Tiên Quyết +### Cài Đặt -**Trước khi cài đặt CCS, hãy đảm bảo bạn đã đăng nhập vào Claude CLI với tài khoản subscription:** -```bash -claude /login -``` - -### Phương Pháp Cài Đặt Chính - -#### Option 1: npm Package (Được khuyến nghị) +**npm Package (Được khuyến nghị)** **macOS / Linux / Windows** ```bash npm install -g @kaitranntt/ccs ``` -Tất cả các trình quản lý package chính đều được hỗ trợ: +**Tất cả các trình quản lý package chính đều được hỗ trợ:** ```bash # yarn @@ -52,7 +46,10 @@ pnpm add -g @kaitranntt/ccs bun add -g @kaitranntt/ccs ``` -#### Option 2: Cài Đặt Trực Tiếp (Truyền thống) +
+Phương án thay thế: Cài Đặt Trực Tiếp (Truyền thống) + +
**macOS / Linux** ```bash @@ -64,7 +61,11 @@ curl -fsSL ccs.kaitran.ca/install | bash irm ccs.kaitran.ca/install | iex ``` -> **💡 Mẹo hiệu năng**: Cài truyền thống bỏ qua Node.js routing để khởi động nhanh hơn, nhưng tôi ưu tiên cập nhật npm do triển khai dễ dàng hơn. +**Lưu ý**: Cài truyền thống bỏ qua Node.js routing để khởi động nhanh hơn, nhưng ưu tiên npm cho dễ dàng tự động hóa triển khai. + +
+ +
### Cấu Hình (Tự Tạo) @@ -82,18 +83,29 @@ irm ccs.kaitran.ca/install | iex } ``` -### Đường Dẫn Claude CLI Tùy Chỉnh +
+

Custom Claude CLI Path

 + +
Nếu Claude CLI được cài đặt ở vị trí không chuẩn (ổ D, thư mục tùy chỉnh), đặt `CCS_CLAUDE_PATH`: ```bash -export CCS_CLAUDE_PATH="/path/to/claude" # Unix -$env:CCS_CLAUDE_PATH = "D:\Tools\Claude\claude.exe" # Windows +# Unix/Linux/macOS +export CCS_CLAUDE_PATH="/path/to/claude" + +# Windows PowerShell +$env:CCS_CLAUDE_PATH = "D:\Tools\Claude\claude.exe" ``` -**Xem [Hướng dẫn Khắc phục Sự cố](./docs/vi/troubleshooting.vi.md#claude-cli-ở-vị-trí-không-chuẩn) để biết chi tiết cài đặt.** +**Xem thêm**: [Hướng dẫn Khắc phục Sự cố](./docs/en/troubleshooting.md#claude-cli-in-non-standard-location) để biết chi tiết cài đặt. -### Hỗ Trợ Symlink Windows (Chế Độ Nhà Phát Triển) +
+ +
+

Windows Symlink Support (Developer Mode)

 + +
**Người dùng Windows**: Bật Chế độ Nhà phát triển để có symlink thực sự (hiệu suất tốt hơn, đồng bộ hóa tức thì): @@ -101,137 +113,83 @@ $env:CCS_CLAUDE_PATH = "D:\Tools\Claude\claude.exe" # Windows 2. Bật **Developer Mode** 3. Cài đặt lại CCS: `npm install -g @kaitranntt/ccs` -**Nếu không có Chế độ Nhà phát triển**: CCS tự động chuyển sang sao chép thư mục (hoạt động nhưng không đồng bộ tức thì trên các profile). +**Cảnh báo**: Nếu không có Chế độ Nhà phát triển, CCS tự động chuyển sang sao chép thư mục (hoạt động nhưng không đồng bộ tức thì trên các profile). ---- +
+ +
### Lần Chuyển Đổi Đầu Tiên -> **⚠️ Quan trọng**: Trước khi dùng GLM, GLMT hay Kimi profile, cập nhật API key trong file settings: -> - **GLM**: Chỉnh sửa `~/.ccs/glm.settings.json` và thêm GLM API key -> - **GLMT**: Chỉnh sửa `~/.ccs/glmt.settings.json` và thêm Z.AI API key (yêu cầu coding plan) -> - **Kimi**: Chỉnh sửa `~/.ccs/kimi.settings.json` và thêm Kimi API key +> [!IMPORTANT] +> **Trước khi dùng các mô hình thay thế, cập nhật API keys trong file settings:** +> +> - **GLM**: Chỉnh sửa `~/.ccs/glm.settings.json` và thêm Z.AI Coding Plan API Key của bạn +> - **GLMT**: Chỉnh sửa `~/.ccs/glmt.settings.json` và thêm Z.AI Coding Plan API Key của bạn +> - **Kimi**: Chỉnh sửa `~/.ccs/kimi.settings.json` và thêm Kimi API key của bạn + +
+ +**Parallel Workflow: Planning + Execution** ```bash -# Claude subscription mặc định -ccs "Lên kế hoạch kiến trúc microservices" +# Terminal 1 - Planning (Claude Sonnet) +ccs "Plan a REST API with authentication and rate limiting" -# Chuyển sang GLM (tối ưu chi phí) -ccs glm "Tạo REST API" - -# GLM với thinking mode -ccs glmt "Giải quyết bài toán thuật toán" - -# Kimi cho lập trình -ccs kimi "Viết integration tests" +# Terminal 2 - Execution (GLM, cost-optimized) +ccs glm "Implement the user authentication endpoints from the plan" ``` ---- +
+Thinking Models (Kimi & GLMT) -## Điểm Đau Hàng Ngày Của Lập Trình Viên +
-Lập trình viên đối mặt nhiều kịch bản subscription hàng ngày: +```bash +# Kimi - Stable thinking support +ccs kimi "Design a caching strategy with trade-off analysis" -1. **Phân Tách Account**: Tài khoản Claude công ty vs Claude cá nhân → bạn phải tự chuyển context để giữ công việc và cá nhân riêng biệt -2. **Hết Rate Limit**: Claude dừng giữa chừng project → bạn phải tự tay sửa `~/.claude/settings.json` -3. **Quản Lý Chi Phí**: 2-3 subscriptions Pro ($20/tháng) vs Claude Max với chi phí 5x ($100/tháng) → Tier Pro là ngưỡng thực tế cho hầu hết lập trình viên -4. **Lựa Chọn Model**: Tác vụ khác nhau hưởng lợi từ thế mạnh model khác nhau → chuyển đổi thủ công +# GLMT - Experimental (see full disclaimer below) +ccs glmt "Debug complex algorithm with reasoning steps" +``` -Chuyển đổi context thủ công làm gián đoạn workflow. **CCS quản lý liền mạch**. +**Lưu ý:** GLMT là thử nghiệm và không ổn định. Xem phần [GLM with Thinking (GLMT)](#glm-with-thinking-glmt) dưới đây để biết chi tiết. -## Tại Sao CCS Thay Vì Chuyển Đổi Thủ Công? +
+ +
+ +## The Daily Developer Pain Point + +**Session limits shouldn't kill your flow state.** + +Developers face multiple subscription scenarios daily: + +1. **Account Separation** - Company Claude account vs personal Claude → you must manually switch contexts to keep work and personal separate +2. **Rate Limits Hit** - Claude stops mid-project → you manually edit `~/.claude/settings.json` +3. **Cost Management** - 2-3 Pro subscriptions ($20/month each) vs Claude Max at 5x cost ($100/month) → Pro tier is the practical ceiling for most developers +4. **Model Choice** - Different tasks benefit from different model strengths → manual switching + +**Manual context switching breaks your workflow. CCS manages it seamlessly.** + +
+ +## Why CCS Instead of Manual Switching?
-| Tính năng | Lợi ích | -|-----------|---------| -| **Phân Cách Account** | Giữ công việc riêng với cá nhân | -| **Tối Ưu Chi Phí** | 2-3 account Pro vs Max 5x chi phí | -| **Chuyển Đổi Tức Thì** | Một lệnh, không sửa file | -| **Không Downtime** | Không gián đoạn workflow | -| **Quản Lý Rate Limit** | Chuyển account khi hết limit | -| **Đa Nền Tảng** | macOS, Linux, Windows | +| Feature | Benefit | +|:--------|:--------| +| **Account Isolation** | Keep work separate from personal | +| **Cost Optimization** | 2-3 Pro accounts vs Max at 5x cost | +| **Instant Switching** | One command, no file editing | +| **Zero Downtime** | Never interrupt workflow | +| **Rate Limit Management** | Switch accounts when limits hit | +| **Cross-Platform** | macOS, Linux, Windows |
-**Giải pháp**: -```bash -ccs cong-ty # Dùng account Claude công ty -ccs ca-nhan # Chuyển sang account Claude cá nhân -ccs glm # Chuyển sang GLM cho tác vụ tối ưu chi phí -ccs kimi # Chuyển sang Kimi cho lựa chọn thay thế -# Hết rate limit? Chuyển ngay: -ccs glm # Tiếp tục làm việc với GLM -# Cần account công ty khác? -ccs cong-ty-2 # Chuyển sang account công ty thứ hai -``` - ---- - -## 🏗️ Tổng Quan Kiến Trúc - -**v3.0 Mô hình Login-Per-Profile**: Mỗi profile là một Claude instance riêng biệt nơi người dùng đăng nhập trực tiếp. Không cần sao chép credentials hay vault encryption. - -```mermaid -flowchart TD - subgraph "Người Dùng Input" - USER["User chạy: ccs <profile> [args...]"] - end - - subgraph "Engine Phát Hiện Profile" - DETECT[ProfileDetector] - PROFILE_CHECK{Profile tồn tại?} - - subgraph "Loại Profile" - SETTINGS["Settings-based
glm, kimi, default"] - ACCOUNT["Account-based
work, personal, team"] - end - end - - subgraph "Xử Lý Core CCS" - CONFIG["Đọc config.json
và profiles.json"] - - subgraph "Profile Handlers" - SETTINGS_MGR["SettingsManager
→ --settings flag"] - INSTANCE_MGR["InstanceManager
→ CLAUDE_CONFIG_DIR"] - end - end - - subgraph "Thực Thi Claude CLI" - CLAUDE_DETECT["Claude CLI Detection
Hỗ trợ CCS_CLAUDE_PATH"] - - subgraph "Phương Thức Thực Thi" - SETTINGS_EXEC["claude --settings <path>"] - INSTANCE_EXEC["CLAUDE_CONFIG_DIR=<instance> claude"] - end - end - - subgraph "API Layer" - API["API Response
Claude Sonnet 4.5
GLM 4.6
Kimi K2 Thinking"] - end - - %% Flow connections - USER --> DETECT - DETECT --> PROFILE_CHECK - PROFILE_CHECK -->|Có| SETTINGS - PROFILE_CHECK -->|Có| ACCOUNT - - SETTINGS --> CONFIG - ACCOUNT --> CONFIG - - CONFIG --> SETTINGS_MGR - CONFIG --> INSTANCE_MGR - - SETTINGS_MGR --> SETTINGS_EXEC - INSTANCE_MGR --> INSTANCE_EXEC - - SETTINGS_EXEC --> CLAUDE_DETECT - INSTANCE_EXEC --> CLAUDE_DETECT - - CLAUDE_DETECT --> API -``` - ---- +
## Architecture @@ -247,9 +205,9 @@ flowchart TD ### Shared Data (v3.1) -Commands and skills symlinked from `~/.ccs/shared/` - no duplication across profiles. +Commands and skills symlinked from `~/.ccs/shared/` - **no duplication across profiles**. -``` +```plaintext ~/.ccs/ ├── shared/ # Shared across all profiles │ ├── agents/ @@ -261,85 +219,270 @@ Commands and skills symlinked from `~/.ccs/shared/` - no duplication across prof │ ├── commands@ → shared/commands/ │ ├── skills@ → shared/skills/ │ ├── settings.json # API keys, credentials -│ └── sessions/ # Conversation history +│ ├── sessions/ # Conversation history │ └── ... ``` -**Shared**: commands/, skills/, agents/ -**Profile-specific**: settings.json, sessions/, todolists/, logs/ +| Type | Files | +|:-----|:------| +| **Shared** | `commands/`, `skills/`, `agents/` | +| **Profile-specific** | `settings.json`, `sessions/`, `todolists/`, `logs/` | -**[i] Windows**: Copies dirs if symlinks unavailable (enable Developer Mode for true symlinks) +> [!NOTE] +> **Windows**: Copies directories if symlinks unavailable (enable Developer Mode for true symlinks) ---- +
+ +## Usage Examples + +### Basic Switching + +```bash +ccs # Claude subscription (default) +ccs glm # GLM (cost-optimized) +ccs kimi # Kimi (with thinking support) +``` + +### Multi-Account Setup + +```bash +# Create accounts +ccs auth create work +ccs auth create personal +``` + +**Run concurrently in separate terminals:** + +```bash +# Terminal 1 - Work +ccs work "implement feature" + +# Terminal 2 - Personal (concurrent) +ccs personal "review code" +``` + +### Help & Version + +```bash +ccs --version # Show version +ccs --help # Show all commands and options +``` + +
## GLM with Thinking (GLMT) -> **[!] CẢNH BÁO: CHƯA SẴN SÀNG SẢN XUẤT** +> [!CAUTION] +> ### NOT PRODUCTION READY - EXPERIMENTAL FEATURE > -> **GLMT là thử nghiệm và yêu cầu gỡ lỗi sâu rộng**: -> - Streaming và hỗ trợ công cụ vẫn đang phát triển -> - Có thể gặp lỗi, timeout, hoặc phản hồi không đầy đủ -> - Yêu cầu gỡ lỗi thường xuyên và can thiệp thủ công -> - **Không khuyến nghị cho quy trình quan trọng hoặc sử dụng sản xuất** +> **GLMT is experimental and requires extensive debugging**: +> - Streaming and tool support still under active development +> - May experience unexpected errors, timeouts, or incomplete responses +> - Requires frequent debugging and manual intervention +> - **Not recommended for critical workflows or production use** > -> **Phương án thay thế cho GLM Thinking**: Cân nhắc trải qua **CCR hustle** với **Transformer của Bedolla** (ZaiTransformer) để có triển khai ổn định hơn. +> **Alternative for GLM Thinking**: Consider going through the **CCR hustle** with the **Transformer of Bedolla** ([ZaiTransformer](https://github.com/Bedolla/ZaiTransformer/)) for a more stable implementation. + +> [!IMPORTANT] +> GLMT requires npm installation (`npm install -g @kaitranntt/ccs`). Not available in native shell versions (requires Node.js HTTP server). + +
+ +> [!NOTE] +> ### Acknowledgments: The Foundation That Made GLMT Possible > -> **[!] Quan trọng**: GLMT yêu cầu cài đặt npm (`npm install -g @kaitranntt/ccs`). Không có trong phiên bản shell gốc (yêu cầu Node.js HTTP server). +> **CCS's GLMT implementation owes its existence to the groundbreaking work of [@Bedolla](https://github.com/Bedolla)**, who created [ZaiTransformer](https://github.com/Bedolla/ZaiTransformer/) - the **first integration** to bridge [Claude Code Router (CCR)](https://github.com/musistudio/claude-code-router) with Z.AI's reasoning capabilities. +> +> Before ZaiTransformer, no one had successfully integrated Z.AI's thinking mode with Claude Code's workflow. Bedolla's work wasn't just helpful - it was **foundational**. His implementation of request/response transformation architecture, thinking mode control mechanisms, and embedded proxy design directly inspired and enabled GLMT's design. +> +> **Without ZaiTransformer's pioneering work, GLMT wouldn't exist in its current form.** If you benefit from GLMT's thinking capabilities, please consider starring [ZaiTransformer](https://github.com/Bedolla/ZaiTransformer/) to support pioneering work in the Claude Code ecosystem. -### GLM vs GLMT +
-| Tính năng | GLM (`ccs glm`) | GLMT (`ccs glmt`) | -|-----------|-----------------|-------------------| -| **Endpoint** | Tương thích Anthropic | Tương thích OpenAI | -| **Thinking** | Không | Thử nghiệm (reasoning_content) | -| **Tool Support** | Cơ bản | **Không ổn định (v3.5+)** | -| **MCP Tools** | Giới hạn | **Lỗi (v3.5+)** | -| **Streaming** | Ổn định | **Thử nghiệm (v3.4+)** | -| **TTFB** | <500ms | <500ms (đôi khi), 2-10s+ (thường xuyên) | -| **Use Case** | Công việc đáng tin cậy | **Chỉ thử nghiệm gỡ lỗi** | +
+

GLM vs GLMT Comparison

 ---- +
-## ⚡ Tính Năng +
-- **Chuyển Đổi Ngay Lập Tức** - `ccs glm` chuyển sang GLM, không cần sửa config -- **Phiên Đồng Thời** - Chạy nhiều profile cùng lúc ở các terminal khác nhau -- **Instance Riêng Biệt** - Mỗi profile có config riêng (`~/.ccs/instances//`) -- **Đa Nền Tảng** - macOS, Linux, Windows - hoạt động giống nhau -- **Không Downtime** - Chuyển đổi ngay lập tức, không gián đoạn workflow +| Feature | GLM (`ccs glm`) | GLMT (`ccs glmt`) | +|:--------|:----------------|:------------------| +| **Endpoint** | Anthropic-compatible | OpenAI-compatible | +| **Thinking** | No | Experimental (`reasoning_content`) | +| **Tool Support** | Basic | **Unstable (v3.5+)** | +| **MCP Tools** | Limited | **Buggy (v3.5+)** | +| **Streaming** | Stable | **Experimental (v3.4+)** | +| **TTFB** | <500ms | <500ms (sometimes), 2-10s+ (often) | +| **Use Case** | Reliable work | **Debugging experiments only** | +
---- +
-## 💻 Ví Dụ Sử Dụng +
+ +
+

Tool Support (v3.5) - EXPERIMENTAL

 + +
+ +**GLMT attempts MCP tools and function calling:** + +- **Bidirectional Transformation**: Anthropic tools ↔ OpenAI format (unstable) +- **MCP Integration**: MCP tools sometimes execute (often output XML garbage) +- **Streaming Tool Calls**: Real-time tool calls (when not crashing) +- **Backward Compatible**: May break existing thinking support +- **Configuration Required**: Frequent manual debugging needed + +
+ +
+

Streaming Support (v3.4) - OFTEN FAILS

 + +
+ +**GLMT attempts real-time streaming** with incremental reasoning content delivery: + +- **Default**: Streaming enabled (TTFB <500ms when it works) +- **Auto-fallback**: Frequently switches to buffered mode due to errors +- **Thinking parameter**: Claude CLI `thinking` parameter sometimes works + - May ignore `thinking.type` and `budget_tokens` + - Precedence: CLI parameter > message tags > default (when not broken) + +**Status**: Z.AI (tested, tool calls frequently break, requires constant debugging) + +
+ +
+

How It Works (When It Works)

 + +
+ +1. CCS spawns embedded HTTP proxy on localhost (if not crashing) +2. Proxy attempts to convert Anthropic format → OpenAI format (often fails) +3. Tries to transform Anthropic tools → OpenAI function calling format (buggy) +4. Forwards to Z.AI with reasoning parameters and tools (when not timing out) +5. Attempts to convert `reasoning_content` → thinking blocks (partial or broken) +6. Attempts to convert OpenAI `tool_calls` → Anthropic `tool_use` blocks (XML garbage common) +7. Thinking and tool calls sometimes appear in Claude Code UI (when not broken) + +
+ +
+

Control Tags & Keywords

 + +
+ +**Control Tags**: +- `` - Enable/disable reasoning blocks (default: On) +- `` - Control reasoning depth (deprecated - Z.AI only supports binary thinking) + +**Thinking Keywords** (inconsistent activation): +- `think` - Sometimes enables reasoning (low effort) +- `think hard` - Sometimes enables reasoning (medium effort) +- `think harder` - Sometimes enables reasoning (high effort) +- `ultrathink` - Attempts maximum reasoning depth (often breaks) + +
+ +
+

Environment Variables

 + +
+ +**GLMT features** (all experimental): +- Forced English output enforcement (sometimes works) +- Random thinking mode activation (unpredictable) +- Attempted streaming with frequent fallback to buffered mode + +**General**: +- `CCS_DEBUG_LOG=1` - Enable debug file logging +- `CCS_CLAUDE_PATH=/path/to/claude` - Custom Claude CLI path + +
+ +
+

API Key Setup

 + +
```bash -ccs # Claude subscription (mặc định) -ccs glm # GLM (không thinking) -ccs glmt # GLM với thinking -ccs kimi # Kimi cho Coding -ccs --version # Hiển thị phiên bản +# Edit GLMT settings +nano ~/.ccs/glmt.settings.json ``` -### Phiên Đồng Thời (Multi-Account) +Set Z.AI API key (requires coding plan): + +```json +{ + "env": { + "ANTHROPIC_AUTH_TOKEN": "your-z-ai-api-key" + } +} +``` + +
+ +
+

Security Limits (DoS Protection)

 + +
+ +**v3.4 Protection Limits**: + +| Limit | Value | Purpose | +|:------|:------|:--------| +| **SSE buffer** | 1MB max per event | Prevent buffer overflow | +| **Content buffer** | 10MB max per block | Limit thinking/text blocks | +| **Content blocks** | 100 max per message | Prevent DoS attacks | +| **Request timeout** | 120s | Both streaming and buffered | + +
+ +
+

Debugging

 + +
+ +**Enable verbose logging**: ```bash -# Tạo nhiều tài khoản Claude -ccs auth create cong-ty # Tài khoản công ty -ccs auth create ca-nhan # Tài khoản cá nhân -ccs auth create team # Tài khoản team - -# Terminal 1 - Tài khoản công ty -ccs cong-ty "implement feature" - -# Terminal 2 - Tài khoản cá nhân (chạy đồng thời) -ccs ca-nhan "review code" +ccs glmt --verbose "your prompt" ``` ---- +**Enable debug file logging**: +```bash +export CCS_DEBUG_LOG=1 +ccs glmt --verbose "your prompt" +# Logs: ~/.ccs/logs/ +``` -### 🗑️ Gỡ Cài Đặt +**GLMT debugging**: +```bash +# Verbose logging shows streaming status and reasoning details +ccs glmt --verbose "test" +``` + +**Check reasoning content**: +```bash +cat ~/.ccs/logs/*response-openai.json | jq '.choices[0].message.reasoning_content' +``` + +**Troubleshooting**: +- **If absent**: Z.AI API issue (verify key, account status) +- **If present**: Transformation issue (check `response-anthropic.json`) + +
+ +
+ +## Uninstall + +
+

Package Managers

 + +
-**Package Managers** ```bash # npm npm uninstall -g @kaitranntt/ccs @@ -354,57 +497,63 @@ pnpm remove -g @kaitranntt/ccs bun remove -g @kaitranntt/ccs ``` -**Uninstaller Chính Thức** +
+ +
+

Official Uninstaller

 + +
-**macOS / Linux** ```bash +# macOS / Linux curl -fsSL ccs.kaitran.ca/uninstall | bash -``` -**Windows PowerShell** -```powershell +# Windows PowerShell irm ccs.kaitran.ca/uninstall | iex ``` ---- +
-## 🎯 Triết Lý +
-- **YAGNI**: Không có tính năng "phòng hờ" -- **KISS**: Bash đơn giản, không phức tạp -- **DRY**: Một nguồn chân lý duy nhất (config) +## 🎯 Philosophy ---- +- **YAGNI**: No features "just in case" +- **KISS**: Simple bash, no complexity +- **DRY**: One source of truth (config) -## 📖 Tài Liệu +## 📖 Documentation -**Tài liệu đầy đủ trong [docs/](./docs/)**: -- [Hướng dẫn Cài đặt](./docs/en/installation.md) -- [Cấu hình](./docs/en/configuration.md) -- [Ví dụ Sử dụng](./docs/en/usage.md) +**Complete documentation in [docs/](./docs/)**: +- [Installation Guide](./docs/en/installation.md) +- [Configuration](./docs/en/configuration.md) +- [Usage Examples](./docs/en/usage.md) - [System Architecture](./docs/system-architecture.md) - [GLMT Control Mechanisms](./docs/glmt-controls.md) -- [Khắc phục Sự cố](./docs/en/troubleshooting.md) -- [Đóng góp](./CONTRIBUTING.md) +- [Troubleshooting](./docs/en/troubleshooting.md) +- [Contributing](./CONTRIBUTING.md) ---- +## 🤝 Contributing -## 🤝 Đóng Góp +We welcome contributions! Please see our [Contributing Guide](./CONTRIBUTING.md) for details. -Chúng tôi chào mừng đóng góp! Vui lòng xem [Hướng dẫn Đóng góp](./CONTRIBUTING.md) để biết chi tiết. - ---- - -## 📄 Giấy Phép - -CCS được cấp phép theo [Giấy phép MIT](LICENSE). - ---- +## Star History
-**Được tạo với ❤️ cho những lập trình viên hay hết rate limit** - -[⭐ Star repo này](https://github.com/kaitranntt/ccs) | [🐛 Báo cáo vấn đề](https://github.com/kaitranntt/ccs/issues) | [📖 Đọc tài liệu](./docs/en/) +Star History Chart
+ + +## License + +CCS is licensed under the [MIT License](LICENSE). + +
+ +**Made with ❤️ for developers who hit rate limits too often** + +[⭐ Star this repo](https://github.com/kaitranntt/ccs) | [🐛 Report issues](https://github.com/kaitranntt/ccs/issues) | [📖 Read docs](./docs/en/) + +
\ No newline at end of file