codexmu 0.1.0 → 0.2.0

package/README.ko.md

@@ -12,7 +12,7 @@ Codex의 여러 ChatGPT 계정을 저장하고, 사용 한도에 도달하면
 
 Node.js **24 이상**과 공식 Codex가 필요합니다. npm 패키지는 macOS / Linux의 ARM64·x64 실행 파일을 포함하며, 설치 시 Rust 빌드나 별도 바이너리 다운로드를 하지 않습니다.
 
-공개 npm 배포 후에는 다음 명령으로 설치합니다. **현재 저장소에 배포 구성을 추가한 상태이며, 공개 레지스트리 게시 여부는 별도로 확인해야 합니다.**
+공개 npm 레지스트리에서 설치합니다:
 
 ```sh
 npm install -g codexmu
@@ -58,7 +58,7 @@ codexmu list --live
 codexmu
 ```
 
-등록된 모든 계정이 자동 전환 후보가 됩니다. 예를 들어 `personal`과 `work`가 차례로 한도에 걸리면 사용 가능한 `extra`로 전환해 같은 대화를 이어갑니다. 전환 순서는 등록 순서가 아니라 남은 사용량에 따라 결정합니다.
+등록된 모든 계정이 자동 전환 후보가 됩니다. 예를 들어 `personal`과 `work`가 차례로 한도에 걸리면 사용 가능한 `extra`로 전환해 같은 대화를 이어갑니다. 전환 순서는 등록 순서가 아니라 남은 사용량에 따라 결정합니다. 특정 계정을 먼저 쓰려면 `codexmu priority NAME 1`로 높은 등급을 주세요. 사용량은 같은 등급 안에서만 비교하며, 위 등급의 계정이 모두 사용 불가능할 때만 아래 등급을 사용합니다. `codexmu priority personal -1`은 `personal`을 예비 계정으로 남깁니다. 등급은 전환할 때 목적지를 정할 뿐이며, 활성 계정에 여유가 남아 있는 동안 상위 등급으로 되돌아가지는 않습니다.
 
 `login`은 임시 `CODEX_HOME`에서 공식 `codex login`을 실행합니다. 로그인 취소·실패 시 기존 활성 계정은 그대로 유지됩니다. 브라우저 로그인을 쓰려면 `--device-auth`를 생략하세요. 키체인에만 저장되어 `auth.json`이 없다면 `add` 대신 `login`을 사용하세요.
 
@@ -75,20 +75,18 @@ codexmu remove unused
 
 계정을 등록한 뒤 **`codexmu`만 실행하면 공식 Codex 터미널 화면으로 바로 들어갑니다.** 한도 오류가 발생하면 다른 등록 계정으로 전환하고 같은 대화에서 작업을 자동으로 이어갑니다.
 
-`codext`의 미리보기처럼 입력창 바로 위에 색상 상태 헤더를 표시합니다.
+입력창 아래 공식 status line에 codexmu 색상 구간을 합쳐 한 줄로 표시하고, 그 줄을 화면 맨 아래에 고정합니다.
 
 ![codexmu 터미널 미리보기](docs/terminal-preview.png)
 
-위 이미지는 로컬 가짜 계정으로 검증한 실제 PTY 출력을 터미널 에뮬레이터에서 재생한 모습입니다.
+위 이미지는 로컬 가짜 계정으로 실행한 화면을 Terminal.app에서 캡처한 것입니다.
 
 ```text
-codexmu │ gpt-5.1 medium │ …/codexmu │ main +2 │ 5h 85% · 0h42m │ user@example.com (plus)
-
 › 프로젝트를 설명해 줘
-  Context 100% left · Fast off · 5h 85% · weekly 58% · 0.153.4
+ codexmu │ gpt-5.1 medium │ …/codexmu │ main +2 │ 5h 85% · 0h42m │ user@example.com (plus)   Context 100% left · Fast off · 5h 85% · weekly 58% · 0.153.4
 ```
 
