@cc-x/cc-x 0.4.3 → 0.4.5

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 +170 -296
  2. package/README.md +131 -292
  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
@@ -1,370 +1,244 @@
1
1
  # ccx
2
2
 
3
+ > `xx` — one command to switch Claude Code between APIs. **Zero config risk.**
4
+ >
3
5
  > [简体中文](README.md) | English
4
6
 
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.).
7
+ Switching Claude Code between the official account and third-party APIs means juggling
8
+ environment variables — or trusting a tool that rewrites your Claude config. ccx takes a
9
+ different path: **switching happens purely at the environment-variable layer.** It never
10
+ reads or writes any Claude Code config file. Your MCP, plugins, hooks — it won't touch them.
8
11
 
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**.
12
+ ```text
13
+ cc-x v0.4.4 · Claude Code API switcher (default = used by bare `claude` in new terminals)
13
14
 
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`).
15
+ ▶ Official (default)[Logged in]
16
+ DeepSeek [Key set] — work
17
+ 智谱GLM [No key]
18
+ 小米MiMo [No key]
18
19
 
19
- ---
20
-
21
- ## Why it exists
20
+ New profile · 切换到中文 · Update check: off · Exit
22
21
 
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.
29
-
30
- ## ccx vs cc-switch
22
+ ↑↓ move · Enter open · Shift+↑↓ reorder · q quit
23
+ ```
31
24
 
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:
25
+ > **Two builds**: the **native Go build** is recommended — GitHub Releases provide a lightweight
26
+ > `xx` / `xx.exe` with no Node.js, for Windows x64, macOS Intel / Apple Silicon, Linux x64 / arm64.
27
+ > If you prefer npm, install `@cc-x/cc-x` (command is still `xx`). Both builds are feature-equal.
35
28
 
36
- | | ccx (command `xx`) | cc-switch |
37
- |---|---|---|
38
- | Form | Terminal command (lightweight) | Desktop GUI (full-featured) |
39
- | Scope | Only switches the API | API + MCP + multiple CLIs + prompts… |
40
- | Touches config files? | **No** (env vars only) | Rewrites config files from its own DB |
41
- | Can lose MCP / plugins? | **Impossible by design** | Users have reported it overwriting them |
42
- | Different API per terminal | **Native** (process-level isolation) | Global switch; sessions can interfere |
43
-
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`.
29
+ ---
75
30
 
76
31
  ## Install
77
32
 
