ccs/docs/vi/README.md

CCS - Claude Code Switch

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. Ngừng hitting rate limits. Làm việc liên tục.

Languages: English · Tiếng Việt · 日本語

Bắt Đầu Nhanh

Cài Đặt

npm Package (Được khuyến nghị)

macOS / Linux / Windows

npm install -g @kaitranntt/ccs

Tất cả các trình quản lý package chính đều được hỗ trợ:

# yarn
yarn global add @kaitranntt/ccs

# pnpm (ít hơn 70% dung lượng đĩa)
pnpm add -g @kaitranntt/ccs

# bun (nhanh hơn 30x)
bun add -g @kaitranntt/ccs

[!] LỖI THỜI: Trình cài đặt shell gốc (Cũ)

Warning

Các trình cài đặt này đã lỗi thời và sẽ bị xóa trong phiên bản tương lai. Hiện tại chúng tự động chuyển hướng đến cài đặt npm. Vui lòng sử dụng npm trực tiếp.

macOS / Linux

curl -fsSL ccs.kaitran.ca/install | bash

Windows PowerShell

irm ccs.kaitran.ca/install | iex

Lưu ý: Script hiển thị cảnh báo lỗi thời và tự động chạy cài đặt npm nếu Node.js khả dụng.

Cấu Hình (Tự Tạo)

CCS tự động tạo cấu hình trong quá trình cài đặt (thông qua script postinstall của npm).

~/.ccs/config.json:

{
  "profiles": {
    "glm": "~/.ccs/glm.settings.json",
    "glmt": "~/.ccs/glmt.settings.json",
    "kimi": "~/.ccs/kimi.settings.json",
    "default": "~/.claude/settings.json"
  }
}

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:

# Unix/Linux/macOS
export CCS_CLAUDE_PATH="/path/to/claude"

# Windows PowerShell
$env:CCS_CLAUDE_PATH = "D:\Tools\Claude\claude.exe"

Xem thêm: Hướng dẫn Khắc phục Sự cố để biết chi tiết cài đặt.

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ì):

1. Mở Settings → Privacy & Security → For developers
2. Bật Developer Mode
3. Cài đặt lại CCS: npm install -g @kaitranntt/ccs

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

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

# Terminal 1 - Planning (Claude Sonnet)
ccs "Plan a REST API with authentication and rate limiting"

# Terminal 2 - Execution (GLM, cost-optimized)
ccs glm "Implement the user authentication endpoints from the plan"

Thinking Models (Kimi & GLMT)

# 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"

Lưu ý: GLMT là thử nghiệm và không ổn định. Xem phần GLM with Thinking (GLMT) dưới đây để biết chi tiết.

The Daily Developer Pain Point

DỪNG việc chuyển đổi. BẮT ĐẦU điều phối.

Giới hạn phiên không nên phá hỏng trạng thái dòng chảy của bạn.

Bạn đang sâu trong triển khai. Ngữ cảnh đã tải. Giải pháp đang kết tinh.
Sau đó: 🔴 "Bạn đã đạt đến giới hạn sử dụng."

Động lực mất đi. Ngữ cảnh mất. Năng suất sụp đổ.

Giải pháp: Quy trình công việc song song

❌ CÁCH CŨ: Chuyển đổi khi bạn đạt đến giới hạn (Phản ứng)

Quy trình làm việc hiện tại của bạn:

• 2pm: Xây dựng tính năng, trong vùng

• 3pm: 🔴 Đạt giới hạn sử dụng

• 3:05pm: Dừng công việc, chỉnh sửa ~/.claude/settings.json

• 3:15pm: Chuyển tài khoản, mất ngữ cảnh

• 3:30pm: Cố gắng quay lại trạng thái dòng chảy

• 4pm: Cuối cùng cũng năng suất trở lại

• Kết quả: Mất 1 giờ, động lực bị phá hủy, sự thất vọng tăng lên

✨ CÁCH MỚI: Chạy song song ngay từ đầu (Chủ động) - ĐƯỢC KHUYÊN NGHỊ

Quy trình làm việc mới của bạn:

• 2pm: Terminal 1: ccs "Lập kế hoạch kiến trúc API" → Tư duy chiến lược (Claude Pro)

• 2pm: Terminal 2: ccs glm "Triển khai các điểm cuối API" → Thực thi mã (GLM)

• 3pm: Vẫn đang giao hàng, không có gián đoạn

• 4pm: Đạt trạng thái dòng chảy, năng suất tăng vọt

• 5pm: Tính năng đã giao hàng, ngữ cảnh được duy trì

• Kết quả: Không có thời gian chết, năng suất liên tục, ít thất vọng hơn

💰 Giá trị đề xuất:

• Thiết lập: Claude Pro hiện tại của bạn + GLM Lite (add-on hiệu quả về chi phí)
• Giá trị: Tiết kiệm 1 giờ/ngày × 20 ngày làm việc = 20 giờ/tháng được phục hồi
• ROI: Thời gian phát triển của bạn có giá trị hơn chi phí thiết lập
• Thực tế: Giao hàng nhanh hơn chi phí vận hành

Chọn con đường của bạn

Tập trung vào ngân sách: Chỉ GLM

• Tốt nhất cho: Phát triển tiết kiệm chi phí, tạo mã cơ bản
• Sử dụng: Chỉ sử dụng ccs glm trực tiếp để được trợ giúp AI hiệu quả về chi phí
• Thực tế: Không có quyền truy cập Claude, nhưng có khả năng cho nhiều nhiệm vụ mã hóa
• Thiết lập: Chỉ cần API key GLM, rất phải chăng

✨ Được khuyên nghị cho phát triển hàng ngày: 1 Claude Pro + 1 GLM Lite

