@carjms/codexswitch 0.1.0 → 0.3.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 (6) hide show
  1. package/README.ko.md +300 -0
  2. package/README.md +157 -129
  3. package/package.json +1 -1
  4. package/src/cli.js +297 -24
  5. package/src/runner.js +102 -5
  6. package/src/store.js +71 -9
package/README.md CHANGED
@@ -1,46 +1,48 @@
1
1
  # codexswitch
2
2
 
3
- **OpenAI Codex CLI 계정을 여러 개 등록해두고, 클릭 한 번(명령 한 줄)으로 전환하거나, 사용량 한도에 걸리면 자동으로 다음 계정으로 넘어가게 해주는 도구입니다.**
3
+ **English** | [한국어](README.ko.md)
4
4
 
5
- [KarpelesLab/teamclaude](https://github.com/KarpelesLab/teamclaude)(Claude용 멀티 계정 도구)에서 영감을 받아 Codex CLI에 맞게 만들었습니다. macOS / Windows / Linux를 지원하며, Node.js만 있으면 되고 외부 의존성은 없습니다.
5
+ **Register multiple OpenAI Codex CLI accounts, switch between them with a single command, and automatically rotate to the next account when you hit a usage limit.**
6
6
 
7
- ## 이런 분께 필요합니다
7
+ Inspired by [KarpelesLab/teamclaude](https://github.com/KarpelesLab/teamclaude) (a multi-account tool for Claude), adapted for the Codex CLI. Supports macOS / Windows / Linux, requires only Node.js, and has zero external dependencies.
8
8
 
9
- - ChatGPT 계정이 2개 이상 있고(개인용/회사용, Plus/Pro 등) Codex를 계정 바꿔가며 쓰고 싶은 분
10
- - 한 계정의 사용량 한도(usage limit)가 차면 **자동으로 다른 계정으로 이어서** 작업하고 싶은 분
11
- - 매번 `codex logout` → `codex login`을 반복하는 게 지겨운 분
9
+ ## Who is this for?
12
10
 
13
- Codex CLI는 로그인 정보를 한 파일(`auth.json`)에만 저장해서 원래 계정 1개만 쓸 수 있습니다. codexswitch이 이 한계를 풀어줍니다.
11
+ - You have two or more ChatGPT accounts (personal/work, Plus/Pro, ...) and want to use Codex across them
12
+ - You want to **continue working on another account automatically** when one account hits its usage limit
13
+ - You are tired of repeating `codex logout` → `codex login` every time
14
+
15
+ The Codex CLI stores credentials in a single file (`auth.json`), so out of the box it only supports one account. codexswitch removes that limitation.
14
16
 
15
17
  ---
16
18
 
17
- ## 1. 준비물
19
+ ## 1. Prerequisites
18
20
 
19
- 두 가지가 미리 설치되어 있어야 합니다.
21
+ Two things must be installed first.
20
22
 
21
- ### ① Node.js (v18 이상)
23
+ ### ① Node.js (v18+)
22
24
 
23
- 터미널에서 `node --version`을 입력했을 때 `v18` 이상이 나오면 이 단계는 건너뛰세요.
25
+ If `node --version` prints `v18` or higher, skip this step.
24
26
 
25
- - **macOS**: [nodejs.org](https://nodejs.org/)에서 LTS 버전 설치 파일(.pkg)을 받아 실행하거나, Homebrew가 있다면 터미널에서:
27
+ - **macOS**: download the LTS installer (.pkg) from [nodejs.org](https://nodejs.org/), or with Homebrew:
26
28
  ```bash
27
29
  brew install node
28
30
  ```
29
- - **Windows**: [nodejs.org](https://nodejs.org/)에서 LTS 버전 설치 파일(.msi)을 받아 실행하세요. 설치 중 옵션은 전부 기본값 그대로 "다음"만 눌러도 됩니다.
31
+ - **Windows**: download the LTS installer (.msi) from [nodejs.org](https://nodejs.org/) and run it. The default options are fine.
30
32
 
31
33
  ### ② Codex CLI
32
34
 
33
- - **macOS** — 터미널(응용 프로그램 → 유틸리티 → 터미널)에서:
35
+ - **macOS** — in Terminal (Applications → Utilities → Terminal):
34
36
  ```bash
35
37
  npm install -g @openai/codex
36
38
  ```
37
- - **Windows** — PowerShell(시작 메뉴에서 "PowerShell" 검색 → 실행)에서:
39
+ - **Windows** — in PowerShell (search "PowerShell" in the Start menu):
38
40
  ```powershell
39
41
  npm install -g @openai/codex
40
42
  ```
41
- > 참고: Codex CLI는 Windows 네이티브 지원이 실험적(experimental) 단계라, OpenAI는 WSL(Windows Subsystem for Linux) 사용을 권장합니다. WSL을 쓰신다면 WSL 터미널 안에서 macOS/Linux 방법을 그대로 따라 하시면 됩니다.
43
+ > Note: native Windows support in the Codex CLI is experimental; OpenAI recommends WSL (Windows Subsystem for Linux). If you use WSL, just follow the macOS/Linux instructions inside your WSL terminal.
42
44
 
43
- 설치 확인:
45
+ Verify:
44
46
 
45
47
  ```bash
46
48
  codex --version
@@ -48,31 +50,31 @@ codex --version
48
50
 
49
51
  ---
50
52
 
51
- ## 2. codexswitch 설치
53
+ ## 2. Install codexswitch
52
54
 
53
- macOS와 Windows 모두 같은 명령입니다 (macOS는 터미널, Windows는 PowerShell):
55
+ Same command on macOS (Terminal) and Windows (PowerShell):
54
56
 
55
57
  ```bash
56
58
  npm install -g @carjms/codexswitch
57
59
  ```
58
60
 
59
- 설치 확인:
61
+ Verify:
60
62
 
61
63
  ```bash
62
64
  codexswitch help
63
65
  ```
64
66
 
65
- 도움말이 나오면 성공입니다. `codexswitch`과 짧은 별칭 `cxs` 두 명령 모두 똑같이 동작합니다 (아래 예시는 짧은 `cxs`를 사용합니다).
67
+ If you see the help text, you are done. `codexswitch` and the short alias `cxs` behave identically (the examples below use `cxs`).
66
68
 
67
69
  ---
68
70
 
69
- ## 3. 처음 시작하기 (5분 가이드)
71
+ ## 3. Getting started (5 minutes)
70
72
 
71
- 계정 2개를 등록하고 전환해보는 전체 과정입니다.
73
+ A full walkthrough: register two accounts and switch between them.
72
74
 
73
- ### 3-1. 이미 로그인된 계정 등록하기
75
+ ### 3-1. Register the account you are already logged in with
74
76
 
75
- 전에 `codex login`을 해본 적이 있다면, 그 계정을 그대로 가져옵니다:
77
+ If you have run `codex login` before, import that account as-is:
76
78
 
77
79
  ```bash
78
80
  cxs import
@@ -83,21 +85,21 @@ added account "me@gmail.com" (me@gmail.com, plus)
83
85
  set "me@gmail.com" as the active account
84
86
  ```
85
87
 
86
- 이름을 직접 붙이고 싶다면 `cxs import 개인용` 처럼 뒤에 이름을 쓰면 됩니다.
88
+ To pick your own name, append it: `cxs import personal`.
87
89
 
88
- > 아직 한 번도 로그인한 적이 없다면 이 단계는 건너뛰고 3-2로 가세요.
90
+ > Never logged in? Skip to 3-2.
89
91
 
90
- ### 3-2. 두 번째 계정 로그인하기
92
+ ### 3-2. Log in with a second account
91
93
 
92
94
  ```bash
93
- cxs login 회사용
95
+ cxs login work
94
96
  ```
95
97
 
96
- 브라우저가 열리면 **추가할 ChatGPT 계정으로** 로그인하세요. (이미 브라우저에 다른 계정이 로그인돼 있다면 로그인 화면에서 계정을 전환하세요.)
98
+ A browser opens — log in with the **account you want to add**. (If your browser is already signed in to another account, switch accounts on the login screen.)
97
99
 
98
- > 이 과정은 격리된 임시 공간에서 진행되므로 **기존 계정 로그인은 전혀 건드리지 않습니다.**
100
+ > This happens in an isolated temporary profile, so **your existing login is untouched.**
99
101
 
100
- ### 3-3. 등록된 계정 확인
102
+ ### 3-3. List registered accounts
101
103
 
102
104
  ```bash
103
105
  cxs list
@@ -107,168 +109,194 @@ cxs list
107
109
  name email plan prio status token refreshed
108
110
  - ------------ ---------------- ---- ---- ------ ----------------
109
111
  * me@gmail.com me@gmail.com plus 0 ok 2026-07-08 09:12
110
- 회사용 work@company.com pro 0 ok 2026-07-08 09:15
112
+ work work@company.com pro 0 ok 2026-07-08 09:15
111
113
  ```
112
114
 
113
- `*` 표시가 현재 활성 계정입니다.
115
+ `*` marks the active account.
114
116
 
115
- ### 3-4. 계정 전환
117
+ ### 3-4. Switch accounts
116
118
 
117
119
  ```bash
118
- cxs use 회사용
120
+ cxs use work
119
121
  ```
120
122
 
121
- 이제부터 평소처럼 `codex`를 실행하면 회사용 계정으로 동작합니다. 다시 바꾸려면 `cxs use me@gmail.com`, 또는 `cxs next`(다음 계정으로 순환).
123
+ From now on, plain `codex` runs as the work account. Switch back with `cxs use me@gmail.com`, or cycle with `cxs next`.
122
124
 
123
- ### 3-5. 한도 자동 전환으로 실행하기 (핵심 기능)
125
+ ### 3-5. Run with automatic limit rotation (the key feature)
124
126
 
125
127
  ```bash
126
- cxs exec "이 프로젝트의 테스트 코드를 작성해줘"
128
+ cxs exec "write tests for this project"
127
129
  ```
128
130
 
129
- `codex exec`를 실행하다가 **사용량 한도에 걸리면**:
131
+ While running `codex exec`, if the account **hits a usage limit**:
130
132
 
131
- 1. 그 계정을 일정 시간 "한도 걸림"으로 표시하고 (에러 메시지의 "try again in 2 hours" 같은 시간을 자동 인식)
132
- 2. 다음 사용 가능한 계정으로 **같은 명령을 자동 재시도**합니다
133
- 3. 모든 계정이 소진되면 그때 멈춥니다
133
+ 1. The account is marked "limited" for a while (times like "try again in 2 hours" in the error message are parsed automatically)
134
+ 2. The next usable account **resumes the same session** (`codex exec resume`) and continues from where it stopped — no restarting from scratch (opt out with `--no-resume`)
135
+ 3. It only stops when every account is exhausted
134
136
 
135
137
  ```
136
138
  [codexswitch] exec as "me@gmail.com"
137
- ... (작업 중 한도 도달) ...
139
+ ... (usage limit reached mid-run) ...
138
140
  [codexswitch] "me@gmail.com" hit a usage/rate limit (paused until 2026-07-08 14:30) — rotating
139
- [codexswitch] exec as "회사용" (attempt 2)
140
- ... (이어서 작업) ...
141
+ [codexswitch] exec as "work" (attempt 2)
142
+ ... (work continues) ...
141
143
  ```
142
144
 
143
- ### 3-6. 계정 전환 없이 특정 계정으로 실행
145
+ `cxs exec` also adds `--skip-git-repo-check` automatically, so it works in folders that are not git repositories.
146
+
147
+ ### 3-6. Run one account without switching
144
148
 
145
- 전역 활성 계정은 그대로 두고, 이번 한 번만 다른 계정으로 실행할 수도 있습니다:
149
+ Leave the globally active account alone and run a different account just this once:
146
150
 
147
151
  ```bash
148
- cxs run 회사용 # 회사용 계정으로 codex 대화형 실행
149
- cxs run 회사용 exec "..." # 회사용 계정으로 codex exec 실행
152
+ cxs run work # interactive codex as "work"
153
+ cxs run work exec "..." # codex exec as "work"
150
154
  ```
151
155
 
152
- 각 계정은 격리된 자기만의 환경에서 실행되므로, **터미널 2개를 열어 서로 다른 계정으로 동시에 codex를 돌릴 수도 있습니다.** (설정과 세션 기록은 공유됩니다.)
156
+ Each account runs in its own isolated environment, so you can even **open two terminals and run codex as two different accounts simultaneously.** (Config and session history are shared.)
153
157
 
154
- ---
158
+ ### 3-7. Set the rotation order and a default model
155
159
 
156
- ## 4. 명령어 전체 목록
160
+ Set the rotation order in one command. `exec` and `next` follow this order afterwards:
157
161
 
158
- | 명령 | 설명 |
159
- |---|---|
160
- | `cxs login [이름]` | 새 계정 로그인 후 저장 (기존 로그인 유지, 이름 생략 시 이메일 사용) |
161
- | `cxs import [이름]` | 현재 `~/.codex`에 로그인된 계정을 저장소로 가져오기 |
162
- | `cxs list` | 계정 목록: 활성 표시(`*`), 이메일, 플랜, 우선순위, 한도 상태 |
163
- | `cxs use <이름>` | 활성 계정 전환 |
164
- | `cxs current` | 현재 활성 계정 확인 |
165
- | `cxs next` | 다음 사용 가능한 계정으로 순환 전환 |
166
- | `cxs run [이름] [인자...]` | 전환 없이 특정 계정으로 codex 실행 (격리 환경) |
167
- | `cxs exec [인자...]` | `codex exec` + 한도 도달 시 자동 계정 로테이션 |
168
- | `cxs exec -a <이름> ...` | 특정 계정부터 exec 시작 |
169
- | `cxs remove <이름>` | 계정 삭제 |
170
- | `cxs rename <옛이름> <새이름>` | 계정 이름 변경 |
171
- | `cxs disable / enable <이름>` | 로테이션에서 임시 제외 / 복귀 |
172
- | `cxs priority <이름> <숫자>` | 로테이션 우선순위 (낮을수록 먼저, 기본 0) |
173
- | `cxs clear-limit <이름>` | 기록된 한도 상태 수동 해제 |
174
- | `cxs cooldown [분]` | 한도 감지 시 기본 대기 시간 조회/설정 (기본 60분) |
175
- | `cxs sync` | codex가 갱신한 토큰을 저장소에 반영 |
162
+ ```bash
163
+ cxs order work me@gmail.com # use "work" first, then me@gmail.com
164
+ cxs order # show the current order
165
+ ```
176
166
 
177
- ---
167
+ Set a default model to inject into every `run`/`exec` (an explicit `-m` always wins):
178
168
 
179
- ## 5. 자주 묻는 질문 / 문제 해결
169
+ ```bash
170
+ cxs model gpt-5.2-codex # set the default model
171
+ cxs model # show the current setting
172
+ cxs model default # reset to the codex default
173
+ ```
180
174
 
181
- **Q. `codexswitch: command not found` (또는 "인식할 수 없는 명령") 이 떠요.**
182
- npm 전역 설치 경로가 PATH에 없는 경우입니다. 터미널/PowerShell을 **완전히 닫았다 다시 열어보세요.** 그래도 안 되면 `npm config get prefix`로 나온 경로(Windows는 그 경로 자체, macOS는 그 아래 `bin` 폴더)를 PATH에 추가하세요.
175
+ ### 3-8. Register an OpenAI API-key account
183
176
 
184
- **Q. macOS에서 `npm install -g` 하다가 `EACCES` 권한 오류가 나요.**
185
- `sudo npm install -g @carjms/codexswitch`로 설치하거나, 더 좋은 방법으로는 [nvm](https://github.com/nvm-sh/nvm)으로 Node.js를 설치하면 권한 문제가 사라집니다.
177
+ You can also register an account billed through API credits (Platform) instead of a ChatGPT subscription:
186
178
 
187
- **Q. `codex CLI not found` 오류가 나요.**
188
- Codex CLI가 설치되지 않았거나 PATH에 없는 경우입니다. `npm install -g @openai/codex` 후 다시 시도하세요. 특별한 위치에 설치했다면 환경변수 `CODEX_SWITCH_CODEX_BIN`에 전체 경로를 지정하면 됩니다.
179
+ ```bash
180
+ cxs add-key api-account sk-your-api-key
181
+ ```
189
182
 
190
- **Q. 계정을 전환하면 기존 대화 세션이나 설정이 날아가나요?**
191
- 아니요. 전환되는 것은 **인증 정보(auth.json)뿐**입니다. `config.toml` 설정, 세션 기록, 스킬 등은 모든 계정이 공유합니다.
183
+ > Tip: to keep the key out of your shell history, omit it and pass it via the environment:
184
+ > `OPENAI_API_KEY=sk-... cxs add-key api-account`
192
185
 
193
- **Q. Windows에서 `run`/`exec`가 잘 동작하나요?**
194
- 동작합니다. 내부적으로 macOS/Linux는 심볼릭 링크, Windows는 디렉토리 정션(관리자 권한 불필요)을 사용합니다. 파일 공유까지 완전하게 하려면 Windows **설정 → 개발자 모드**를 켜는 것을 추천하지만, 꺼져 있어도 복사 방식으로 자동 대체되어 문제없이 동작합니다.
186
+ ### 3-9. Usage thresholds (rotate before hitting the wall)
195
187
 
196
- **Q. 한도에 걸렸다고 표시된 계정을 바로 다시 쓰고 싶어요.**
197
- `cxs clear-limit <이름>` 으로 해제하면 됩니다.
188
+ Accounts whose recorded 5-hour/weekly usage reaches the configured percentage are skipped in rotation automatically (default 95%):
198
189
 
199
- **Q. 계정 이름에 한글을 써도 되나요?**
200
- 네. `회사용`, `개인용` 같은 한글 이름 모두 가능합니다. (허용 문자: 한글 등 모든 언어의 글자, 숫자, 공백, `@ . _ + -`)
190
+ ```bash
191
+ cxs threshold 90 # both 5h and weekly at 90%
192
+ cxs threshold 90 98 # 5h at 90%, weekly at 98%
193
+ cxs threshold # show current settings
194
+ cxs list # per-account 5h/week usage columns
195
+ ```
201
196
 
202
- **Q. 여러 계정을 쓰는 게 약관에 문제되지 않나요?**
203
- 본인 소유의 정당한 계정들(예: 개인 계정과 회사 계정)을 전환하는 용도로 사용하세요. 한도 우회를 목적으로 한 계정 남용은 OpenAI 이용약관에 어긋날 수 있으며, 사용에 대한 책임은 사용자에게 있습니다.
197
+ > Usage numbers are read from what codex records in its session files. Some codex versions do not record them in `exec` mode; in that case they refresh after interactive runs (`cxs run`). Without numbers, rotation still works via limit-error detection.
204
198
 
205
199
  ---
206
200
 
207
- ## 6. 데이터가 저장되는 위치
201
+ ## 4. All commands
208
202
 
209
- | 항목 | macOS/Linux | Windows |
210
- |---|---|---|
211
- | 계정 저장소 | `~/.codex-switch/` | `C:\Users\<사용자>\.codex-switch\` |
212
- | Codex 설정 | `~/.codex/` | `C:\Users\<사용자>\.codex\` |
203
+ | Command | Description |
204
+ |---|---|
205
+ | `cxs login [name]` | Log in to a new account and store it (existing login untouched; defaults to the email as the name) |
206
+ | `cxs import [name]` | Import the account currently in `~/.codex` |
207
+ | `cxs add-key <name> [key]` | Register an OpenAI API-key account (falls back to `$OPENAI_API_KEY`) |
208
+ | `cxs list` | List accounts: active marker (`*`), email, plan, priority, limit status |
209
+ | `cxs use <name>` | Switch the active account |
210
+ | `cxs current` | Show the active account |
211
+ | `cxs next` | Switch to the next account in rotation order (wraps around) |
212
+ | `cxs run [name] [args...]` | Run codex as a specific account without switching (isolated env) |
213
+ | `cxs exec [args...]` | `codex exec` + automatic rotation on usage limits — the next account resumes the same session; works outside git repos |
214
+ | `cxs exec -a <name> ...` | Start exec with a specific account (`--no-resume`: restart instead of resuming) |
215
+ | `cxs order [names...]` | Set the rotation order in one command (no args: show it) |
216
+ | `cxs model [name]` | Set the default model injected into `run`/`exec` (`default` to reset) |
217
+ | `cxs threshold [5h%] [wk%]` | Rotate to the next account when usage reaches these percents (default 95; one value sets both) |
218
+ | `cxs patterns [add/remove]` | Custom regex patterns treated as rate-limit errors |
219
+ | `cxs export <file>` | Back up all accounts + settings (⚠️ contains tokens — treat like a password) |
220
+ | `cxs restore <file>` | Restore accounts from a backup (for moving machines) |
221
+ | `cxs completion <bash\|zsh>` | Print a shell completion script |
222
+ | `cxs remove <name>` | Delete an account |
223
+ | `cxs rename <old> <new>` | Rename an account |
224
+ | `cxs disable / enable <name>` | Temporarily exclude from / restore to rotation |
225
+ | `cxs priority <name> <n>` | Change one account's priority (lower = preferred, default 0) |
226
+ | `cxs clear-limit <name>` | Manually clear a recorded rate-limit |
227
+ | `cxs cooldown [minutes]` | Show/set the default cooldown after a limit is detected (default 60) |
228
+ | `cxs sync` | Save tokens refreshed by codex back into the store |
213
229
 
214
- ```
215
- .codex-switch/
216
- ├── meta.json # 활성 계정, 우선순위, 한도 상태, 쿨다운 설정
217
- ├── accounts/<이름>.json # 계정별 인증 정보 사본 (권한 600)
218
- └── profiles/<이름>/ # run/exec용 계정별 격리 실행 환경
219
- ```
230
+ ---
220
231
 
221
- ### 환경변수로 위치 바꾸기
232
+ ## 5. FAQ / Troubleshooting
222
233
 
223
- | 변수 | 기본값 | 설명 |
224
- |---|---|---|
225
- | `CODEX_SWITCH_HOME` | `~/.codex-switch` | 계정 저장소 위치 |
226
- | `CODEX_HOME` | `~/.codex` | 관리 대상 codex 설정 디렉토리 |
227
- | `CODEX_SWITCH_CODEX_BIN` | `codex` | codex 바이너리 경로 |
234
+ **Q. `codexswitch: command not found`.**
235
+ The npm global bin directory is not on your PATH. **Close and reopen your terminal/PowerShell.** If that does not help, add the path printed by `npm config get prefix` (on macOS, its `bin` subfolder) to your PATH.
228
236
 
229
- - macOS/Linux: `export CODEX_SWITCH_HOME=/원하는/경로`
230
- - Windows PowerShell: `$env:CODEX_SWITCH_HOME = "D:\원하는\경로"` (영구 설정은 `setx CODEX_SWITCH_HOME "D:\원하는\경로"`)
237
+ **Q. `EACCES` permission error during `npm install -g` on macOS.**
238
+ Install with `sudo npm install -g @carjms/codexswitch`, or better, install Node.js via [nvm](https://github.com/nvm-sh/nvm), which avoids the permission problem entirely.
231
239
 
232
- ---
240
+ **Q. `codex CLI not found`.**
241
+ The Codex CLI is not installed or not on your PATH. Run `npm install -g @openai/codex` and try again. If it is installed somewhere unusual, point the `CODEX_SWITCH_CODEX_BIN` environment variable at the binary.
233
242
 
234
- ## 7. 설계 (어떻게 동작하나)
243
+ **Q. `Not inside a trusted directory and --skip-git-repo-check was not specified.`**
244
+ This is a Codex CLI safety check: `codex exec` refuses to run in folders that are not git repositories. **Since v0.2.0, `cxs exec` adds this flag automatically, so you should not see this error.** For interactive runs (`cxs run`), codex itself asks "do you trust this folder?" — just approve it.
235
245
 
236
- ### 핵심 아이디어 3가지
246
+ **Q. Do I lose sessions or settings when I switch accounts?**
247
+ No. Only the **credentials (auth.json)** are swapped. `config.toml`, session history, skills, etc. are shared across all accounts.
237
248
 
238
- **1. 계정 전환 = auth.json 교체 (`use`)**
239
- Codex CLI는 인증을 `auth.json` 파일 하나로 관리합니다. 저장해둔 계정별 사본을 원자적(atomic rename)으로 써넣는 것만으로 계정이 바뀌고, 설정·세션·히스토리는 그대로 유지됩니다.
249
+ **Q. Does `run`/`exec` work on Windows?**
250
+ Yes. Internally, macOS/Linux use symlinks and Windows uses directory junctions (no admin rights needed). For complete file sharing we recommend enabling Windows **Settings → Developer Mode**, but even without it, a copy-based fallback keeps everything working.
240
251
 
241
- **2. 오버레이 프로필 = 전환 없는 격리 실행 (`run` / `exec`)**
242
- Codex CLI는 `CODEX_HOME` 환경변수로 설정 디렉토리를 바꿀 수 있습니다. 계정마다 프로필 디렉토리를 만들되 `auth.json`만 실제 파일로 두고, 나머지(`config.toml`, `sessions/`, `skills/` 등)는 실제 `~/.codex`로 연결(macOS/Linux: 심볼릭 링크, Windows: 정션/복사)합니다. 설정과 세션은 공유하면서 인증만 격리되므로 서로 다른 계정으로 동시 실행이 가능합니다. (sqlite 파일은 동시 접근 시 손상 위험이 있어 공유하지 않습니다.)
252
+ **Q. I want to use a limited account again right now.**
253
+ Clear it with `cxs clear-limit <name>`.
243
254
 
244
- **3. 한도 기반 자동 로테이션 (`exec`)** — teamclaude의 핵심 개념
245
- `codex exec`의 출력을 실시간으로 흘려보내면서 동시에 수집해 `usage limit / rate limit / 429` 패턴을 감지합니다. 감지되면 해당 계정을 쿨다운 처리(에러 메시지의 "try again in N hours" 파싱, 실패 시 기본 60분)하고, 우선순위 순으로 다음 계정을 골라 같은 명령을 재시도합니다. 한도가 아닌 일반 오류는 로테이션하지 않고 그대로 종료 코드를 전달합니다.
255
+ **Q. Can account names contain non-ASCII characters (e.g. Korean)?**
256
+ Yes. Letters from any language, digits, spaces, and `@ . _ + -` are allowed.
246
257
 
247
- ### 토큰 수명 관리
258
+ **Q. Is using multiple accounts against the terms of service?**
259
+ Use this to switch between accounts you legitimately own (e.g. a personal and a work account). Abusing accounts to evade usage limits may violate OpenAI's terms of service; you are responsible for how you use it.
248
260
 
249
- codex는 실행 중 스스로 토큰을 갱신해 `auth.json`을 다시 씁니다. 갱신본이 유실되지 않도록 계정 전환 직전과 `run`/`exec` 종료 시점에 현재 auth.json을 저장소로 **sync-back**합니다 (토큰의 `account_id`로 매칭, `last_refresh`가 최신일 때만 덮어씀).
261
+ ---
250
262
 
251
- ### 보안
263
+ ## 6. Where data is stored
252
264
 
253
- - 인증 파일은 권한 `600`, 디렉토리는 `700`으로 생성 (macOS/Linux)
254
- - 토큰을 화면에 출력하지 않음 — JWT는 이메일/플랜 표시용으로만 로컬 디코딩
255
- - 네트워크 요청 없음 — 모든 인증/갱신은 codex CLI 자신이 수행
265
+ | Item | macOS/Linux | Windows |
266
+ |---|---|---|
267
+ | Account store | `~/.codex-switch/` | `C:\Users\<you>\.codex-switch\` |
268
+ | Codex config | `~/.codex/` | `C:\Users\<you>\.codex\` |
256
269
 
257
- ### teamclaude와의 차이
270
+ ```
271
+ .codex-switch/
272
+ ├── meta.json # active account, order/priorities, limit states, settings
273
+ ├── accounts/<name>.json # per-account copy of auth.json (mode 600)
274
+ └── profiles/<name>/ # per-account isolated env used by run/exec
275
+ ```
258
276
 
259
- teamclaude는 로컬 MITM 프록시로 API 트래픽을 가로채 할당량을 실시간 추적하며 요청 단위로 계정을 바꿉니다. Codex CLI는 할당량 조회를 외부에 노출하지 않으므로, codexswitch는 프록시 대신 **프로필 전환 + 출력 감지 기반의 명령 단위 로테이션**이라는 더 단순하고 안전한 방식을 택했습니다.
277
+ ### Environment variables
278
+
279
+ | Variable | Default | Description |
280
+ |---|---|---|
281
+ | `CODEX_SWITCH_HOME` | `~/.codex-switch` | Account store location |
282
+ | `CODEX_HOME` | `~/.codex` | The codex config dir codexswitch manages |
283
+ | `CODEX_SWITCH_CODEX_BIN` | `codex` | Path to the codex binary |
284
+
285
+ - macOS/Linux: `export CODEX_SWITCH_HOME=/your/path`
286
+ - Windows PowerShell: `$env:CODEX_SWITCH_HOME = "D:\your\path"` (persist with `setx`)
260
287
 
261
288
  ---
262
289
 
263
- ## 개발
290
+
291
+ ## Development
264
292
 
265
293
  ```bash
266
294
  git clone https://github.com/JIMyungSik/codexswitch.git
267
295
  cd codexswitch
268
- npm link # 로컬 개발 버전을 전역 명령으로 연결
269
- npm test # 가짜 codex 바이너리로 전체 흐름 검증 (실제 ~/.codex는 건드리지 않음)
296
+ npm link # link the local dev version as a global command
297
+ npm test # full-flow test against a fake codex binary (never touches your real ~/.codex)
270
298
  ```
271
299
 
272
- ## 라이선스
300
+ ## License
273
301
 
274
302
  MIT
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@carjms/codexswitch",
3
- "version": "0.1.0",
3
+ "version": "0.3.0",
4
4
  "description": "Multi-account manager for OpenAI Codex CLI with quota-based rotation (inspired by KarpelesLab/teamclaude)",
5
5
  "license": "MIT",
6
6
  "repository": {