-표시되는 값은 현재 세션의 모델·추론 강도·작업 경로, Git 브랜치와 변경 수, 실제 조회한 남은 사용량, 활성 계정의 이메일·플랜입니다. 헤더의 시간은 한도 초기화까지 남은 시간입니다. 계정 전환이 서버에서 승인되면 헤더도 새 계정으로 바뀌고 전환 알림을 잠시 표시합니다. 조회되지 않은 한도는 `—`로 표시하며, 좁은 창에서는 경로·Git 표시를 줄입니다. 배경·글꼴은 사용하는 터미널 설정을 따릅니다.
+표시되는 값은 현재 세션의 모델·추론 강도·작업 경로, Git 브랜치와 변경 수, 실제 조회한 남은 사용량, 활성 계정의 이메일·플랜입니다. 상태 줄의 시간은 한도 초기화까지 남은 시간입니다. 계정 전환이 서버에서 승인되면 상태 줄도 새 계정으로 바뀌고 전환 알림 구간을 잠시 표시합니다. 조회되지 않은 한도는 `—`로 표시하며, 좁은 창에서는 경로·Git 표시를 줄입니다. 마우스 휠과 PageUp/PageDown으로 Codex 출력만 스크롤되고 상태 줄은 그대로 남으며, 다른 키를 누르면 현재 화면으로 돌아옵니다. codexmu는 마우스를 가로채지 않으므로 텍스트 선택·복사·Cmd+클릭은 터미널 기본 동작 그대로입니다(휠 스크롤은 Terminal.app, iTerm2, kitty, Ghostty, WezTerm이 기본으로 켜 두는 alternate scroll 동작을 이용합니다). 배경·글꼴은 사용하는 터미널 설정을 따릅니다.
 
 ```sh
 codexmu
@@ -96,7 +94,7 @@ codexmu "이 프로젝트를 설명해 줘"
 codexmu run -- --model gpt-5.1
 codexmu run -- resume --last
 
-# 상태 헤더 없이 원래 공식 Codex 화면 사용
+# 상태 줄 없이 원래 공식 Codex 화면 사용
 codexmu --plain
 ```
 
@@ -106,7 +104,7 @@ codexmu --plain
 
 새 홈에서 공식 Codex의 SQLite 초기화가 충돌하지 않도록 서버 시작부터 초기화 응답까지는 별도 시작 잠금으로 순서를 맞춥니다. 초기화 응답을 받으면 즉시 해제하여 여러 세션이 함께 작업할 수 있습니다.
 
-공식 Codex의 `--remote unix://...` 기능을 이용합니다. 이 기능을 지원하는 Codex가 필요하며 CLI 0.153.4에서 검증했습니다. 임시 전용 Unix 소켓으로 기존 터미널 UI와 인증 전환 브리지를 연결하고, PTY 화면에 상태 헤더를 합성합니다. 종료 시 소켓을 제거하고 터미널 설정을 복구합니다. TCP 포트를 열지 않습니다. 긴 대화는 공식 Codex의 `Ctrl+T` 화면에서 확인할 수 있습니다. 터미널 고유의 키보드·스크롤 동작이 필요하면 `--plain`을 사용하세요.
+공식 Codex의 `--remote unix://...` 기능을 이용합니다. 이 기능을 지원하는 Codex가 필요하며 CLI 0.153.4에서 검증했습니다. 임시 전용 Unix 소켓으로 기존 터미널 UI와 인증 전환 브리지를 연결하고, PTY 화면을 별도 화면(alternate screen)에 자체 스크롤백과 함께 합성하므로 Codex 출력을 스크롤해도 상태 줄이 고정됩니다. 종료 시 소켓을 제거하고 터미널 설정을 복구합니다. TCP 포트를 열지 않습니다. 터미널 고유의 스크롤백이 필요하면 `--plain`을 사용하세요.
 
 Codex 옵션은 `run --` 뒤에 전달하면 관리 명령·옵션과 혼동하지 않습니다. `--remote` 연결 주소는 codexmu가 관리합니다. 자동 재개를 끄려면 `codexmu --no-resume`을 실행하세요.
 
