@cc-x/cc-x 0.4.3 → 0.4.4

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
  1. package/README.en.md +230 -264
  2. package/README.md +182 -245
  3. package/dist/config/store.js +3 -1
  4. package/dist/i18n/messages.js +4 -0
  5. package/dist/ui/menus.js +25 -2
  6. package/dist/ui/select.js +3 -0
  7. package/dist/update/update.js +112 -0
  8. package/package.json +1 -1
package/README.en.md CHANGED
@@ -2,36 +2,43 @@
2
2
 
3
3
  > [简体中文](README.md) | English
4
4
 
5
- **A Claude Code API switcher** (terminal command: `xx`). Quickly switch Claude Code
6
- between the official account and third-party Anthropic-compatible APIs (DeepSeek,
7
- Zhipu GLM, Xiaomi MiMo, etc.).
5
+ **A Claude Code API switcher** (terminal command `xx`). One command to switch Claude Code
6
+ between the official account and third-party Anthropic-compatible APIs (DeepSeek, Zhipu GLM,
7
+ Xiaomi MiMo…).
8
8
 
9
- What makes it different: **it never writes any Claude Code config file**. API switching works
10
- purely through environment variables, so it is **physically incapable of clobbering your MCP servers,
11
- plugins, or hooks** — and it lets **multiple terminals each run a different API at the
12
- same time, without interfering with one another**.
9
+ What sets it apart from other switchers — **it never writes any Claude Code config file**;
10
+ switching works purely through environment variables. So:
13
11
 
14
- > **Native Go build:** GitHub Releases provide a lightweight `xx` / `xx.exe` with no
15
- > Node.js requirement for Windows x64, macOS Intel / Apple Silicon, and Linux x64 / arm64.
16
- > If you prefer npm, `npm install -g @cc-x/cc-x` is still available (the terminal command
17
- > is still `xx`).
12
+ - 🛡️ **Zero config risk**: it never touches `~/.claude/settings.json`, never opens
13
+ `~/.claude.json` (where MCP lives) — **physically incapable** of losing your MCP / plugins / hooks.
14
+ - 🔀 **Parallel terminals**: each terminal can run a different API without interference (process-level isolation).
15
+ - ⚡ **One command**: pick in `xx`, then use it for this terminal only or set it as the future default.
18
16
 
19
- ---
17
+ ```text
18
+ cc-x v0.4.4 · Claude Code API switcher (default = used by bare `claude` in new terminals)
19
+
20
+ ▶ Official (default)[Logged in]
21
+ DeepSeek [Key set] — work
22
+ 智谱GLM [No key]
23
+ 小米MiMo [No key]
24
+
25
+ New profile
26
+ 切换到中文
27
+ Update check: off
28
+ Exit
20
29
 
21
- ## Why it exists
30
+ ↑↓ move · Enter open · Shift+↑↓ (or PgUp/PgDn) reorder · q quit
31
+ ```
32
+
33
+ > **Two builds**: the **native Go build** is recommended — GitHub Releases provide a lightweight
34
+ > `xx` / `xx.exe` with no Node.js, for Windows x64, macOS Intel / Apple Silicon, Linux x64 / arm64.
35
+ > If you prefer npm, install `@cc-x/cc-x` (command is still `xx`). Both builds are feature-equal.
22
36
 
23
- Claude Code can talk to different API backends via environment variables, but switching
24
- by hand is tedious: editing `settings.json` or typing long `export`s, plus third-party
25
- APIs need **model mappings** (they only know their own model names), and there's no neat
26
- way to give each of several parallel terminals a different API. ccx folds all of that
27
- into one command, `xx`: pick a provider, then either **use it for this terminal only** or
28
- **set it as the default** for future terminals.
37
+ ---
29
38
 
30
39
  ## ccx vs cc-switch
31
40
 
32
- cc-switch is an excellent all-in-one **GUI** — if you want a graphical app, want to manage
33
- MCP centrally, and also switch Codex / Gemini and other CLIs, it fits better. ccx takes the
34
- opposite, **minimal** approach:
41
+ cc-switch is an excellent all-in-one **GUI**; ccx takes the opposite, **minimal** approach:
35
42
 
36
43
  | | ccx (command `xx`) | cc-switch |
37
44
  |---|---|---|
@@ -41,230 +48,186 @@ opposite, **minimal** approach:
41
48
  | Can lose MCP / plugins? | **Impossible by design** | Users have reported it overwriting them |
42
49
  | Different API per terminal | **Native** (process-level isolation) | Global switch; sessions can interfere |
43
50
 