78
- **Native Windows build (recommended)**
33
+ > Install [Claude Code](https://claude.ai/code) first (`claude` on PATH). **Open a new terminal** after installing.
34
+
35
+ **Windows (native, recommended)**
79
36
 
80
37
  ```powershell
81
38
  irm https://github.com/becomeless/cc-x/releases/latest/download/install.ps1 | iex
82
39
  ```
83
40
 
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
- ```
41
+ The installer chooses a per-user directory and adds it to your user PATH automatically, so no administrator rights or manual PATH edits are needed.
91
42
 
92
- **Native macOS / Linux build (recommended)**
43
+ **macOS / Linux (native, recommended)**
93
44
 
94
45
  ```bash
95
46
  curl -fsSL https://github.com/becomeless/cc-x/releases/latest/download/install.sh | sh
96
47
  ```
97
48
 
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
- ```
49
+ The installer places `xx` in a user-level command directory. If that directory isn't on PATH,
50
+ it prints a hint (the Unix installer deliberately doesn't edit your shell config).
106
51
 
107
- **Cross-platform npm build**
52
+ **npm (any platform, Node.js ≥ 18)**
108
53
 
109
54
  ```bash
110
55
  npm install -g @cc-x/cc-x
111
56
  ```
112
57
 
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`.)
58
+ ---
59
+
60
+ ## 60-second quick start
115
61
 
116
- **From source (dev / custom)**
62
+ The first run of `xx` seeds 4 profiles in `~/.cc-mini/providers.json` (Official + DeepSeek +
63
+ Zhipu GLM + Xiaomi MiMo), **with empty keys**.
64
+
65
+ 1. `xx` → ↑↓ to a profile → Enter → **Edit** → **API key** → paste your key
66
+ 2. Then either:
67
+ - **Use this session** — launch Claude now in this terminal (temporary, parallel-friendly)
68
+ - **Set default** — bare `claude` in new terminals uses it from now on
117
69
 
118
70
  ```bash
119
- git clone https://github.com/becomeless/cc-x
120
- cd cc-x
71
+ xx # open the menu
72
+ xx DeepSeek # set as default
73
+ xx DeepSeek -s # use this session, launch Claude now (--session)
74
+ xx -l # list all profiles and state (--list)
75
+ xx --help # all options
121
76
  ```
122
77
 
123
- Native Go release build with version injection and multi-platform assets:
78
+ ---
124
79
 
125
- ```powershell
126
- .\scripts\build-release.ps1 -Version 0.4.2
127
- .\dist\release\ccx_0.4.2_windows_amd64\xx.exe --version
128
- ```
80
+ ## Two modes (the key concept)
129
81
 
130
- npm build:
82
+ Which API Claude uses is decided by **environment variables**. ccx offers two scopes:
131
83
 
132
- ```bash
133
- npm install
134
- npm run build
135
- npm link # then `xx` is available
136
- ```
84
+ | | Use this session (`-s`) | Set default |
85
+ |---|---|---|
86
+ | Mechanism | Sets env vars on this process + launches `claude` | Writes **user environment variables** |
87
+ | Scope | This terminal only; **gone when you close it** | **New** terminals going forward |
88
+ | Running sessions | Unaffected | Unaffected (env freezes at process start) |
89
+ | Best for | Parallel terminals on different APIs | Set your daily-driver API once |
137
90
 
138
- **Open a new terminal afterwards.**
91
+ **Parallel example**: open 4 terminals and run `xx Official -s`, `xx DeepSeek -s`, `xx 智谱GLM -s`,
92
+ `xx 小米MiMo -s` — four Claudes running at once, each on its own API, zero interference.
139
93
 
140
- ## Quick start
94
+ **Why not a global config file?** `settings.json` is shared globally; editing it hits running
95
+ sessions (classic symptom: another terminal suddenly says `cannot be parsed as a URL`).
96
+ Environment variables are naturally process-isolated.
141
97
 
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).
98
+ ---
148
99
 
149
- ## The two activation modes (core concept)
100
+ ## ccx vs cc-switch
150
101
 
151
- Which API Claude uses is ultimately decided by **environment variables**. ccx offers two
152
- scopes:
102
+ cc-switch is an excellent full-featured GUI; ccx takes the opposite, minimal approach.
153
103
 
154
- | | Use this session | Set as default |
104
+ | | ccx (`xx`) | cc-switch |
155
105
  |---|---|---|
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
106
+ | Form | Terminal command (lightweight) | Desktop GUI (full-featured) |
107
+ | Scope | Just API switching | API + MCP + multiple CLIs + prompts… |
108
+ | Touches config? | **Never** (env vars only) | Rewrites config from its own DB |
109
+ | Can lose MCP? | **Physically impossible** | Users have reported it |
110
+ | Parallel terminals | **Native** (process isolation) | Global switch; sessions can clash |
200
111
 
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
208
- ```
112
+ - → **ccx**: terminal natives, parallel-session runners, anyone burned by a config-wrecking switcher, "just switch the API" people
113
+ - → **cc-switch**: GUI preference, all-in-one MCP + multi-CLI management
209
114
 
210
- ## Profile fields
115
+ ---
211
116
 
212
- | Field | Env var | Notes |
213
- |---|---|---|
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 |
239
- |---|---|---|---|---|
240
- | 官方 (official) | (empty = login) | — | — | empty / `auto` |
241
- | DeepSeek | `https://api.deepseek.com/anthropic` | `deepseek-v4-pro` | `deepseek-v4-flash` | `max` (per their docs) |
242
- | Zhipu GLM | `https://open.bigmodel.cn/api/anthropic` | `GLM-4.7` | `glm-4.5-air` | empty |
243
- | 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 |
117
+ ## Design philosophy
118
+
119
+ > ccx cares more about boundaries than features.
244
120
 
245
- > Model names change as providers update; follow each provider's official docs.
121
+ Claude Code already has its own config system, MCP ecosystem, and session state. ccx is not trying to become a control panel above it, or to copy user config into another database. It stands at one narrow point before Claude Code starts: prepare the 7 managed environment variables, then let Claude Code run.
246
122
 
247
- ## Auth field: AUTH_TOKEN vs API_KEY
123
+ That constraint is deliberate: no writes to Claude Code config files, no MCP management, no automatic migration, no resident background controller. If process environment variables can solve it, ccx avoids global files; if a choice matters, the user makes it explicitly. Doing less keeps the failure surface small.
248
124
 
249
- | Option | Actual header | Used by |
125
+ Issues / PRs are welcome, but the direction is clear: **make switching steadier, clearer, and less intrusive** before adding broader management power. Anything that writes a Claude Code config file will not be accepted.
126
+
127
+ ---
128
+
129
+ ## Configuration
130
+
131
+ ### Fields
132
+
133
+ | Field | Environment variable | Notes |
250
134
  |---|---|---|
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 |
253
-
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.
256
-
257
- ## Multiple accounts
258
-
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.
263
-
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:
268
-
269
- ```json
270
- [
271
- {
272
- "name": "DeepSeek",
273
- "auth": "AUTH_TOKEN",
274
- "effort": "max",
275
- "urls": [ { "label": "Anthropic-compatible", "url": "https://api.deepseek.com/anthropic" } ],
276
- "models": { "opus": "deepseek-v4-pro", "sonnet": "deepseek-v4-pro", "haiku": "deepseek-v4-flash" }
277
- }
278
- ]
279
- ```
135
+ | API URL | `ANTHROPIC_BASE_URL` | Third-party endpoint; empty for Official = logged-in session |
136
+ | Auth field | — | `AUTH_TOKEN` (default) or `API_KEY`; **wrong one = 401** |
137
+ | API key | `ANTHROPIC_AUTH_TOKEN` or `ANTHROPIC_API_KEY` | Value for the chosen auth field |
138
+ | opus → model | `ANTHROPIC_DEFAULT_OPUS_MODEL` | Three-tier model mapping; haiku also covers background tasks — **must be set** |
139
+ | sonnet → model | `ANTHROPIC_DEFAULT_SONNET_MODEL` | |
140
+ | haiku → model | `ANTHROPIC_DEFAULT_HAIKU_MODEL` | |
141
+ | effort level | `CLAUDE_CODE_EFFORT_LEVEL` | `low`–`max`; `auto` = model default; empty = unset. Third parties may not honor it |
280
142
 
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.
143
+ > ccx **deliberately does not set** `ANTHROPIC_MODEL`. Use `/model opus|sonnet|haiku` in-session;
144
+ > the mapping table translates to the provider's real model name.
286
145
 
287
- The "API URL" pick list also **auto-collects** URLs already used in your `providers.json`
288
- (tagged `(已有:name)`).
146
+ ### Auth field: AUTH_TOKEN vs API_KEY
289
147
 
290
- ## First run: skipping login / onboarding
148
+ | Option | Request header | Used by |
149
+ |---|---|---|
150
+ | `AUTH_TOKEN` (default) | `Authorization: Bearer <key>` | Most third-party relays |
151
+ | `API_KEY` | `x-api-key: <key>` | The official API, and a few relays |
152
+
153
+ ### Pre-seeded profiles
291
154
 
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`.
155
+ | Profile | BASE_URL | OPUS / SONNET | HAIKU (incl. background) | effort |
156
+ |---|---|---|---|---|
157
+ | Official | empty (logged-in) | — | — | — |
158
+ | DeepSeek | `https://api.deepseek.com/anthropic` | `deepseek-v4-pro` | `deepseek-v4-flash` | `max` (recommended) |
159
+ | Zhipu GLM | `https://open.bigmodel.cn/api/anthropic` | `GLM-4.7` | `glm-4.5-air` | — |
160
+ | Xiaomi MiMo | `https://api.xiaomimimo.com/anthropic` | `mimo-v2.5-pro` | `mimo-v2.5-pro` | — |
161
+
162
+ > Model names change as providers update. Xiaomi MiMo has both pay-as-you-go and TokenPlan
163
+ > endpoints; you pick one when selecting the provider.
164
+
165
+ ### Advanced
166
+
167
+ - **Multiple accounts**: create multiple profiles from the same provider — names auto-suffix
168
+ with ` 2`, ` 3`… Use **Note** to tell them apart, shown as "Provider — Note".
169
+ - **Custom providers**: `presets.json` is the provider catalog; add a JSON entry to offer a new
170
+ one, no code change. Drop `~/.cc-mini/presets.json` to override the shipped catalog.
171
+ - **First-launch login prompt**: third-party APIs may still show onboarding. Add
172
+ `"hasCompletedOnboarding": true` to `~/.claude.json` (**only this key** — don't overwrite
173
+ the file; it also holds your MCP config).
174
+ - **Update check**: toggle to "notify" in the menu — a yellow one-liner appears atop the menu
175
+ when a new release is out. At most one check per day; never auto-upgrades.
295
176
 
296
- File location:
177
+ ---
297
178
 
298
- - Windows: `C:\Users\<you>\.claude.json`
299
- - macOS / Linux: `~/.claude.json`
179
+ ## Data & files
300
180
 
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 }`.
181
+ - **Profiles (plaintext keys, keep local)**: `~/.cc-mini/providers.json` (also holds `lang` and `update`)
182
+ - **Provider catalog**: shipped `presets.json`; override at `~/.cc-mini/presets.json`
183
+ - **"Set default" writes user environment variables** (not Claude config files):
184
+ - Windows → registry `HKCU\Environment` + one change broadcast
185
+ - Unix → `# >>> xx >>>` … `# <<< xx <<<` marker block in shell startup file (idempotent rewrite, chosen by `$SHELL`)
186
+ - Same semantics either way: **only affects new terminals**; switching to "Official" clears all managed vars
187
+ - **No Claude Code config file is ever modified.**
303
188
 
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).
189
+ ccx only touches these 7 "managed" variables (and clears the ones a target profile doesn't use):
190
+ `ANTHROPIC_BASE_URL`, `ANTHROPIC_AUTH_TOKEN`, `ANTHROPIC_API_KEY`, `ANTHROPIC_DEFAULT_OPUS_MODEL`,
191
+ `ANTHROPIC_DEFAULT_SONNET_MODEL`, `ANTHROPIC_DEFAULT_HAIKU_MODEL`, `CLAUDE_CODE_EFFORT_LEVEL`.
306
192
 
307
- ## Files & data
193
+ > 💡 To change `settings.json`, use Claude Code's own `/update-config` and describe what you want
194
+ > in natural language (e.g. "allow npm commands") — safer than letting an external tool rewrite it.
308
195
 
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.**
196
+ ---
320
197
 
321
198
  ## FAQ
322
199
 
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.
200
+ **Does switching in one terminal affect another?** No. "Use this session" is process-scoped;
201
+ "Set default" only affects new terminals.
202
+
203
+ **I set default but bare `claude` here is still the old one?** Expected — this terminal has
204
+ the old env. Open a new one.
326
205
 
327
- **I "set as default" but the current terminal still uses the old API.** Expected — open a
328
- **new** terminal.
206
+ **Seeing `cannot be parsed as a URL`?** A profile's API URL is invalid. Edit to fix or delete it.
329
207
 
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.
208
+ **Set effort on a third party but nothing happens?** effort is a Claude-model feature; third
209
+ parties may not support it. DeepSeek recommends `max`; leave empty otherwise.
332
210
 
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.
211
+ **Are keys safe?** Plaintext in your home dir, protected by your OS account. Don't commit
212
+ `providers.json` to a repo.
213
+
214
+ **Can I choose the install directory?** Yes. The Windows installer supports `-InstallDir`;
215
+ macOS / Linux supports `CCX_INSTALL_DIR` or `--install-dir`. Most users should keep the default;
216
+ if you change it, pass the same directory when uninstalling.
217
+
218
+ **Can I download the binary manually?** Yes. Go to [GitHub Releases](https://github.com/becomeless/cc-x/releases/latest),
219
+ download the zip / tar.gz for your platform, extract it, and put `xx` / `xx.exe` somewhere on PATH.
220
+ For most users, the install command above is better: it picks the platform, verifies checksums, and handles PATH / uninstall.
221
+
222
+ ---
335
223
 
336
224
  ## Uninstall
337
225
 
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.
226
+ 1. Clear env vars: `xx` → Official → Set default
227
+ 2. Remove the binary:
228
+ - Windows native:
229
+ ```powershell
230
+ $s = irm https://github.com/becomeless/cc-x/releases/latest/download/install.ps1
231
+ & ([scriptblock]::Create($s)) -Uninstall
232
+ ```
233
+ This removes the installed files and automatically removes the matching user PATH entry.
234
+ - macOS / Linux native:
235
+ ```bash
236
+ curl -fsSL https://github.com/becomeless/cc-x/releases/latest/download/install.sh | sh -s -- --uninstall
237
+ ```
238
+ - npm: `npm uninstall -g @cc-x/cc-x`
239
+ 3. Delete data: `rm -rf ~/.cc-mini`
240
+
241
+ ---
368
242
 
369
243
  ## License
370
244