@@ -130,7 +128,8 @@ codexmu --codex-bin /absolute/path/to/codex app
 
 - 기본 60초마다 **턴이 실행 중이지 않을 때** 사용량을 조회합니다.
 - `usageLimitExceeded`로 턴이 끝나면 다음 주기를 기다리지 않고 다른 계정을 찾습니다.
-- 사용 가능한 계정 중 응답에 포함된 사용량 창의 최대 사용률이 가장 낮은 계정을 선택합니다.
+- 가장 높은 우선순위 등급의 사용 가능한 계정 중 응답에 포함된 사용량 창의 최대 사용률이 가장 낮은 계정을 선택합니다.
+- `--switch-at 80`을 주면 활성 계정이 80%에 도달하고 80% 미만인 계정이 있을 때 턴 사이에 미리 전환합니다. 선제 전환은 제외 시간을 두지 않고 계속 진행 턴도 보내지 않습니다.
 - 새 인증은 `account/login/start`로 실행 중인 공식 app-server에 전달합니다. 파일만 교체하고 끝내지 않습니다.
 - 기본적으로 같은 스레드에 계속 진행하라는 새 턴을 보냅니다. 원래 프롬프트나 실행한 도구 호출을 재전송하지 않습니다.
 - 다른 턴이 실행 중이면 전환을 미룹니다. 전환 중 들어온 새 턴은 잠시 대기하고, 승인 응답은 계속 전달합니다. 취소된 대기 턴은 실행하지 않습니다.
