mirror of
https://github.com/tiennm99/ccs.git
synced 2026-07-16 06:16:37 +00:00
kaitranntt
071ec041ed
Implements CCS WebSearch Native Infrastructure (Phases 1-3): Phase 1 - Multi-tier MCP Fallback: - Add mcp-manager.ts with ensureMcpWebSearch() for auto-configuration - Support web-search-prime (primary), Brave Search, and Tavily MCPs - Case-insensitive detection of existing web search MCPs - Block-websearch hook for optional native WebSearch blocking Phase 2 - User Configuration: - Add WebSearchConfig interface to unified-config-types.ts - Add getWebSearchConfig() to unified-config-loader.ts - Support configurable webSearchPrimeUrl for security - Add GET/PUT /api/websearch endpoints in routes.ts - Add WebSearch settings UI in settings.tsx dashboard Phase 3 - Documentation & Testing: - Add WebSearch section to README.md - Create comprehensive docs/websearch.md guide - Add 23 unit tests for MCP manager logic Enables web search for gemini, codex, agy, qwen, glm, kimi profiles that cannot access Anthropic's native WebSearch API.
296 lines
7.6 KiB
Markdown
296 lines
7.6 KiB
Markdown
<div align="center">
|
|
|
|
# CCS - Claude Code Switch
|
|
|
|
|
|
|
|
### The universal AI profile manager for Claude Code.
|
|
Run Claude, Gemini, GLM, and any Anthropic-compatible API - concurrently, without conflicts.
|
|
|
|
[](LICENSE)
|
|
[](https://www.npmjs.com/package/@kaitranntt/ccs)
|
|
[](https://claudekit.cc?ref=HMNKXOHN)
|
|
|
|
**[Features & Pricing](https://ccs.kaitran.ca)** | **[Documentation](https://docs.ccs.kaitran.ca)**
|
|
|
|
</div>
|
|
|
|
<br>
|
|
|
|
## The Three Pillars
|
|
|
|
| Capability | What It Does | Manage Via |
|
|
|------------|--------------|------------|
|
|
| **Multiple Claude Accounts** | Run work + personal Claude subs simultaneously | Dashboard |
|
|
| **OAuth Providers** | Gemini, Codex, Antigravity - zero API keys needed | Dashboard |
|
|
| **API Profiles** | GLM, Kimi, or any Anthropic-compatible API | Dashboard |
|
|
|
|
<br>
|
|
|
|
## Quick Start
|
|
|
|
### 1. Install
|
|
|
|
```bash
|
|
npm install -g @kaitranntt/ccs
|
|
```
|
|
|
|
<details>
|
|
<summary>Alternative package managers</summary>
|
|
|
|
```bash
|
|
yarn global add @kaitranntt/ccs # yarn
|
|
pnpm add -g @kaitranntt/ccs # pnpm (70% less disk space)
|
|
bun add -g @kaitranntt/ccs # bun (30x faster)
|
|
```
|
|
|
|
</details>
|
|
|
|
### 2. Open Dashboard
|
|
|
|
```bash
|
|
ccs config
|
|
# Opens http://localhost:3000
|
|
```
|
|
|
|
### 3. Configure Your Accounts
|
|
|
|
The dashboard provides visual management for all account types:
|
|
|
|
- **Claude Accounts**: Create isolated instances (work, personal, client)
|
|
- **OAuth Providers**: One-click auth for Gemini, Codex, Antigravity
|
|
- **API Profiles**: Configure GLM, Kimi with your keys
|
|
- **Health Monitor**: Real-time status across all profiles
|
|
|
|
**Analytics (Light/Dark Theme)**
|
|
|
|
|
|
|
|
|
|
|
|
**API Profiles & OAuth Providers**
|
|
|
|
|
|
|
|
|
|
|
|
<br>
|
|
|
|
## Built-in Providers
|
|
|
|
| Provider | Auth Type | Command | Best For |
|
|
|----------|-----------|---------|----------|
|
|
| **Claude** | Subscription | `ccs` | Default, strategic planning |
|
|
| **Gemini** | OAuth | `ccs gemini` | Zero-config, fast iteration |
|
|
| **Codex** | OAuth | `ccs codex` | Code generation |
|
|
| **Antigravity** | OAuth | `ccs agy` | Alternative routing |
|
|
| **GLM** | API Key | `ccs glm` | Cost-optimized execution |
|
|
| **Kimi** | API Key | `ccs kimi` | Long-context, thinking mode |
|
|
|
|
> **OAuth providers** authenticate via browser on first run. Tokens are cached in `~/.ccs/cliproxy/auth/`.
|
|
|
|
> [!TIP]
|
|
> **Need more?** CCS supports **any Anthropic-compatible API**. Create custom profiles for self-hosted LLMs, enterprise gateways, or alternative providers. See [API Profiles documentation](https://docs.ccs.kaitran.ca/providers/api-profiles).
|
|
|
|
<br>
|
|
|
|
## Usage
|
|
|
|
### Basic Commands
|
|
|
|
```bash
|
|
ccs # Default Claude session
|
|
ccs agy # Antigravity (OAuth)
|
|
ccs gemini # Gemini (OAuth)
|
|
ccs glm # GLM (API key)
|
|
```
|
|
|
|
### Parallel Workflows
|
|
|
|
Run multiple terminals with different providers:
|
|
|
|
```bash
|
|
# Terminal 1: Planning (Claude Pro)
|
|
ccs work "design the authentication system"
|
|
|
|
# Terminal 2: Execution (GLM - cost optimized)
|
|
ccs glm "implement the user service from the plan"
|
|
|
|
# Terminal 3: Review (Gemini)
|
|
ccs gemini "review the implementation for security issues"
|
|
```
|
|
|
|
### Multi-Account Claude
|
|
|
|
Create isolated Claude instances for work/personal separation:
|
|
|
|
```bash
|
|
ccs auth create work
|
|
|
|
# Run concurrently in separate terminals
|
|
ccs work "implement feature" # Terminal 1
|
|
ccs "review code" # Terminal 2 (personal account)
|
|
```
|
|
|
|
<br>
|
|
|
|
## Maintenance
|
|
|
|
### Health Check
|
|
|
|
```bash
|
|
ccs doctor
|
|
```
|
|
|
|
Verifies: Claude CLI, config files, symlinks, permissions.
|
|
|
|
### Update
|
|
|
|
```bash
|
|
ccs update # Update to latest
|
|
ccs update --force # Force reinstall
|
|
ccs update --beta # Install dev channel
|
|
```
|
|
|
|
### Sync Shared Items
|
|
|
|
```bash
|
|
ccs sync
|
|
```
|
|
|
|
Re-creates symlinks for shared commands, skills, and settings.
|
|
|
|
<br>
|
|
|
|
## Configuration
|
|
|
|
CCS auto-creates config on install. Dashboard is the recommended way to manage settings.
|
|
|
|
**Config location**: `~/.ccs/config.yaml`
|
|
|
|
<details>
|
|
<summary>Custom Claude CLI path</summary>
|
|
|
|
If Claude CLI is installed in a non-standard location:
|
|
|
|
```bash
|
|
export CCS_CLAUDE_PATH="/path/to/claude" # Unix
|
|
$env:CCS_CLAUDE_PATH = "D:\Tools\Claude\claude.exe" # Windows
|
|
```
|
|
|
|
</details>
|
|
|
|
<details>
|
|
<summary>Windows symlink support</summary>
|
|
|
|
Enable Developer Mode for true symlinks:
|
|
|
|
1. **Settings** → **Privacy & Security** → **For developers**
|
|
2. Enable **Developer Mode**
|
|
3. Reinstall: `npm install -g @kaitranntt/ccs`
|
|
|
|
Without Developer Mode, CCS falls back to copying directories.
|
|
|
|
</details>
|
|
|
|
<br>
|
|
|
|
## WebSearch
|
|
|
|
Third-party profiles (Gemini, Codex, GLM, etc.) cannot use Anthropic's native WebSearch. CCS automatically configures MCP-based web search as a fallback.
|
|
|
|
### How It Works
|
|
|
|
| Profile Type | WebSearch Method |
|
|
|--------------|------------------|
|
|
| Claude (native) | Anthropic WebSearch API |
|
|
| OAuth providers | MCP web-search-prime (auto-configured) |
|
|
| API profiles | MCP web-search-prime (auto-configured) |
|
|
|
|
### Configuration
|
|
|
|
Configure via dashboard (**Settings** page) or `~/.ccs/config.yaml`:
|
|
|
|
```yaml
|
|
websearch:
|
|
enabled: true # Enable/disable auto-config
|
|
provider: auto # auto | web-search-prime | brave | tavily
|
|
fallback: true # Enable fallback chain
|
|
```
|
|
|
|
### Optional API Keys
|
|
|
|
For additional search providers, set environment variables:
|
|
|
|
```bash
|
|
export BRAVE_API_KEY="your-key" # Free tier: 15k queries/month
|
|
export TAVILY_API_KEY="your-key" # AI-optimized search (paid)
|
|
```
|
|
|
|
> [!NOTE]
|
|
> `web-search-prime` works without API keys. Brave/Tavily are optional fallbacks.
|
|
|
|
See [docs/websearch.md](./docs/websearch.md) for detailed configuration and troubleshooting.
|
|
|
|
<br>
|
|
|
|
## Documentation
|
|
|
|
| Topic | Link |
|
|
|-------|------|
|
|
| Installation | [docs.ccs.kaitran.ca/getting-started/installation](https://docs.ccs.kaitran.ca/getting-started/installation) |
|
|
| Configuration | [docs.ccs.kaitran.ca/getting-started/configuration](https://docs.ccs.kaitran.ca/getting-started/configuration) |
|
|
| OAuth Providers | [docs.ccs.kaitran.ca/providers/oauth-providers](https://docs.ccs.kaitran.ca/providers/oauth-providers) |
|
|
| Multi-Account Claude | [docs.ccs.kaitran.ca/providers/claude-accounts](https://docs.ccs.kaitran.ca/providers/claude-accounts) |
|
|
| API Profiles | [docs.ccs.kaitran.ca/providers/api-profiles](https://docs.ccs.kaitran.ca/providers/api-profiles) |
|
|
| CLI Reference | [docs.ccs.kaitran.ca/reference/cli-commands](https://docs.ccs.kaitran.ca/reference/cli-commands) |
|
|
| Architecture | [docs.ccs.kaitran.ca/reference/architecture](https://docs.ccs.kaitran.ca/reference/architecture) |
|
|
| Troubleshooting | [docs.ccs.kaitran.ca/reference/troubleshooting](https://docs.ccs.kaitran.ca/reference/troubleshooting) |
|
|
|
|
<br>
|
|
|
|
## Uninstall
|
|
|
|
```bash
|
|
npm uninstall -g @kaitranntt/ccs
|
|
```
|
|
|
|
<details>
|
|
<summary>Alternative package managers</summary>
|
|
|
|
```bash
|
|
yarn global remove @kaitranntt/ccs
|
|
pnpm remove -g @kaitranntt/ccs
|
|
bun remove -g @kaitranntt/ccs
|
|
```
|
|
|
|
</details>
|
|
|
|
<br>
|
|
|
|
## Philosophy
|
|
|
|
- **YAGNI**: No features "just in case"
|
|
- **KISS**: Simple, focused implementation
|
|
- **DRY**: One source of truth (config)
|
|
|
|
<br>
|
|
|
|
## Contributing
|
|
|
|
See [CONTRIBUTING.md](./CONTRIBUTING.md).
|
|
|
|
<br>
|
|
|
|
## License
|
|
|
|
MIT License - see [LICENSE](LICENSE).
|
|
|
|
<div align="center">
|
|
|
|
---
|
|
|
|
**[ccs.kaitran.ca](https://ccs.kaitran.ca)** | [Report Issues](https://github.com/kaitranntt/ccs/issues) | [Star on GitHub](https://github.com/kaitranntt/ccs)
|
|
|
|
</div>
|