• Tốt nhất cho: Giao hàng mã hàng ngày, công việc phát triển nghiêm túc
• Sử dụng: ccs để lập kế hoạch + ccs glm để thực thi (quy trình công việc song song)
• Thực tế: Cân bằng hoàn hảo giữa khả năng và chi phí cho hầu hết các nhà phát triển
• Giá trị: Không bao giờ đạt đến giới hạn phiên, năng suất liên tục

Power User: Nhiều Claude Pro + GLM Pro

• Tốt nhất cho: Nhiều công việc, dự án đồng thời, solo dev
• Mở khóa: Không bao giờ cạn kiệt giới hạn phiên hoặc hàng tuần
• Quy trình làm việc: 3+ terminal chạy các nhiệm vụ chuyên biệt đồng thời

Tập trung vào quyền riêng tư: Cách ly Công việc/Cá nhân

• Khi cần: Cách ly nghiêm ngặt ngữ cảnh AI công việc và cá nhân
• Thiết lập: ccs auth create work + ccs auth create personal
• Lưu ý: Tính năng nâng cao - hầu hết người dùng không cần điều này

---

Why CCS Instead of Manual Switching?

CCS không phải về "chuyển đổi khi bạn đạt đến giới hạn lúc 3pm."

Nó về việc chạy song song ngay từ đầu.

Sự khác biệt cốt lõi

Chuyển đổi thủ công	Điều phối CCS
🔴 Đạt giới hạn → Dừng công việc → Chỉnh sửa tệp cấu hình → Khởi động lại	✅ Nhiều terminal chạy các mô hình khác nhau ngay từ đầu
😰 Mất ngữ cảnh và gián đoạn trạng thái dòng chảy	😌 Năng suất liên tục với ngữ cảnh được bảo toàn
📝 Xử lý nhiệm vụ tuần tự	⚡ Quy trình công việc song song (lập kế hoạch + thực thi đồng thời)
🛠️ Giải quyết vấn đề phản ứng khi bị chặn	🎯 Thiết kế quy trình công việc chủ động ngăn chặn chặn

CCS mang lại cho bạn

• Không chuyển đổi ngữ cảnh: Duy trì trạng thái dòng chảy của bạn mà không bị gián đoạn
• Năng suất song song: Lập kế hoạch chiến lược trong một terminal, thực thi mã trong terminal khác
• Quản lý tài khoản tức thì: Một lệnh chuyển đổi, không cần chỉnh sửa tệp cấu hình
• Cách ly công việc-cuộc sống: Cách ly ngữ cảnh mà không cần đăng xuất
• Tính nhất quán đa nền tảng: Trải nghiệm mượt mà tương tự trên macOS, Linux, Windows

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 <profile>

Shared Data (v3.1)

Commands and skills symlinked from ~/.ccs/shared/ - no duplication across profiles.

~/.ccs/
├── shared/                  # Shared across all profiles
│   ├── agents/
│   ├── commands/
│   └── skills/
├── instances/               # Profile-specific data
│   └── work/
│       ├── agents@ → shared/agents/
│       ├── commands@ → shared/commands/
│       ├── skills@ → shared/skills/
│       ├── settings.json    # API keys, credentials
│       ├── sessions/        # Conversation history
│       └── ...

Type	Files
Shared	commands/, skills/, agents/
Profile-specific	settings.json, sessions/, todolists/, logs/

Note

Windows: Copies directories if symlinks unavailable (enable Developer Mode for true symlinks)

Usage Examples

Basic Switching

ccs              # Claude subscription (default)
ccs glm          # GLM (cost-optimized)
ccs kimi         # Kimi (with thinking support)

Multi-Account Setup

# Create accounts
ccs auth create work
ccs auth create personal

Run concurrently in separate terminals:

# Terminal 1 - Work
ccs work "implement feature"

# Terminal 2 - Personal (concurrent)
ccs personal "review code"

Help & Version

ccs --version    # Show version
ccs --help       # Show all commands and options

GLM with Thinking (GLMT)

Caution

NOT PRODUCTION READY - EXPERIMENTAL FEATURE

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

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).

Note

Acknowledgments: The Foundation That Made GLMT Possible

CCS's GLMT implementation owes its existence to the groundbreaking work of @Bedolla, who created ZaiTransformer - the first integration to bridge Claude Code Router (CCR) 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 to support pioneering work in the Claude Code ecosystem.

GLM vs GLMT Comparison

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

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:

• <Thinking:On|Off> - Enable/disable reasoning blocks (default: On)
• <Effort:Low|Medium|High> - 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

# Edit GLMT settings
nano ~/.ccs/glmt.settings.json

Set Z.AI API key (requires coding plan):

{
  "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:

ccs glmt --verbose "your prompt"

Enable debug file logging:

export CCS_DEBUG_LOG=1
ccs glmt --verbose "your prompt"
# Logs: ~/.ccs/logs/

GLMT debugging:

# Verbose logging shows streaming status and reasoning details
ccs glmt --verbose "test"

Check reasoning content:

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

# 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

# macOS / Linux
curl -fsSL ccs.kaitran.ca/uninstall | bash

# Windows PowerShell
irm ccs.kaitran.ca/uninstall | iex

🎯 Philosophy

• YAGNI: No features "just in case"
• KISS: Simple bash, no complexity
• DRY: One source of truth (config)

📖 Documentation

Complete documentation in docs/:

• Installation Guide
• Configuration
• Usage Examples
• System Architecture
• GLMT Control Mechanisms
• Troubleshooting
• Contributing

🤝 Contributing

We welcome contributions! Please see our Contributing Guide for details.

Star History

License

CCS is licensed under the MIT License.

Made with ❤️ for developers who hit rate limits too often

⭐ Star this repo | 🐛 Report issues | 📖 Read docs