@@ -168,7 +167,7 @@ codexmu app-server -- --stdio
 
 ```text
 $CODEX_HOME/auth.json                       활성 Codex 인증
-$CODEX_HOME/codexmu/accounts/<name>.json     계정별 인증·일시 제외 시각
+$CODEX_HOME/codexmu/accounts/<name>.json     계정별 인증·우선순위·일시 제외 시각
 $CODEX_HOME/codexmu/previous-auth.json       직전 활성 인증 백업
 $CODEX_HOME/codexmu/pending-refresh.json     중단된 OAuth 갱신 복구용 임시 기록
 $CODEX_HOME/codexmu/terminal-<PID>.log       세션별 공식 서버 진단 로그
@@ -182,8 +181,9 @@ $CODEX_HOME/codexmu/terminal-<PID>.log       세션별 공식 서버 진단 로
 | `--codex-bin` | `CODEXMU_CODEX_BIN` | `codex` |
 | `--interval` | `CODEXMU_INTERVAL` | 60초, 최소 5초 |
 | `--no-resume` | `CODEXMU_NO_RESUME` | false |
+| `--switch-at` | `CODEXMU_SWITCH_AT` | 100 (한도 도달 시에만 전환); 1–100 |
 
-사용량 요청 실패·유효한 사용량 창이 없는 응답·이미 지난 리셋 시각을 여유 계정의 증거로 사용하지 않습니다. 한도에 도달한 계정은 최소 60초 동안 후보에서 제외됩니다. `--dry-run`은 계정 전환을 하지 않지만 정상 인증 유지에 필요한 OAuth 갱신은 할 수 있습니다.
+사용량 요청 실패·유효한 사용량 창이 없는 응답·이미 지난 리셋 시각을 여유 계정의 증거로 사용하지 않습니다. 한도에 도달한 계정은 최소 60초 동안, `usageLimitExceeded` 오류를 받은 계정은 사용량 보고에 여유가 있어 보여도 다음 리셋 시각까지 후보에서 제외됩니다. `--dry-run`은 계정 전환을 하지 않지만 정상 인증 유지에 필요한 OAuth 갱신은 할 수 있습니다.
 
 ## 검증
 
@@ -216,7 +216,7 @@ python3 tests/terminal.py --codex-bin "$(command -v codex)" --sessions 3 --resiz
 
 `package.json`과 `Cargo.toml`의 버전을 함께 변경하세요. GitHub 저장소에 코드를 올린 뒤 Actions의 **npm release → Run workflow**를 실행하면 네 플랫폼의 바이너리를 빌드·검증하고 `npm-package` 아티팩트에 설치 가능한 `.tgz`를 만듭니다. Linux는 musl 타깃으로 빌드합니다.
 
-공개 게시하려면 해당 npm 패키지에 게시 권한이 있는 토큰을 저장소의 Actions secret **`NPM_TOKEN`**에 등록하고, 워크플로의 **publish**를 선택하세요. 패키지 이름을 바꾸려면 `package.json`의 `name`을 변경하면 됩니다. 워크플로는 네 플랫폼의 빌드와 검증이 모두 성공한 뒤 패키지를 게시합니다.
+게시하려면 `npm-package` 아티팩트를 내려받고, `npm login`한 머신에서 `npm publish ./codexmu-<version>.tgz --access public`을 실행하세요. npm은 게시 계정에 2단계 인증(2FA)을 요구하며, 명령 실행 시 브라우저 승인 단계가 열립니다. CI에서 게시하려면 granular npm 토큰을 저장소의 Actions secret **`NPM_TOKEN`**에 등록하고 워크플로의 **publish**를 선택하세요. 패키지 이름을 바꾸려면 `package.json`의 `name`을 변경하면 됩니다. 워크플로는 네 플랫폼의 빌드와 검증이 모두 성공한 뒤 패키지를 게시합니다.
 
 로컬 `npm publish`도 네 플랫폼 실행 파일이 모두 있는지 먼저 확인합니다. `npm pack`은 현재 플랫폼만으로 허용하므로 로컬 설치 테스트에 사용할 수 있습니다. 이 로컬 전용 `.tgz`를 공개 게시하지 마세요. 의존 npm 패키지와 설치 스크립트는 없습니다.
 

package/README.md

@@ -12,7 +12,7 @@ A Rust program that stores multiple ChatGPT accounts for Codex and automatically
 
 Requires **Node.js 24 or later** and official Codex. The release package bundles macOS / Linux binaries for ARM64 and x64, without a Rust build or separate binary download during installation.
 
-After publication to npm, install with the following commands. **This repository contains the release configuration; public registry publication must be checked separately.**
+Install from the public npm registry:
 
 ```sh
 npm install -g codexmu
@@ -58,7 +58,7 @@ codexmu list --live
 codexmu
 ```
 
-All registered accounts are candidates for automatic switching. For example, if `personal` and then `work` reach their limits, codexmu can switch to an available `extra` account and continue the same conversation. Selection depends on remaining usage, not registration order.
+All registered accounts are candidates for automatic switching. For example, if `personal` and then `work` reach their limits, codexmu can switch to an available `extra` account and continue the same conversation. Selection depends on remaining usage, not registration order. To prefer some accounts, give them a higher tier with `codexmu priority NAME 1`; usage decides only within a tier, and lower tiers are used once every account above them is unavailable. `codexmu priority personal -1` keeps `personal` as the reserve. Tiers decide where a switch goes; codexmu does not move back to a higher tier while the active account still has headroom.
 
 `login` runs official `codex login` in a temporary `CODEX_HOME`. Cancelling or failing login preserves the existing active account. Omit `--device-auth` for browser login. If your credentials exist only in the keychain and there is no `auth.json`, use `login` instead of `add`.
 
@@ -75,20 +75,18 @@ Duplicate accounts, overwriting an existing name, and deleting the active accoun
 
 After registering accounts, **run `codexmu` to open the official Codex terminal UI.** When a usage-limit error occurs, it switches to another registered account and automatically continues work in the same conversation.
 
-A colored status header appears just above the input area, inspired by the `codext` preview:
+codexmu merges its own colored segments into the official status line below the input area and pins that line to the bottom row:
 
 ![codexmu terminal preview](docs/terminal-preview.png)
 
-The image replays actual PTY output from a local fake-account test in a terminal emulator.
+The image is a Terminal.app capture of a local fake-account run.
 
 ```text
