npm - claude-cac - Versions diffs - 1.0.0 → 1.1.0 - Mend

claude-cac 1.0.0 → 1.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (8) hide show

package/README.md CHANGED Viewed

@@ -1,14 +1,19 @@
 <div align="center">
-# cac — Claude Code Cloak
+# :umbrella: cac
-**Privacy Cloak + CLI Proxy for Claude Code**
+**Claude Code 小雨伞** — Isolate, protect, and manage your Claude Code.
-**[中文](#中文) | [English](#english)**
+*Run Claude Code your way — isolated, protected, managed.*
+**[中文](#中文) | [English](#english) | [:book: Docs](https://cac.nextmind.space/docs)**
+[![GitHub stars](https://img.shields.io/github/stars/nmhjklnm/cac?style=social)](https://github.com/nmhjklnm/cac)
+[![Docs](https://img.shields.io/badge/Docs-cac.nextmind.space-D97706.svg)](https://cac.nextmind.space/docs)
 [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
-[![Platform](https://img.shields.io/badge/Platform-macOS%20%7C%20Linux-lightgrey.svg)]()
-[![Shell](https://img.shields.io/badge/Shell-Bash-green.svg)]()
+[![Platform](https://img.shields.io/badge/Platform-macOS%20%7C%20Linux%20%7C%20Windows-lightgrey.svg)]()
+:star: Star this repo if it helps — it helps others find it too.
 </div>
@@ -20,127 +25,173 @@
 > **[Switch to English](#english)**
-### 为什么需要 cac
+### 简介
-Claude Code 在运行过程中会读取并上报设备标识符（硬件 UUID、安装 ID、网络出口 IP 等）。cac 通过 wrapper 机制拦截所有 `claude` 调用，在进程层面同时解决两个问题：
+**cac** 是 Claude Code 的环境管理器，类似 uv 之于 Python：
-**A. 隐私隔离** — 每个配置对外呈现独立的设备身份，彻底隔离真实设备指纹。
+- **版本管理** — 安装、切换、回滚 Claude Code 版本
+- **环境隔离** — 每个环境独立的 `.claude` 配置 + 身份 + 代理
+- **隐私保护** — 设备指纹伪装 + 遥测阻断 + mTLS
+- **零配置** — 无需 setup，首次使用自动初始化
-**B. CLI 专属代理** — 进程级注入代理，`claude` 流量直连远端代理服务器。无需 Clash / Shadowrocket 等本地代理工具，无需中转，无需起本地服务端。配合静态住宅 IP，获得固定、干净的出口身份。
+### 安装
-### 特性一览
+```bash
+# npm（推荐）
+npm install -g claude-cac
-| | 特性 | 说明 |
-|:---|:---|:---|
-| **A** | 硬件 UUID 隔离 | macOS: 拦截 `ioreg` / Linux: 拦截 `machine-id` |
-| **A** | hostname / MAC 隔离 | 拦截 `hostname` 和 `ifconfig` 命令 |
-| **A** | stable_id / userID 隔离 | 切换配置时自动写入独立标识 |
-| **A** | 时区 / 语言伪装 | 根据代理出口地区自动匹配 |
-| **A** | NS 层级遥测拦截 | DNS guard 拦截 `statsig.anthropic.com` 等遥测域名 |
-| **A** | 12 层环境变量保护 | 全面禁用遥测、错误上报、非必要流量 |
-| **A** | fetch 遥测拦截 | 替换原生 fetch，防止绕过 DNS 拦截 |
-| **A** | mTLS 客户端证书 | 自签 CA + 每环境独立客户端证书 |
-| **B** | 进程级代理 | 支持 HTTP/HTTPS/SOCKS5 代理 |
-| **B** | 免本地服务端 | 无需 Clash / Shadowrocket / TUN，CLI 直连 |
-| **B** | 静态住宅 IP 支持 | 配置固定代理 → 固定出口 IP |
-| **B** | 启动前连通检测 | 代理不可达时拒绝启动，真实 IP 零泄漏 |
-| **B** | 本地代理冲突检测 | `cac check` 自动检测 Clash/TUN 冲突 |
+# 或手动安装
+curl -fsSL https://raw.githubusercontent.com/nmhjklnm/cac/master/install.sh | bash
+```
-所有 `claude` 调用（含 Agent 子进程）均通过 wrapper 拦截。零入侵 Claude Code 源代码。
+### 快速上手
-### 安装
+```bash
+# 安装 Claude Code
+cac claude install latest
-**一键安装（推荐）：**
+# 创建环境
+cac env create work -p 1.2.3.4:1080:u:p -c latest
-```bash
-curl -fsSL https://raw.githubusercontent.com/nmhjklnm/cac/master/install.sh | bash
+# 激活
+cac work
+# 启动 Claude Code（首次需 /login）
+claude
 ```
-**手动安装：**
+代理可选 — 不需要代理也能用：
 ```bash
-git clone https://github.com/nmhjklnm/cac.git
-cd cac
-bash install.sh
+cac env create personal                  # 只要身份隔离
+cac env create work -c 2.1.81           # 指定版本，无代理
 ```
-安装完成后重开终端，或执行 `source ~/.zshrc`。
-### 使用
+### 版本管理
 ```bash
-# 添加配置
-cac add us1 1.2.3.4:1080:username:password
-cac add us2 "socks5://username:password@1.2.3.4:1080"
-# 切换配置
-cac us1
+cac claude install latest               # 安装最新版
+cac claude install 2.1.81               # 安装指定版本
+cac claude ls                           # 列出已安装版本
+cac claude pin 2.1.81                   # 当前环境切换版本
+cac claude uninstall 2.1.81             # 卸载
+```
-# 检查状态（含代理冲突检测）
-cac check
+### 环境管理
-# 启动 Claude Code
-claude
+```bash
+cac env create <name> [-p <proxy>] [-c <version>] [--type local|container]
+cac env ls                              # 列出所有环境
+cac env rm <name>                       # 删除环境
+cac <name>                              # 激活环境（快捷方式）
+cac ls                                  # = cac env ls
 ```
-首次使用需在 Claude Code 内执行 `/login` 完成账号登录。
+每个环境完全隔离：
+- **Claude Code 版本** — 不同环境可以用不同版本
+- **`.claude` 配置** — sessions、settings、memory 各自独立
+- **身份信息** — UUID、hostname、MAC 等完全不同
+- **代理出口** — 每个环境走不同代理（或不走代理）
-### 命令
+### 全部命令
 | 命令 | 说明 |
 |:---|:---|
-| `cac add <名字> <host:port:u:p>` | 添加配置 |
-| `cac <名字>` | 切换配置，刷新所有隐私参数 |
-| `cac ls` | 列出所有配置 |
-| `cac check` | 检查代理 + 安全防护 + 冲突检测 |
-| `cac stop` | 临时停用保护 |
-| `cac -c` | 恢复保护 |
+| **版本管理** | |
+| `cac claude install [latest\|<ver>]` | 安装 Claude Code |
+| `cac claude uninstall <ver>` | 卸载版本 |
+| `cac claude ls` | 列出已安装版本 |
+| `cac claude pin <ver>` | 当前环境绑定版本 |
+| **环境管理** | |
+| `cac env create <name> [-p proxy] [-c ver]` | 创建环境 |
+| `cac env ls` | 列出环境 |
+| `cac env rm <name>` | 删除环境 |
+| `cac <name>` | 激活环境 |
+| **自管理** | |
+| `cac self update` | 更新 cac 自身 |
+| **其他** | |
+| `cac ls` | 列出环境（= `cac env ls`） |
+| `cac check` | 检查当前环境 |
+| `cac relay on\|off\|status` | 本地中转（绕过 TUN） |
+| `cac stop` / `cac resume` | 暂停 / 恢复保护 |
+| `cac delete` | 卸载 cac |
+| `cac -v` | 版本号 |
+### 代理格式
+```
+host:port:user:pass       带认证（自动检测协议）
+host:port                 无认证
+socks5://u:p@host:port    指定协议
+```
+### 隐私保护
+| 特性 | 实现方式 |
+|:---|:---|
+| 硬件 UUID 隔离 | macOS `ioreg` / Linux `machine-id` / Windows `wmic`+`reg` shim |
+| 主机名 / MAC 隔离 | Shell shim + Node.js `os.hostname()` / `os.networkInterfaces()` hook |
+| Node.js 指纹钩子 | `fingerprint-hook.js` 通过 `NODE_OPTIONS --require` 注入 |
+| 遥测阻断 | DNS guard + 12 层环境变量 + fetch 拦截 + HOSTALIASES |
+| 健康检查 bypass | 本地 HTTPS server + `/etc/hosts` + `NO_PROXY` |
+| mTLS 客户端证书 | 自签 CA + 每环境独立客户端证书 |
+| `.claude` 配置隔离 | 每个环境独立的 `CLAUDE_CONFIG_DIR` |
 ### 工作原理
 ```
-                cac wrapper (进程级，零入侵源代码)
-                ┌──────────────────────────────────────┐
-  claude ──────►│ 12 层环境变量遥测保护                  │──── 直连远端代理 ────► Anthropic API
-                │ NODE_OPTIONS --require DNS guard     │     (静态住宅 IP)
-                │ PATH 前置 shim（设备指纹隔离）         │
-                │ mTLS 客户端证书注入                    │
-                │ 启动前代理连通性检测                    │
-                └──────────────────────────────────────┘
-                    ↑ dns.lookup / net.connect / fetch 遥测拦截
-                    ↑ macOS: ioreg/hostname/ifconfig shim
-                    ↑ Linux: cat/hostname/ifconfig shim
+              cac wrapper（进程级，零侵入源代码）
+              ┌──────────────────────────────────────────┐
+  claude ────►│  CLAUDE_CONFIG_DIR → 隔离配置目录          │
+              │  版本解析 → ~/.cac/versions/<ver>/claude   │
+              │  健康检查 bypass（本地 HTTPS server）       │
+              │  12 层遥测环境变量保护                      │──► 代理 ──► Anthropic API
+              │  NODE_OPTIONS: DNS guard + 指纹钩子        │
+              │  PATH: 设备指纹 shim                       │
+              │  mTLS: 客户端证书注入                       │
+              └──────────────────────────────────────────┘
 ```
 ### 文件结构
 ```
 ~/.cac/
-├── bin/claude            # wrapper（拦截所有 claude 调用）
-├── shim-bin/             # ioreg / hostname / ifconfig / cat shim
-├── cac-dns-guard.js      # NS 层级 DNS 拦截 + mTLS 注入 + fetch 补丁
-├── blocked_hosts         # HOSTALIASES 遥测域名拦截（备用层）
-├── ca/                   # mTLS 自签 CA 证书
-├── real_claude           # 真实 claude 二进制路径
-├── current               # 当前激活的配置名
+├── versions/<ver>/claude     # Claude Code 二进制文件
+├── bin/claude                # wrapper
+├── shim-bin/                 # ioreg / hostname / ifconfig / cat shim
+├── fingerprint-hook.js       # Node.js 指纹拦截
+├── cac-dns-guard.js          # DNS + fetch 遥测拦截
+├── ca/                       # 自签 CA + 健康检查 bypass 证书
+├── current                   # 当前激活的环境名
 └── envs/<name>/
-    ├── proxy             # 代理地址
-    ├── uuid / stable_id / user_id  # 独立身份标识
-    ├── machine_id / hostname / mac_address  # 独立设备指纹
-    ├── client_cert.pem / client_key.pem     # mTLS 客户端证书
-    └── tz / lang         # 时区 / 语言
+    ├── .claude/              # 隔离的 .claude 配置目录
+    ├── proxy                 # 代理地址（可选）
+    ├── version               # 绑定的 Claude Code 版本
+    ├── type                  # local / container
+    ├── uuid / stable_id      # 隔离身份
+    ├── hostname / mac_address / machine_id
+    └── client_cert.pem       # mTLS 证书
 ```
-### 注意事项
+### Docker 容器模式
+完全隔离的运行环境：sing-box TUN 网络隔离 + cac 身份伪装，预装 Claude Code。
+```bash
+cac docker setup     # 粘贴代理地址，网络自动检测
+cac docker start     # 启动容器
+cac docker enter     # 进入容器，claude + cac 直接可用
+cac docker check     # 网络 + 身份一键诊断
+cac docker port 6287 # 端口转发
+```
-> **本地代理工具共存**
-> 若同时使用 Clash / Shadowrocket 等 TUN 模式，需为代理服务器 IP 添加 DIRECT 规则。`cac check` 会自动检测冲突并给出修复建议。
+代理格式：`ip:port:user:pass`（SOCKS5）、`ss://...`、`vmess://...`、`vless://...`、`trojan://...`
-> **第三方 API 配置**
-> wrapper 启动时自动清除 `ANTHROPIC_BASE_URL` / `ANTHROPIC_AUTH_TOKEN` / `ANTHROPIC_API_KEY`。
+### 注意事项
-> **IPv6**
-> 建议在系统层关闭 IPv6，防止真实出口 IPv6 地址被暴露。
+- **首次登录**：启动 `claude` 后，输入 `/login` 完成 OAuth 授权
+- **TUN 冲突**：使用 `cac relay on` 或在 TUN 软件中为代理 IP 添加 DIRECT 规则
+- **IPv6**：建议系统级关闭，防止真实地址泄露
 ---
@@ -150,100 +201,165 @@ claude
 > **[切换到中文](#中文)**
-### Why cac
+### Overview
-Claude Code reads and reports device identifiers at runtime (hardware UUID, installation ID, network egress IP, etc.). cac intercepts all `claude` invocations via a wrapper, solving two problems at the process level — without modifying any Claude Code source code:
+**cac** — Isolate, protect, and manage your Claude Code:
-**A. Privacy Cloak** — Each profile presents an independent device identity, fully isolating your real device fingerprint.
+- **Version management** — install, switch, rollback Claude Code versions
+- **Environment isolation** — independent `.claude` config + identity + proxy per environment
+- **Privacy protection** — device fingerprint spoofing + telemetry blocking + mTLS
+- **Zero config** — no setup needed, auto-initializes on first use
-**B. CLI Proxy** — Process-level proxy injection; `claude` traffic connects directly to the remote proxy server. No Clash / Shadowrocket or any local proxy tools needed.
+### Install
-### Features
+```bash
+# npm (recommended)
+npm install -g claude-cac
-| | Feature | Description |
-|:---|:---|:---|
-| **A** | Hardware UUID isolation | macOS: intercepts `ioreg` / Linux: intercepts `machine-id` |
-| **A** | hostname / MAC isolation | Intercepts `hostname` and `ifconfig` commands |
-| **A** | stable_id / userID isolation | Writes independent identifiers on profile switch |
-| **A** | Timezone / locale spoofing | Auto-detected from proxy exit region |
-| **A** | NS-level telemetry blocking | DNS guard blocks `statsig.anthropic.com` and other telemetry domains |
-| **A** | 12-layer env var protection | Disables telemetry, error reporting, non-essential traffic |
-| **A** | fetch telemetry interception | Replaces native fetch to prevent DNS interception bypass |
-| **A** | mTLS client certificates | Self-signed CA + per-profile client certificates |
-| **B** | Process-level proxy | Supports HTTP/HTTPS/SOCKS5 proxies |
-| **B** | No local server needed | No Clash / Shadowrocket / TUN — direct CLI connection |
-| **B** | Static residential IP support | Fixed proxy config = fixed egress IP |
-| **B** | Pre-launch connectivity check | Blocks startup if proxy unreachable — zero real IP leakage |
-| **B** | Local proxy conflict detection | `cac check` detects Clash/TUN conflicts automatically |
+# or manual
+curl -fsSL https://raw.githubusercontent.com/nmhjklnm/cac/master/install.sh | bash
+```
-All `claude` invocations (including Agent subprocesses) are intercepted. Zero invasion of Claude Code source code.
+### Quick start
-### Installation
+```bash
+# Install Claude Code
+cac claude install latest
-**One-line install (recommended):**
+# Create environment
+cac env create work -p 1.2.3.4:1080:u:p -c latest
-```bash
-curl -fsSL https://raw.githubusercontent.com/nmhjklnm/cac/master/install.sh | bash
+# Activate
+cac work
+# Run Claude Code (first time: /login)
+claude
 ```
-**Manual install:**
+Proxy is optional:
 ```bash
-git clone https://github.com/nmhjklnm/cac.git
-cd cac
-bash install.sh
+cac env create personal                  # identity isolation only
+cac env create work -c 2.1.81           # pinned version, no proxy
 ```
-After installation, restart your terminal or run `source ~/.zshrc`.
+### Version management
-### Usage
+```bash
+cac claude install latest               # install latest
+cac claude install 2.1.81               # install specific version
+cac claude ls                           # list installed versions
+cac claude pin 2.1.81                   # pin current env to version
+cac claude uninstall 2.1.81             # remove
+```
+### Environment management
 ```bash
-cac add us1 1.2.3.4:1080:username:password
-cac us1
-cac check    # includes proxy conflict detection
-claude
+cac env create <name> [-p <proxy>] [-c <version>] [--type local|container]
+cac env ls                              # list all environments
+cac env rm <name>                       # remove environment
+cac <name>                              # activate (shortcut)
+cac ls                                  # = cac env ls
 ```
-On first use, run `/login` inside Claude Code to authenticate.
+Each environment is fully isolated:
+- **Claude Code version** — different envs can use different versions
+- **`.claude` config** — sessions, settings, memory are independent
+- **Identity** — UUID, hostname, MAC are all different
+- **Proxy** — each env routes through a different proxy (or none)
-### Commands
+### All commands
 | Command | Description |
 |:---|:---|
-| `cac add <name> <host:port:u:p>` | Add profile |
-| `cac <name>` | Switch profile, refresh all privacy parameters |
-| `cac ls` | List all profiles |
-| `cac check` | Check proxy + security + conflict detection |
-| `cac stop` | Temporarily disable protection |
-| `cac -c` | Re-enable protection |
+| **Version management** | |
+| `cac claude install [latest\|<ver>]` | Install Claude Code |
+| `cac claude uninstall <ver>` | Remove version |
+| `cac claude ls` | List installed versions |
+| `cac claude pin <ver>` | Pin current env to version |
+| **Environment management** | |
+| `cac env create <name> [-p proxy] [-c ver]` | Create environment |
+| `cac env ls` | List environments |
+| `cac env rm <name>` | Remove environment |
+| `cac <name>` | Activate environment |
+| **Self-management** | |
+| `cac self update` | Update cac itself |
+| **Other** | |
+| `cac ls` | List environments (= `cac env ls`) |
+| `cac check` | Verify current environment |
+| `cac relay on\|off\|status` | Local relay (bypass TUN) |
+| `cac stop` / `cac resume` | Pause / resume protection |
+| `cac delete` | Uninstall cac |
+| `cac -v` | Show version |
+### Privacy protection
+| Feature | How |
+|:---|:---|
+| Hardware UUID isolation | macOS `ioreg` / Linux `machine-id` / Windows `wmic`+`reg` shim |
+| Hostname / MAC isolation | Shell shim + Node.js `os.hostname()` / `os.networkInterfaces()` hook |
+| Node.js fingerprint hook | `fingerprint-hook.js` via `NODE_OPTIONS --require` |
+| Telemetry blocking | DNS guard + 12 env vars + fetch interception + HOSTALIASES |
+| Health check bypass | Local HTTPS server + `/etc/hosts` + `NO_PROXY` |
+| mTLS client certificates | Self-signed CA + per-profile client certs |
+| `.claude` config isolation | Per-environment `CLAUDE_CONFIG_DIR` |
-### How It Works
+### How it works
 ```
-                cac wrapper (process-level, zero source invasion)
-                ┌──────────────────────────────────────┐
-  claude ──────►│ 12-layer env var telemetry protection │──── Direct to remote ────► Anthropic API
-                │ NODE_OPTIONS --require DNS guard      │     (static residential)
-                │ PATH-prepended shims (fingerprint)    │
-                │ mTLS client cert injection            │
-                │ Pre-flight proxy check                │
-                └──────────────────────────────────────┘
-                    ↑ dns.lookup / net.connect / fetch telemetry interception
-                    ↑ macOS: ioreg/hostname/ifconfig shim
-                    ↑ Linux: cat/hostname/ifconfig shim
+              cac wrapper (process-level, zero source invasion)
+              ┌──────────────────────────────────────────┐
+  claude ────►│  CLAUDE_CONFIG_DIR → isolated config dir   │
+              │  Version resolve → ~/.cac/versions/<ver>   │
+              │  Health check bypass (local HTTPS server)  │
+              │  Env vars: 12-layer telemetry kill         │──► Proxy ──► Anthropic API
+              │  NODE_OPTIONS: DNS guard + fingerprint     │
+              │  PATH: device fingerprint shims            │
+              │  mTLS: client cert injection               │
+              └──────────────────────────────────────────┘
 ```
-### Notes
+### File layout
+```
+~/.cac/
+├── versions/<ver>/claude     # Claude Code binaries
+├── bin/claude                # wrapper
+├── shim-bin/                 # ioreg / hostname / ifconfig / cat shims
+├── fingerprint-hook.js       # Node.js fingerprint interception
+├── cac-dns-guard.js          # DNS + fetch telemetry interception
+├── ca/                       # self-signed CA + health bypass cert
+├── current                   # active environment name
+└── envs/<name>/
+    ├── .claude/              # isolated .claude config directory
+    ├── proxy                 # proxy URL (optional)
+    ├── version               # pinned Claude Code version
+    ├── type                  # local / container
+    ├── uuid / stable_id      # isolated identity
+    ├── hostname / mac_address / machine_id
+    └── client_cert.pem       # mTLS cert
+```
-> **Coexisting with local proxy tools**
-> If you also use Clash / Shadowrocket in TUN mode, add a DIRECT rule for the proxy server IP. `cac check` will detect conflicts and provide fix suggestions.
+### Docker mode
-> **Third-party API configuration**
-> The wrapper automatically clears `ANTHROPIC_BASE_URL` / `ANTHROPIC_AUTH_TOKEN` / `ANTHROPIC_API_KEY` on startup.
+Fully isolated environment: sing-box TUN network isolation + cac identity protection, with Claude Code pre-installed.
+```bash
+cac docker setup     # paste proxy, network auto-detected
+cac docker start     # start container
+cac docker enter     # shell with claude + cac ready
+cac docker check     # network + identity diagnostics
+cac docker port 6287 # port forwarding
+```
+Proxy formats: `ip:port:user:pass` (SOCKS5), `ss://...`, `vmess://...`, `vless://...`, `trojan://...`
+### Notes
-> **IPv6**
-> It is recommended to disable IPv6 at the system level to prevent your real IPv6 egress address from being exposed.
+- **First login**: Run `claude`, then type `/login`. Health check is automatically bypassed.
+- **TUN conflicts**: Use `cac relay on` or add DIRECT rule in your TUN software.
+- **IPv6**: Recommend disabling system-wide to prevent real address exposure.
 ---