44
- **ccx fits you if you** live in the terminal, often run **several terminals with different
45
- APIs in parallel**, have been burned by a switcher corrupting your config/MCP, or simply
46
- want the one job done with zero extra features.
47
-
48
- **cc-switch fits you if you** want a GUI, need to manage MCP and several AI CLIs in one
49
- place, or prefer an all-in-one tool.
50
-
51
- ## Safety
52
-
53
- - **Writes no Claude Code config files.** It never touches `~/.claude/settings.json`, and never opens
54
- `~/.claude.json` (where your MCP config lives). MCP / plugins / hooks / permissions
55
- cannot be affected.
56
- - It only ever sets/clears these 7 "managed" variables, nothing else:
57
- `ANTHROPIC_BASE_URL`, `ANTHROPIC_AUTH_TOKEN`, `ANTHROPIC_API_KEY`,
58
- `ANTHROPIC_DEFAULT_OPUS_MODEL`, `ANTHROPIC_DEFAULT_SONNET_MODEL`,
59
- `ANTHROPIC_DEFAULT_HAIKU_MODEL`, `CLAUDE_CODE_EFFORT_LEVEL`.
60
- - On switch it clears the managed variables the target profile doesn't use (the two auth
61
- fields are mutually exclusive), so nothing leaks from the previous provider.
62
-
63
- > 💡 **About `settings.json` and other Claude Code config files:** don't manage them with
64
- > third-party tools (ccx deliberately doesn't either). To change them, use Claude Code's own
65
- > `/update-config` and just describe what you want in natural language (e.g. "allow npm
66
- > commands", "switch to dark theme") — Claude Code maintains the file itself, which is safer
67
- > than letting an external tool rewrite it.
68
-
69
- ## Requirements
70
-
71
- - **Native Go build:** Windows 10/11 x64, macOS Intel / Apple Silicon, Linux x64 / arm64;
72
- no Node.js required.
73
- - **Cross-platform npm build:** Node.js ≥ 18 (package `@cc-x/cc-x`).
74
- - **Claude Code installed (`claude` on PATH)** — "Use this session" launches `claude`.
51
+ - **ccx fits you if you** live in the terminal, often run several terminals with different APIs
52
+ in parallel, have been burned by a switcher corrupting your config/MCP, or just want that one job done.
53
+ - **cc-switch fits you if you** want a GUI, need to manage MCP and several AI CLIs in one place,
54
+ or prefer an all-in-one tool.
75
55
 
76
56
  ## Install
77
57
 
78
- **Native Windows build (recommended)**
58
+ > Install **Claude Code** first (`claude` on PATH) — "Use this session" launches it. **Open a new terminal** after installing.
59
+
60
+ **Windows native (recommended)**
79
61
 
80
62
  ```powershell
81
63
  irm https://github.com/becomeless/cc-x/releases/latest/download/install.ps1 | iex
82
64
  ```
83
65
 
84
- The installer downloads the latest GitHub Release asset named `ccx_*_windows_amd64.zip`,
85
- installs it to `%LOCALAPPDATA%\Programs\ccx`, and adds that directory to the user PATH.
86
- Open a new terminal afterwards and run:
87
-
88
- ```powershell
89
- xx --version
90
- ```
66
+ Installs to `%LOCALAPPDATA%\Programs\ccx` and adds it to your user PATH.
91
67
 
92
- **Native macOS / Linux build (recommended)**
68
+ **macOS / Linux native (recommended)**
93
69
 
94
70
  ```bash
95
71
  curl -fsSL https://github.com/becomeless/cc-x/releases/latest/download/install.sh | sh
96
72
  ```
97
73
 
98
- The installer downloads the matching `ccx_*_darwin_*.tar.gz` or `ccx_*_linux_*.tar.gz`
99
- asset, installs `xx` to `~/.local/bin` (override with `CCX_INSTALL_DIR` or
100
- `--install-dir`), and verifies `checksums.txt` when available. If that directory is not
101
- on PATH, add it as prompted, open a new terminal, and run:
102
-
103
- ```bash
104
- xx --version
105
- ```
74
+ Installs to `~/.local/bin` (override with `CCX_INSTALL_DIR`) and verifies `checksums.txt`. If that dir
75
+ isn't on PATH, follow the printed hint.
106
76
 
107
- **Cross-platform npm build**
77
+ **npm, any platform** (needs Node.js ≥ 18)
108
78
 
109
79
  ```bash
110
80
  npm install -g @cc-x/cc-x
111
81
  ```
112
82
 
113
- Then type `xx` in any terminal. Update with `npm update -g @cc-x/cc-x`; remove with
114
- `npm uninstall -g @cc-x/cc-x`. (The npm package is `@cc-x/cc-x`; the terminal command is `xx`.)
83
+ Open a new terminal and run `xx --version` to verify.
115
84
 
116
- **From source (dev / custom)**
85
+ ## Quick start (60 seconds)
117
86
 
118
- ```bash
119
- git clone https://github.com/becomeless/cc-x
120
- cd cc-x
121
- ```
87
+ 1. Open a new terminal and run `xx`. The first run creates 4 default profiles in
88
+ `~/.cc-mini/providers.json` (Official + DeepSeek + Zhipu GLM + Xiaomi MiMo), **with empty keys**.
89
+ 2. ↑↓ to the one you want → Enter → **Edit** → pick **API key** and paste your key (done locally).
90
+ 3. Then either:
91
+ - **Set default**: future **new** terminals running bare `claude` use it.
92
+ - **Use this session**: launch Claude right now in this terminal (temporary, parallel-friendly).
122
93
 
123
- Native Go release build with version injection and multi-platform assets:
94
+ ## Two activation modes (core concept)
124
95
 
125
- ```powershell
126
- .\scripts\build-release.ps1 -Version 0.4.2
127
- .\dist\release\ccx_0.4.2_windows_amd64\xx.exe --version
128
- ```
96
+ This is the key to ccx. Which API Claude uses is decided by **environment variables**; ccx offers two scopes:
97
+
98
+ | | Use this session | Set default |
99
+ |---|---|---|
100
+ | Mechanism | Sets env vars for **this one process** and launches `claude` | Writes the API as **user environment variables** |
101
+ | Scope | This terminal only, **ephemeral** (gone when you close it) | **New** terminals running bare `claude` use it |
102
+ | Effect on running sessions | **None** | **None** (env vars freeze at process start) |
103
+ | Typical use | Several terminals in parallel, each on its own API | Set your everyday "main API" |
104
+
105
+ **Parallel example**: open 4 terminals and run `xx Official -s`, `xx DeepSeek -s`, `xx 智谱GLM -s`,
106
+ `xx 小米MiMo -s` — four Claudes running at once, each on its own API, never interfering.
107
+
108
+ **Why not switch via a global config file?** Because `settings.json` is shared globally; editing it hits
109
+ **running** sessions (a classic symptom: another terminal suddenly reports `... cannot be parsed as a URL`).
110
+ Environment variables are process-isolated, sidestepping that trap.
129
111
 
130
- npm build:
112
+ ## Command-line usage
131
113
 
132
114
  ```bash
133
- npm install
134
- npm run build
135
- npm link # then `xx` is available
115
+ xx # open the interactive menu
116
+ xx DeepSeek # "Set default" to the profile named DeepSeek
117
+ xx DeepSeek -s # "Use this session" for DeepSeek and launch Claude (--session)
118
+ xx -l # list all profiles and their state (--list)
119
+ xx --lang en # UI language for this run (zh / en)
120
+ xx --help # all options
136
121
  ```
137
122
 
138
- **Open a new terminal afterwards.**
123
+ `xx <name>` defaults to "Set default"; add `-s` / `--session` for "Use this session".
139
124
 
140
- ## Quick start
125
+ ## Menus & editing
141
126
 
142
- 1. Open a new terminal and run `xx`. On first run it creates 4 default profiles in
143
- `~/.cc-mini/providers.json` (official + DeepSeek + Zhipu GLM + Xiaomi MiMo) with
144
- **empty keys**.
145
- 2. Use ↑↓ to pick a profile → Enter → "Edit" → enter your **API key** (done locally).
146
- 3. Then either choose **Set as default** (open a new terminal, bare `claude` uses it) or
147
- **Use this session** (launches Claude in the current terminal immediately).
127
+ Run `xx` for the main menu: `↑↓` move, `Enter` select, `q` / `Esc` quit. With a profile selected,
128
+ **`Shift+↑↓` (or `PgUp`/`PgDn`) reorders** it, saved instantly.
148
129
 
149
- ## The two activation modes (core concept)
130
+ - **Select a profile → Enter** for the action menu: **Use this session** / **Set default** / **Edit** /
131
+ **Delete** (with confirm; keep "Official") / **Back**.
132
+ - **New profile** — create an empty profile and open the edit form.
133
+ - **Switch to 中文 / English** — instant language toggle, remembered in `lang` in `~/.cc-mini/providers.json`.
134
+ - **Update check: off / notify** — see [Checking for updates](#checking-for-updates).
135
+ - **Exit**.
150
136
 
151
- Which API Claude uses is ultimately decided by **environment variables**. ccx offers two
152
- scopes:
137
+ ```text
138
+ Profile: DeepSeek — work [Key set]
153
139
 
154
- | | Use this session | Set as default |
155
- |---|---|---|
156
- | Mechanism | Sets env vars in **the current process only**, then launches `claude` | Writes **user environment variables** |
157
- | Scope | This terminal only, **gone when it closes** | Future **newly opened** terminals' bare `claude` |
158
- | Effect on other / running sessions | **None** | **None** (env is fixed at process start) |
159
- | Typical use | Parallel terminals, each on a different API | Your usual "main" API |
160
-
161
- **Parallel example:** open 4 terminals and run `xx 官方 -s`, `xx DeepSeek -s`,
162
- `xx 智谱GLM -s`, `xx 小米MiMo -s` — four Claude sessions running at once, each
163
- on its own API, independent.
164
-
165
- **Why not switch via a global config file?** Because `settings.json` is global and editing
166
- it can disturb **running** sessions (e.g. another terminal suddenly erroring with
167
- `... cannot be parsed as a URL`). ccx avoids this with env vars: per-process isolation plus
168
- a user-level default.
169
-
170
- ## Menu
171
-
172
- Run `xx` for the interactive menu (`↑↓` move, `Enter` select, `q`/`Esc` quit; number keys
173
- also work). With a profile highlighted, press **`Shift+↑↓` (or `PgUp`/`PgDn`) to move it
174
- up/down and reorder** — saved instantly:
175
-
176
- - **Select a profile → Enter** opens the action menu:
177
- - **Use this session** — sets env for this terminal and launches Claude now.
178
- - **Set as default** — writes user env vars; **open a new terminal** for bare `claude` to
179
- pick it up; running sessions unaffected.
180
- - **Edit** — opens the form (below).
181
- - **Delete** — removes the profile (with confirmation; keep "官方").
182
- - **Back**.
183
- - **+ New profile**.
184
- - **语言 / Language** — toggle the UI between English and Chinese instantly (remembered;
185
- written back to `lang` in `~/.cc-mini/providers.json`).
186
- - **Quit**.
187
-
188
- **Edit form:** `↑↓` to pick a field, `Enter` to edit it; scroll past the fields to choose
189
- "Save & return" / "Discard". Inside a field, **Enter = keep unchanged**, `-` = clear,
190
- `Esc` = cancel that field. The first field is **"Provider"**: pick a provider (from the
191
- catalog) and it **auto-fills** the API URL, the three model mappings, and the auth field
192
- (if the provider has multiple API URLs — e.g. Xiaomi MiMo's pay-as-you-go API vs TokenPlan —
193
- you choose one). "Note" is free text. "API URL" can also be opened on its own to override
194
- (catalog + already-used URLs + manual entry).
195
-
196
- > "Provider" is a picker — press `Esc` to cancel in one key. "Note" uses plain input
197
- > (Enter = keep, `-` = clear; CJK input-method friendly).
198
-
199
- ## CLI usage
140
+ ▶ Session — this terminal only, launches Claude now (great for parallel terminals)
141
+ Set default — used by bare claude in new terminals (running sessions unaffected)
142
+ Edit
143
+ Delete
144
+ Back
200
145
 
201
- ```bash
202
- xx # interactive menu
203
- xx DeepSeek # "Set as default" to the profile named DeepSeek
204
- xx DeepSeek -s # "Use this session" and launch Claude (--session)
205
- xx -l # list all profiles and their status (--list)
206
- xx --lang en # UI in English for this run (zh / en)
207
- xx --help # show all options
146
+ ↑↓ move · Enter select · q back
147
+ ```
148
+
149
+ **Edit form**: `↑↓` pick a field, `Enter` to change; "Save & back" / "Discard" at the bottom. Inside a
150
+ field, **Enter = keep**, `-` = clear, `Esc` = cancel that field. The first field, **Provider**, is the key
151
+ one: picking a provider (from the preset catalog) **auto-fills** the API URL, the three model mappings, and
152
+ the auth field (providers with multiple URLs let you choose one first); "Note" is free text.
153
+
154
+ ```text
155
+ Edit profile (↑↓ pick a field, Enter to edit; save/discard at bottom)
156
+
157
+ ▶ Provider : DeepSeek
158
+ Note : work
159
+ API URL : https://api.deepseek.com/anthropic
160
+ Auth field : AUTH_TOKEN
161
+ API key : ********
162
+ opus → model : deepseek-v4-pro
163
+ sonnet→ model : deepseek-v4-pro
164
+ haiku → model : deepseek-v4-flash
165
+ effort level : max
166
+
167
+ Show key in plaintext (now hidden)
168
+
169
+ Save & back
170
+ Discard
208
171
  ```
209
172
 
210
- ## Profile fields
173
+ ## Configuration reference
174
+
175
+ ### Fields
211
176
 
212
- | Field | Env var | Notes |
177
+ | Field | Environment variable | Notes |
213
178
  |---|---|---|
214
- | Provider | — | Picked from the catalog; auto-fills API URL / models / auth field. Also the profile's unique id — collisions get a ` 2`/` 3`… suffix (see "Multiple accounts") |
215
- | Note | — | Free text; tells apart multiple profiles of the same provider |
216
- | API URL | `ANTHROPIC_BASE_URL` | Third-party endpoint; empty = official login |
217
- | Auth field | — | Whether the key goes into `AUTH_TOKEN` or `API_KEY` |
218
- | API key | `ANTHROPIC_AUTH_TOKEN` / `ANTHROPIC_API_KEY` | Value for the chosen auth field |
219
- | opus → model | `ANTHROPIC_DEFAULT_OPUS_MODEL` | model the `opus` tier maps to |
220
- | sonnet → model | `ANTHROPIC_DEFAULT_SONNET_MODEL` | model the `sonnet` tier maps to |
221
- | haiku → model | `ANTHROPIC_DEFAULT_HAIKU_MODEL` | model for `haiku`; **also used by background tasks** |
222
- | effort | `CLAUDE_CODE_EFFORT_LEVEL` | thinking depth (see below) |
223
-
224
- > ccx deliberately does **not** set `ANTHROPIC_MODEL` nor touch the `model` field in
225
- > `settings.json`. Pick a tier live with `/model opus|sonnet|haiku`; the mapping translates
226
- > it to the provider's model.
227
-
228
- ## Model mapping & effort
229
-
230
- Third-party APIs **must** have model mappings, because they only accept their own model
231
- names while Claude Code defaults to `claude-*`. Background tasks use the `haiku` tier, so
232
- **`haiku → model` must be set too** (otherwise background calls fail).
233
-
234
- **effort:** `low < medium < high < xhigh < max`; higher = smarter but slower / more tokens;
235
- `auto` = the model's default; empty = unset. effort is a Claude-model feature — whether a
236
- third party honors it depends on its implementation.
237
-
238
- | Profile | BASE_URL | OPUS / SONNET | HAIKU | effort |
179
+ | Provider | — | Picked from the preset catalog; auto-fills URL/models/auth. Also the unique key; duplicates get " 2/3…" |
180
+ | Note | — | Free text to tell apart multiple profiles of the same provider |
181
+ | API URL | `ANTHROPIC_BASE_URL` | Third-party endpoint; empty for Official = use the logged-in session |
182
+ | Auth field | — | Put the key in `AUTH_TOKEN` or `API_KEY` (see below) |
183
+ | API key | `ANTHROPIC_AUTH_TOKEN` or `ANTHROPIC_API_KEY` | Value for the chosen auth field |
184
+ | opus → model | `ANTHROPIC_DEFAULT_OPUS_MODEL` | Model the `opus` tier maps to |
185
+ | sonnet → model | `ANTHROPIC_DEFAULT_SONNET_MODEL` | Model the `sonnet` tier maps to |
186
+ | haiku → model | `ANTHROPIC_DEFAULT_HAIKU_MODEL` | Model the `haiku` tier maps to; **background tasks use it too** |
187
+ | effort level | `CLAUDE_CODE_EFFORT_LEVEL` | Thinking depth, see below |
188
+
189
+ > ccx **deliberately does not set** `ANTHROPIC_MODEL` or touch `model` in `settings.json`. You pick the tier
190
+ > live with `/model opus\|sonnet\|haiku`, and the mapping translates it to the provider's real model.
191
+
192
+ ### Model mapping & effort
193
+
194
+ **Why third parties need model mapping:** their endpoints only know their own model names (e.g.
195
+ `deepseek-v4-pro`), while Claude Code calls `claude-*` by default — without mapping it errors out. Background
196
+ tasks use the `haiku` tier, so `haiku → model` **must be set too** (otherwise: "main chat works but errors
197
+ now and then").
198
+
199
+ **effort (thinking depth):** `low < medium < high < xhigh < max` — higher is smarter but slower and burns
200
+ more tokens; `auto` = model default; empty = unset. Note **effort is a Claude-model feature; whether a third
201
+ party honors it depends on their implementation**.
202
+
203
+ Reference config per provider (defaults are pre-seeded):
204
+
205
+ | Profile | BASE_URL | OPUS / SONNET | HAIKU (incl. background) | effort |
239
206
  |---|---|---|---|---|
240
- | 官方 (official) | (empty = login) | — | — | empty / `auto` |
241
- | DeepSeek | `https://api.deepseek.com/anthropic` | `deepseek-v4-pro` | `deepseek-v4-flash` | `max` (per their docs) |
207
+ | Official | (empty = logged-in) | — | — | empty / `auto` |
208
+ | DeepSeek | `https://api.deepseek.com/anthropic` | `deepseek-v4-pro` | `deepseek-v4-flash` | `max` (recommended) |
242
209
  | Zhipu GLM | `https://open.bigmodel.cn/api/anthropic` | `GLM-4.7` | `glm-4.5-air` | empty |
243
210
  | Xiaomi MiMo | `https://api.xiaomimimo.com/anthropic` (pay-as-you-go)<br>`https://token-plan-cn.xiaomimimo.com/anthropic` (TokenPlan) | `mimo-v2.5-pro` | `mimo-v2.5-pro` | empty |
244
211
 
245
212
  > Model names change as providers update; follow each provider's official docs.
246
213
 
247
- ## Auth field: AUTH_TOKEN vs API_KEY
214
+ ### Auth field: AUTH_TOKEN vs API_KEY
248
215
 
249
- | Option | Actual header | Used by |
216
+ | Option | Request header | Used by |
250
217
  |---|---|---|
251
- | `ANTHROPIC_AUTH_TOKEN` (default) | `Authorization: Bearer <key>` | most third-party relays |
252
- | `ANTHROPIC_API_KEY` | `x-api-key: <key>` | official API and a few relays |
218
+ | `ANTHROPIC_AUTH_TOKEN` (default) | `Authorization: Bearer <key>` | Most third-party relays |
219
+ | `ANTHROPIC_API_KEY` | `x-api-key: <key>` | The official API, and a few relays that only accept this |
253
220
 
254
- Some endpoints accept only one; the wrong one yields 401. Switch it in the Edit form;
255
- ccx clears the other on switch to avoid conflicts.
221
+ The wrong one yields 401. Switch it under "Auth field"; on switch ccx clears the other to avoid a leftover conflict.
256
222
 
257
- ## Multiple accounts
223
+ ## Multiple accounts & maintaining presets
258
224
 
259
- For multiple accounts of the same vendor (e.g. personal vs work DeepSeek keys): **just
260
- create multiple profiles**. Picking the same provider a second time auto-names it
261
- `DeepSeek 2`; use the **Note** field to mark "personal / work". The list shows them as
262
- "Provider — Note", easy to tell apart.
225
+ **Multiple accounts**: several keys for the same provider (personal / work)? Just create multiple profiles —
226
+ the second one off the same provider auto-names to `DeepSeek 2`; use **Note** to label them, shown as
227
+ "Provider — Note".
263
228
 
264
- ## Maintaining the provider catalog
265
-
266
- `presets.json` (ships with the tool) is the **provider catalog** — the "Provider" choices
267
- when creating/editing a profile come from here. Add a provider, no code change. Each entry:
229
+ **Maintaining the provider catalog**: `presets.json` (shipped with the tool) is the catalog the "Provider"
230
+ picker reads. Add a provider to offer a new one — no code change:
268
231
 
269
232
  ```json
270
233
  [
@@ -278,93 +241,96 @@ when creating/editing a profile come from here. Add a provider, no code change.
278
241
  ]
279
242
  ```
280
243
 
281
- - `urls` may contain **multiple** entries (e.g. a vendor splitting its API and TokenPlan
282
- across different addresses) — you pick one when choosing that provider.
283
- - `models` are the **recommended** opus/sonnet/haiku mappings, auto-filled on pick (still
284
- editable afterwards).
285
- - `auth` (`AUTH_TOKEN`/`API_KEY`) and `effort` are optional and carried over on pick.
244
+ - `urls` can hold **several** (e.g. API vs TokenPlan endpoints); you choose one when picking the provider.
245
+ - `models` are the recommended three-tier mapping, auto-filled and still editable. `auth` / `effort` are optional.
246
+ - You can also drop a custom catalog at `~/.cc-mini/presets.json` to override the shipped one (highest priority).
247
+
248
+ ## Checking for updates
249
+
250
+ The **Update check** toggle in the main menu is **off by default**. Switch it to **notify** and ccx shows a
251
+ one-line yellow notice atop the menu when a newer release exists, with the upgrade command (it never
252
+ auto-downloads — you decide when to upgrade).
286
253
 
287
- The "API URL" pick list also **auto-collects** URLs already used in your `providers.json`
288
- (tagged `(已有:name)`).
254
+ - No GitHub API; checks at most once a day, cached in `~/.cc-mini/update-check.json`; offline/failure is silent.
255
+ - The check runs in the background and won't slow startup — a new version usually shows up on your **next** launch.
256
+ - To upgrade, just re-run the install command (native: the one-liner under [Install](#install); npm:
257
+ `npm i -g @cc-x/cc-x@latest`).
289
258
 
290
- ## First run: skipping login / onboarding
259
+ ## First run: skip login / onboarding
291
260
 
292
- With a third-party API (token auth) Claude Code may still show the login/onboarding screen
293
- on first launch, because it hasn't recorded that onboarding is done. One-time fix: add
294
- `"hasCompletedOnboarding": true` to `~/.claude.json`.
261
+ With a third-party API (token auth), Claude Code **may still show a login / onboarding screen on first
262
+ launch** — because it hasn't recorded "onboarding done". One-time fix: in `~/.claude.json` (Windows:
263
+ `C:\Users\<you>\.claude.json`), **add a single key** to the top-level `{ }` (keep everything else):
295
264
 
296
- File location:
265
+ ```json
266
+ {
267
+ "hasCompletedOnboarding": true
268
+ }
269
+ ```
297
270
 
298
- - Windows: `C:\Users\<you>\.claude.json`
299
- - macOS / Linux: `~/.claude.json`
271
+ > ⚠️ This file also holds your MCP config — **only add the key, never overwrite the whole file**. ccx
272
+ > deliberately won't edit it for you; it's exactly the file a tool shouldn't touch.
300
273
 
301
- **Important: this file also holds your MCP config — only ADD the key, don't overwrite the
302
- whole file.** If it doesn't exist, create it as `{ "hasCompletedOnboarding": true }`.
274
+ ## Data & file locations
303
275
 
304
- > ccx deliberately does **not** edit this file for you — it's exactly the file no tool
305
- > should mess with. One-time step (some versions may need more; follow official docs).
276
+ - **Profiles (plaintext keys, keep local)**: `~/.cc-mini/providers.json` (also holds `lang` and `update`).
277
+ - **Provider catalog**: the shipped `presets.json`, or `~/.cc-mini/presets.json` to override.
278
+ - **Update-check cache**: `~/.cc-mini/update-check.json`.
279
+ - **"Set default" writes user environment variables** (not Claude config files):
280
+ - **Windows** → registry `HKCU\Environment` + one change broadcast;
281
+ - **macOS / Linux** → a `# >>> xx >>>` … `# <<< xx <<<` marker block in the shell startup file
282
+ (idempotent rewrite, chosen by `$SHELL`).
283
+ - Same semantics either way: **only affects new terminals**; switching to "Official" clears all managed vars.
284
+ - **It modifies no Claude config file.**
306
285
 
307
- ## Files & data
286
+ ccx only ever touches these 7 "managed" variables (and clears the ones a target profile doesn't use):
287
+ `ANTHROPIC_BASE_URL`, `ANTHROPIC_AUTH_TOKEN`, `ANTHROPIC_API_KEY`, `ANTHROPIC_DEFAULT_OPUS_MODEL`,
288
+ `ANTHROPIC_DEFAULT_SONNET_MODEL`, `ANTHROPIC_DEFAULT_HAIKU_MODEL`, `CLAUDE_CODE_EFFORT_LEVEL`.
308
289
 
309
- - Profiles (with keys, stored **in plaintext** locally — don't share): `~/.cc-mini/providers.json`
310
- (also holds the UI `lang`).
311
- - Provider catalog: the shipped `presets.json`; you can also drop a **custom catalog** at
312
- `~/.cc-mini/presets.json` to override it (highest priority).
313
- - "Set as default" writes **user environment variables** (not a Claude config file):
314
- - **Windows** → registry `HKCU\Environment` + a single change broadcast;
315
- - **macOS / Linux** → a `# >>> xx >>>` … `# <<< xx <<<` marker block in your shell startup
316
- file (chosen by `$SHELL`: `~/.zshrc` / `~/.bash_profile` / `~/.bashrc` / `~/.profile`).
317
- - Same semantics either way: **only affects newly opened terminals**; switching to "官方"
318
- clears all managed variables.
319
- - **No Claude config file is ever modified.**
290
+ > 💡 To change `settings.json`, use Claude Code's own `/update-config` and describe what you want in natural
291
+ > language (e.g. "allow npm commands") — safer than letting an external tool rewrite it.
320
292
 
321
293
  ## FAQ
322
294
 
323
- **Will switching in one terminal affect another running terminal?** No. "Use this session"
324
- is per-process; "Set as default" writes user env vars that only apply to **newly started**
325
- processes.
295
+ **Does switching in one terminal affect another running one?** No. "Use this session" is process-level; "Set
296
+ default" only affects **new** processes — running sessions froze their env at start.
297
+
298
+ **I "Set default" but bare `claude` here is still the old one?** Expected — this terminal has the old env.
299
+ **Open a new terminal.**
326
300
 
327
- **I "set as default" but the current terminal still uses the old API.** Expected — open a
328
- **new** terminal.
301
+ **Seeing `... cannot be parsed as a URL`?** A profile's API URL is an invalid value; Edit to fix or delete it.
329
302
 
330
- **I saw `... cannot be parsed as a URL`.** A profile's API URL was set to an invalid value;
331
- fix or delete that profile in Edit.
303
+ **Set effort on a third party but nothing happens?** effort is a Claude-model feature; third parties may not
304
+ support it. DeepSeek recommends `max`; otherwise leave it empty.
332
305
 
333
- **effort has no effect on a third party.** It's a Claude-model feature; third parties may
334
- not support it. DeepSeek recommends `max`; leave others empty.
306
+ **Are keys safe?** Stored in plaintext under your home dir, protected by your account. Don't commit
307
+ `providers.json` to a repo.
335
308
 
336
309
  ## Uninstall
337
310
 
338
- - **Clear env vars first**: run `xx` → Set as default → 官方 to clear all managed variables.
339
- - Remove the tool itself:
340
- - native Windows build: delete `%LOCALAPPDATA%\Programs\ccx` and remove that directory
341
- from the user PATH, or run:
342
- ```powershell
343
- powershell -NoProfile -ExecutionPolicy Bypass -Command "$s = irm https://github.com/becomeless/cc-x/releases/latest/download/install.ps1; & ([scriptblock]::Create($s)) -Uninstall"
344
- ```
345
- - native macOS / Linux build:
346
- ```bash
347
- curl -fsSL https://github.com/becomeless/cc-x/releases/latest/download/install.sh | sh -s -- --uninstall
348
- ```
349
- - npm build: `npm uninstall -g @cc-x/cc-x`;
350
- - on macOS / Linux, also remove the `# >>> xx >>>` marker block from your shell startup file
351
- if you ever used "Set as default".
352
- - Delete the data dir `~/.cc-mini/`.
353
-
354
- ## Philosophy
355
-
356
- ccx was born out of my own friction using cc-switch. This isn't a criticism — cc-switch is
357
- powerful and capable; I just wanted a lighter path.
358
-
359
- So ccx follows a single principle: **the simpler, the better.**
360
-
361
- - Do one thing — switch the API — and do it well;
362
- - Touch as little as possible — above all, **never write Claude Code config files**
363
- (`~/.claude/settings.json`, `~/.claude.json`);
364
- - Before adding any feature, ask first: can we *not* add it?
365
-
366
- Issues / PRs welcome. But remember: **a change that makes ccx simpler is more welcome than one
367
- that makes it more powerful.** Any change that writes Claude Code config files will not be accepted.
311
+ 1. **Clear env vars first**: run "Set default → Official" once in `xx` to clear all managed variables.
312
+ 2. **Remove the binary**:
313
+ - Windows native:
314
+ ```powershell
315
+ powershell -NoProfile -ExecutionPolicy Bypass -Command "$s = irm https://github.com/becomeless/cc-x/releases/latest/download/install.ps1; & ([scriptblock]::Create($s)) -Uninstall"
316
+ ```
317
+ - macOS / Linux native:
318
+ ```bash
319
+ curl -fsSL https://github.com/becomeless/cc-x/releases/latest/download/install.sh | sh -s -- --uninstall
320
+ ```
321
+ - npm: `npm uninstall -g @cc-x/cc-x`.
322
+ - macOS / Linux, if you used "Set default", also delete the `# >>> xx >>>` marker block in your shell startup file.
323
+ 3. Delete the data dir `~/.cc-mini/`.
324
+
325
+ ## Design principles
326
+
327
+ ccx was born from friction I kept hitting with cc-switch — not a criticism; it's powerful, I just wanted a
328
+ lighter path. So ccx holds one principle: **simpler is better.** Do one job (switch the API); touch as little
329
+ as possible (above all, **never write a Claude Code config file**); before adding a feature, ask whether it
330
+ can be left out.
331
+
332
+ Issues / PRs welcome — but **changes that make it simpler are more welcome than ones that make it more
333
+ powerful**, and anything that writes a Claude Code config file will not be accepted.
368
334
 
369
335
  ## License
370
336