-codexmu │ gpt-5.1 medium │ …/codexmu │ main +2 │ 5h 85% · 0h42m │ user@example.com (plus)
-
 › Explain this project
-  Context 100% left · Fast off · 5h 85% · weekly 58% · 0.153.4
+ codexmu │ gpt-5.1 medium │ …/codexmu │ main +2 │ 5h 85% · 0h42m │ user@example.com (plus)   Context 100% left · Fast off · 5h 85% · weekly 58% · 0.153.4
 ```
 
-The header shows the session model, reasoning effort, working directory, Git branch and change count, queried remaining usage, and active account email and plan. The time is the countdown to the usage reset. Once the server acknowledges an account switch, the header updates and briefly shows a notification. Unavailable quota data appears as `—`; narrow windows shorten or hide path and Git details. Your terminal controls the background and font.
+The status line shows the session model, reasoning effort, working directory, Git branch and change count, queried remaining usage, and active account email and plan. The time is the countdown to the usage reset. Once the server acknowledges an account switch, the status line updates and briefly shows a switch notice segment. Unavailable quota data appears as `—`; narrow windows shorten or hide path, Git, and native details. The mouse wheel and PageUp/PageDown scroll the Codex output while the status line stays in place; any other key jumps back to the live view. codexmu never captures the mouse, so selecting text, copying, and Cmd+click keep working exactly as in your terminal (wheel scrolling relies on the alternate-scroll behavior that Terminal.app, iTerm2, kitty, Ghostty, and WezTerm enable by default). Your terminal controls the background and font.
 
 ```sh
 codexmu
@@ -96,7 +94,7 @@ codexmu "Explain this project"
 codexmu run -- --model gpt-5.1
 codexmu run -- resume --last
 
-# Use the original official Codex layout without the status header
+# Use the original official Codex layout without the status line
 codexmu --plain
 ```
 
@@ -106,7 +104,7 @@ Account-store access, usage queries, and OAuth refresh are serialized by a store
 
 A separate startup lock serializes server startup through the initialization response to avoid official Codex SQLite initialization conflicts in a fresh home. It releases immediately after initialization so sessions can work concurrently.
 
-codexmu uses official Codex's `--remote unix://...` feature, verified with CLI 0.153.4. A private temporary Unix socket connects the native terminal UI to the authentication bridge, and the status header is composed over the PTY display. On exit, codexmu removes the socket and restores terminal settings. It opens no TCP port. Use official Codex's `Ctrl+T` view for long conversations, or `--plain` when you need the native terminal keyboard and scrolling behavior.
+codexmu uses official Codex's `--remote unix://...` feature, verified with CLI 0.153.4. A private temporary Unix socket connects the native terminal UI to the authentication bridge, and codexmu composes the PTY display on an alternate screen with its own scrollback, so the status line stays pinned while you scroll the Codex output. On exit, codexmu removes the socket and restores terminal settings. It opens no TCP port. Use `--plain` when you need the terminal's native scrollback instead.
 
 Pass Codex options after `run --` to avoid confusion with management commands and options. codexmu manages the `--remote` address. Use `codexmu --no-resume` to disable automatic continuation.
 
@@ -130,7 +128,8 @@ Terminal and desktop modes share the same switching behavior:
 
 - Query usage every 60 seconds by default, **only when no turn is running**.
 - Look for another account immediately when a turn ends with `usageLimitExceeded`.
