npm package: @ledhcg/ccid
Description: Advanced CLI environment manager for isolating and seamlessly switching configurations in Anthropic's Claude Code.
Author: Dinh Cuong
Latest version: 1.1.36

# CCID (Claude Code ID)

[![npm version](https://img.shields.io/npm/v/@ledhcg/ccid?style=flat-square&color=cyan)](https://www.npmjs.com/package/@ledhcg/ccid)
![Node version](https://img.shields.io/node/v/@ledhcg/ccid?style=flat-square&color=green)
![License](https://img.shields.io/npm/l/@ledhcg/ccid?style=flat-square&color=yellow)

```text
 ░▒▓██████▓▒░ ░▒▓██████▓▒░░▒▓█▓▒░▒▓███████▓▒░  
░▒▓█▓▒░░▒▓█▓▒░▒▓█▓▒░░▒▓█▓▒░▒▓█▓▒░▒▓█▓▒░░▒▓█▓▒░ 
░▒▓█▓▒░      ░▒▓█▓▒░      ░▒▓█▓▒░▒▓█▓▒░░▒▓█▓▒░ 
░▒▓█▓▒░      ░▒▓█▓▒░      ░▒▓█▓▒░▒▓█▓▒░░▒▓█▓▒░ 
░▒▓█▓▒░      ░▒▓█▓▒░      ░▒▓█▓▒░▒▓█▓▒░░▒▓█▓▒░ 
░▒▓█▓▒░░▒▓█▓▒░▒▓█▓▒░░▒▓█▓▒░▒▓█▓▒░▒▓█▓▒░░▒▓█▓▒░ 
 ░▒▓██████▓▒░ ░▒▓██████▓▒░░▒▓█▓▒░▒▓███████▓▒░  
```

**CCID** is an environment and configuration manager dedicated to [Claude Code](https://docs.anthropic.com/en/docs/agents-and-tools/claude-code/overview).

By default, Claude Code binds global configuration parameters inside a single `~/.claude/settings.json` file. CCID bridges this gap by introducing **Profile Management**, allowing developers to seamlessly create, isolate, and switch between multiple Claude Code configurations depending on their workflow.

---

## Core Capabilities

- **Instant Configuration Swapping:** Rapidly swap the contents of your active `settings.json` without manually backing up or copying files.
- **Isolated Profile Storage:** Profiles are securely partitioned in dedicated namespaces. Each profile retains its own copy of standard configuration parameters alongside custom metadata.
- **Multi-Provider Support:** Create profiles configured for Anthropic official, CLI Proxy API, MiniMax, or Z AI (ZhipuAI) providers with guided model selection.
- **Direct Claude Launch:** Launch Claude Code directly from CCID, including Yolo mode (`--dangerously-skip-permissions`) and arbitrary argument forwarding.
- **CLI Profile Switching:** Switch profiles non-interactively from the command line with `-p` flag and immediately launch Claude Code.
- **Strict Data Validation:** Profile names strictly adhere to system-safe characters (`a-z`, `0-9`, `_`, `-`) to prevent directory parsing errors.
- **Default Safeguard:** The foundational `default` profile is locked in a Read-Only state. Destructive actions (edit/delete) are internally disabled.
- **Workspace Override Detection:** Proactively detects local `.claude/settings.json` directories and warns if your global profile swap might be superseded by a local runtime override.

---

## Installation

### Install script (recommended)

Downloads a pre-built binary — **no Node.js required**.

**macOS / Linux / WSL:**
```bash
curl -fsSL https://raw.githubusercontent.com/ledhcg/ccid/main/scripts/install.sh | bash
```

**Windows (PowerShell):**
```powershell
irm https://raw.githubusercontent.com/ledhcg/ccid/main/scripts/install.ps1 | iex
```

**Windows (CMD):**
```cmd
curl -fsSL https://raw.githubusercontent.com/ledhcg/ccid/main/scripts/install.cmd -o install.cmd && install.cmd && del install.cmd
```

Pin a specific version by passing it as an argument:
```bash
curl -fsSL https://raw.githubusercontent.com/ledhcg/ccid/main/scripts/install.sh | bash -s 1.1.36
```

---

### Homebrew (macOS / Linux)

```bash
brew tap ledhcg/ccid
brew install ccid
```

Upgrade:
```bash
brew upgrade ccid
```

---

### npm / yarn

```bash
npm install -g @ledhcg/ccid
# or
yarn global add @ledhcg/ccid
```

---

## Usage

### Interactive Mode

Launch the full interactive TUI:

```bash
ccid
```

### CLI Shortcuts

```bash
ccid .                    # Launch Claude Code directly (no profile switch)
ccid yolo                 # Launch Claude Code in Yolo mode (skip permissions)
ccid -p <profile>         # Switch to a profile and launch Claude Code
ccid -p <profile> yolo    # Switch to a profile and launch in Yolo mode
ccid "Hello world"        # Forward arguments directly to Claude CLI
ccid -h                   # Show help
```

### Navigation (Interactive Mode)

| Key | Action |
|-----|--------|
| Up/Down | Navigate menus |
| Enter | Select / Submit |
| Space | Open profile context menu |
| Esc / q | Back / Exit |
| Ctrl+C | Quit |

---

## AI Provider Support

CCID supports multiple AI providers through its profile creation wizard:

### Anthropic Official
Uses the default Anthropic API. After profile creation, run `claude login` to authenticate.

### CLI Proxy API
Connect to any Claude-compatible proxy endpoint. CCID auto-fetches available models from the proxy's `/v1/models` endpoint.

### MiniMax
Pre-configured with `https://api.minimax.io/anthropic`. Includes preset models:
- MiniMax-M2.7 / M2.7-highspeed
- MiniMax-M2.5 / M2.5-highspeed
- MiniMax-M2.1 / M2.1-highspeed
- MiniMax-M2

All models support 204,800-token context windows.

### Z AI (ZhipuAI)
Pre-configured with `https://api.z.ai/api/anthropic`. Includes preset models:
- GLM-5, GLM-5-Turbo
- GLM-4.7, GLM-4.7-FlashX, GLM-4.7-Flash
- GLM-4.6, GLM-4.5, GLM-4.5-X, GLM-4.5-Air, GLM-4.5-AirX, GLM-4.5-Flash
- GLM-4-32B-0414-128K

Context windows range from 128K to 200K tokens.

For all 3rd-party providers, the wizard guides you through selecting models for each tier (Haiku, Sonnet, Opus) with detailed model information panels.

---

## Profile Creation Wizard

The interactive wizard walks through an 11-step process:

1. **Profile Name** — Validated naming (`a-z`, `0-9`, `_`, `-`)
2. **Description** — Optional profile description
3. **Method** — Anthropic official or 3rd-party provider
4. **Provider** — CLI Proxy API, MiniMax, or Z AI
5. **Base URL** — Custom endpoint (proxy only)
6. **Auth Token** — API authentication token
7. **Load Models** — Auto-fetch or load preset model lists
8. **Haiku Model** — Select model for Haiku tier
9. **Opus Model** — Select model for Opus tier
10. **Sonnet Model** — Select model for Sonnet tier
11. **Confirm** — Review all selections and create

Completed steps are displayed as a persistent summary above the current step. Auth tokens are masked for security.

---

## Internal Architecture

```text
~/.claude/
├── settings.json                   <-- The LIVE configuration file parsed by Claude Code
├── profiles/
│   ├── active.txt                  <-- Internal tracker storing the current active profile name
│   ├── default/                    <-- System default profile (Read-only)
│   │   ├── settings.json           <-- Config replica for default state
│   │   └── meta.json               <-- Stores JSON metadata (description)
│   └── <custom_profile>/           <-- Custom isolated profile
│       ├── settings.json
│       └── meta.json
```

When a profile is invoked, CCID physically copies `profiles/<target>/settings.json` into `~/.claude/settings.json` and updates `active.txt`.

---

## Prerequisites

- Anthropic's **Claude Code** installed
- **Node.js `v18+`** — only required when installing via `npm install -g` (not needed for binary install)

---

## Contributing

1. Fork the repository
2. Create your Feature Branch (`git checkout -b feature/NewCapability`)
3. Commit your Changes (`git commit -m 'Added NewCapability'`)
4. Push to the Branch (`git push origin feature/NewCapability`)
5. Open a Pull Request

---

## License

This software is released under the **MIT License**. See the `LICENSE` file for more details.