-- Among available accounts, select the one with the lowest maximum usage across the usage windows present in the response.
+- Among available accounts in the highest priority tier, select the one with the lowest maximum usage across the usage windows present in the response.
+- With `--switch-at 80`, also switch between turns once the active account reaches 80% and an account below 80% exists. An early switch is not a cooldown and sends no continuation turn.
 - Send new credentials to the running official app-server through `account/login/start`, rather than only replacing a file.
 - By default, send a new continuation turn in the same thread. Do not replay the original prompt or executed tool calls.
 - Defer switching while another turn is running. Queue new turns during a switch while continuing to forward approval responses. Do not execute cancelled queued turns.
@@ -168,7 +167,7 @@ You do not need a separate `codexmu watch` when running `codexmu`. A duplicate `
 
 ```text
 $CODEX_HOME/auth.json                       Active Codex authentication
-$CODEX_HOME/codexmu/accounts/<name>.json     Account credentials and temporary exclusion time
+$CODEX_HOME/codexmu/accounts/<name>.json     Account credentials, priority, and temporary exclusion time
 $CODEX_HOME/codexmu/previous-auth.json       Previous active authentication backup
 $CODEX_HOME/codexmu/pending-refresh.json     Interrupted OAuth refresh recovery journal
 $CODEX_HOME/codexmu/terminal-<PID>.log        Per-session official server diagnostics
@@ -182,8 +181,9 @@ $CODEX_HOME/codexmu/terminal-<PID>.log        Per-session official server diagno
 | `--codex-bin` | `CODEXMU_CODEX_BIN` | `codex` |
 | `--interval` | `CODEXMU_INTERVAL` | 60 seconds; minimum 5 |
 | `--no-resume` | `CODEXMU_NO_RESUME` | false |
+| `--switch-at` | `CODEXMU_SWITCH_AT` | 100 (switch only at the limit); 1–100 |
 
-Failed usage requests, responses without a valid usage window, and past reset timestamps are not treated as evidence of available quota. Accounts that reach their limits are excluded from selection for at least 60 seconds. `--dry-run` does not switch accounts, but may refresh OAuth tokens to keep credentials valid.
+Failed usage requests, responses without a valid usage window, and past reset timestamps are not treated as evidence of available quota. Accounts that reach their limits are excluded from selection for at least 60 seconds, and after a `usageLimitExceeded` error until the next reported usage reset, even if the usage report still shows headroom. `--dry-run` does not switch accounts, but may refresh OAuth tokens to keep credentials valid.
 
 ## Validation
 
@@ -216,7 +216,7 @@ See [AGENTS.md](AGENTS.md) for the code layout, authentication and concurrency i
 
 Update the versions in `package.json` and `Cargo.toml` together. After pushing the code to GitHub, select **npm release → Run workflow** in Actions to build and check all four platforms and create an installable `.tgz` in the `npm-package` artifact. Linux builds use musl targets.
 
-To publish publicly, add a token with permission to publish the npm package as the repository's **`NPM_TOKEN`** Actions secret and select **publish** in the workflow. Change `name` in `package.json` to rename the package. The workflow publishes only after builds and checks succeed for all four platforms.
+To publish, download the `npm-package` artifact and run `npm publish ./codexmu-<version>.tgz --access public` from a machine logged in with `npm login`. npm requires two-factor authentication on the publishing account; the command opens a browser approval step. Alternatively, add a granular npm token as the repository's **`NPM_TOKEN`** Actions secret and select **publish** in the workflow to publish from CI. Change `name` in `package.json` to rename the package. The workflow publishes only after builds and checks succeed for all four platforms.
 
 Local `npm publish` also checks that executables for all four platforms are present. `npm pack` permits a current-platform-only package for local installation tests; do not publish that local-only `.tgz` publicly. There are no npm dependencies or installation scripts.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "codexmu",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Multi-account manager and automatic account switching for Codex",
   "license": "MIT",
   "type": "module",