@wangxt0223/codex-switcher 0.4.0

package/CHANGELOG.md

@@ -0,0 +1,38 @@
+# Changelog
+
+## 0.4.0 - 2026-04-12
+
+- Changed npm package name to `@wangxt0223/codex-switcher` (CLI command remains `codex-sw`).
+- Updated `upgrade` implementation to install the scoped package by default.
+- Added `CODEX_SWITCHER_NPM_PACKAGE` env override for custom package source.
+- Updated README/docs to reflect new package install/publish references.
+
+## 0.3.2 - 2026-04-12
+
+- Added built-in self-upgrade command: `codex-sw upgrade` (supports `--dry-run`).
+- Updated `--help` and README/docs to include upgrade usage.
+
+## 0.3.1 - 2026-04-12
+
+- Added strict App profile guard: `app open/use` now requires existing and logged-in profile.
+- Added `import-default` to migrate data from `~/.codex` into a profile.
+- Added `--sync|--no-sync` for `login`, `use`, and `switch` with overwrite sync (excluding `auth.json`).
+- Updated `--help` and README docs for sync and migration workflows.
+
+## 0.3.0 - 2026-04-12
+
+- Added `codex-sw` namespaced entrypoint (kept `codex-switcher` compatibility).
+- Added concurrency lock to protect profile pointer mutations.
+- Added safer App lifecycle handling with managed PID tracking.
+- Added status exit code conventions (`0/1/2`).
+- Added pointer recovery command: `codex-sw recover`.
+- Added init/bootstrap command: `codex-sw init`.
+- Added doctor auto-fix mode: `codex-sw doctor --fix`.
+- Added log redaction scanner in `check` / `doctor`.
+- Added install/uninstall scripts and CI workflow.
+- Added expanded smoke tests.
+- Added npm release helper: `npm run release:npm`.
+- Added `publishConfig` (public + npmjs registry) and publish guide docs.
+- Added `import-default` command to migrate existing `~/.codex` data into a profile.
+- Changed `app open/use` to require existing and logged-in profile (no silent auto-create).
+- Added `login --sync` and `use/switch --sync` overwrite sync (all files except `auth.json`).

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 wangxt
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.en.md

@@ -0,0 +1,91 @@
+# codex-sw
+
+[中文](README.md) | English
+
+`codex-sw` is a lightweight profile switcher for Codex CLI and Codex App.
+It isolates accounts by running each profile in its own `CODEX_HOME` directory.
+
+## Background
+
+I originally used Codex for personal work while my company account lived in Cursor, so there was no conflict.  
+After the company migrated from Cursor to Codex, my personal and company Codex accounts started conflicting on the same machine, and switching became unreliable.
+
+After inspecting local behavior, I found Codex's local auth model is straightforward: if account-local data is isolated per directory, account switching becomes stable. Based on that, I built `codex-sw` with Codex to manage, switch, and isolate all my Codex accounts.
+
+## Codex Local Auth Model (Summary)
+
+The following is based on observed local behavior and filesystem layout:
+
+- Both `Codex CLI` and `Codex App` read the same root directory: `CODEX_HOME` (default is usually `~/.codex`).
+- Auth state is primarily persisted in `CODEX_HOME/auth.json`.
+- Session/history/state data is also stored under the same `CODEX_HOME` (for example `history.jsonl`, `sessions/`, `state_*.sqlite`).
+- So when multiple accounts share one `CODEX_HOME`, auth/session data can overwrite or contaminate each other.
+
+`codex-sw` solves this by assigning each account its own `CODEX_HOME` (`~/.codex-profiles/<profile>`) and switching that directory for CLI/App operations.
+
+## Install
+
+### Option A: npm (global)
+
+```bash
+npm i -g @wangxt0223/codex-switcher
+codex-sw check
+```
+
+### Option B: from source checkout
+
+```bash
+./scripts/install.sh
+codex-sw check
+```
+
+## Quick start
+
+```bash
+codex-sw add work
+codex-sw add personal
+
+codex-sw use work --sync
+codex-sw login --sync
+codex-sw exec -- login status
+
+codex-sw switch personal --sync
+codex-sw app use personal
+```
+
+## Sync options
+
+- `login --sync`: sync `~/.codex` into the target profile (excluding `auth.json`).
+- `use/switch --sync`: sync current CLI profile into target profile (excluding `auth.json`).
+- `--no-sync`: keep strict isolation without data copy (default).
+
+## Command reference
+
+See plugin guide:
+- Chinese: `plugins/codex-switcher/README.md`
+- English: `plugins/codex-switcher/README.en.md`
+
+## Development
+
+```bash
+npm run check
+```
+
+## Publish to npm
+
+```bash
+npm login --registry https://registry.npmjs.org/
+npm run release:npm
+```
+
+## Upgrade
+
+```bash
+codex-sw upgrade
+```
+
+## Docs
+
+- `docs/macos-manual-checklist.md`
+- `docs/upgrade.md`
+- `docs/publish.md`

package/README.md

@@ -0,0 +1,92 @@
+# codex-sw
+
+中文 | [English](README.en.md)
+
+`codex-sw` 是一个面向 Codex CLI 与 Codex App 的轻量账号切换工具。
+它通过为每个 profile 使用独立的 `CODEX_HOME` 目录实现账号隔离。
+
+## 项目背景
+
+最早我自己一直在用 Codex，公司配的是 Cursor，所以在我的电脑上两套账号互不影响。  
+后来公司从 Cursor 切到 Codex 后，我就得在同一台电脑上同时用个人账号和公司账号，很快就遇到冲突：登录态会互相覆盖，切换也不顺手。
+
+为了搞清楚原因，我看了下 Codex 的本地数据机制，发现思路其实很直接：只要把不同账号对应的本地目录隔离开，就能稳定切换。  
+基于这个思路，我用 Codex 写了 `codex-sw`，专门用来管理、切换和隔离我所有的 Codex 账号，现在日常在个人/公司账号之间切换方便很多。
+
+## Codex 本地认证机制（简述）
+
+以下是基于本地行为和目录结构观察到的机制：
+
+- `Codex CLI` 与 `Codex App` 都会读取同一个工作目录根：`CODEX_HOME`（默认通常是 `~/.codex`）。
+- 账号认证状态主要保存在 `CODEX_HOME/auth.json`。
+- 会话、历史、索引和状态等数据也会写在同一 `CODEX_HOME` 下（如 `history.jsonl`、`sessions/`、`state_*.sqlite` 等）。
+- 因此当多个账号共享同一个 `CODEX_HOME` 时，最容易出现“登录态互相覆盖/污染”的问题。
+
+`codex-sw` 的做法就是为每个账号分配独立 `CODEX_HOME`（`~/.codex-profiles/<profile>`），并在执行命令或启动 App 时切换到对应目录，从而实现账号隔离与可控切换。
+
+## 安装
+
+### 方式 A：npm 全局安装
+
+```bash
+npm i -g @wangxt0223/codex-switcher
+codex-sw check
+```
+
+### 方式 B：源码安装
+
+```bash
+./scripts/install.sh
+codex-sw check
+```
+
+## 快速开始
+
+```bash
+codex-sw add work
+codex-sw add personal
+
+codex-sw use work --sync
+codex-sw login --sync
+codex-sw exec -- login status
+
+codex-sw switch personal --sync
+codex-sw app use personal
+```
+
+## 同步选项
+
+- `login --sync`：将 `~/.codex` 同步到目标 profile（不包含 `auth.json`）。
+- `use/switch --sync`：将当前 CLI profile 同步到目标 profile（不包含 `auth.json`）。
+- `--no-sync`：不进行数据同步（默认）。
+
+## 命令参考
+
+详见插件文档：
+- 中文：`plugins/codex-switcher/README.md`
+- English: `plugins/codex-switcher/README.en.md`
+
+## 开发
+
+```bash
+npm run check
+```
+
+## 发布到 npm
+
+```bash
+npm login --registry https://registry.npmjs.org/
+npm run release:npm
+```
+
+## 升级
+
+```bash
+codex-sw upgrade
+```
+
+## 文档
+
+- `docs/macos-manual-checklist.md`
+- `docs/upgrade.md`
+- `docs/publish.md`

package/docs/macos-manual-checklist.md

@@ -0,0 +1,34 @@
+# macOS Manual Checklist
+
+Run this checklist on a macOS machine with Codex.app installed.
+
+## Setup
+
+- [ ] `codex-sw check` returns `check: ok`
+- [ ] `codex-sw add work` and `codex-sw add personal` succeed
+
+## CLI isolation
+
+- [ ] `codex-sw use work && codex-sw login`
+- [ ] `codex-sw use personal && codex-sw login`
+- [ ] `codex-sw status` shows both profiles logged in when selected as current
+
+## App switching
+
+- [ ] `codex-sw app use work` opens App
+- [ ] `codex-sw app current` prints `work`
+- [ ] `codex-sw app use personal` restarts App under `personal`
+- [ ] `codex-sw app status` reports running when app is open
+- [ ] `codex-sw app stop` stops managed app process
+
+## Recovery and integrity
+
+- [ ] Corrupt pointer file manually and run `codex-sw recover`
+- [ ] `codex-sw doctor --fix` completes successfully
+- [ ] `codex-sw check` passes after recovery
+
+## Security checks
+
+- [ ] `~/.codex-switcher` permission is `700`
+- [ ] `~/.codex-profiles` permission is `700`
+- [ ] no tokens are visible in `~/.codex-switcher/switcher.log`

package/docs/publish.md

@@ -0,0 +1,41 @@
+# npm Publish Guide
+
+This project publishes to npm as:
+
+- package: `@wangxt0223/codex-switcher`
+- command: `codex-sw`
+
+## One-command publish
+
+```bash
+npm login --registry https://registry.npmjs.org/
+npm run release:npm
+```
+
+`release:npm` runs:
+
+1. `npm run check`
+2. `npm pack --dry-run`
+3. login check (`npm whoami --registry ...`)
+4. `npm publish --access public --registry ...`
+
+## Mirror registry note
+
+If your default npm registry is a mirror (for example `https://registry.npmmirror.com`), publishing may fail unless you authenticate against that mirror.
+
+This project forces publish target to npmjs using:
+
+- `package.json` -> `publishConfig.registry = https://registry.npmjs.org/`
+- `scripts/publish-npm.sh` -> `--registry https://registry.npmjs.org/`
+
+## Optional: use a custom registry explicitly
+
+```bash
+NPM_REGISTRY=https://registry.npmjs.org/ npm run release:npm
+```
+
+## Verify publish
+
+```bash
+npm view @wangxt0223/codex-switcher version dist-tags --registry https://registry.npmjs.org/
+```

package/docs/upgrade.md

@@ -0,0 +1,31 @@
+# Upgrade Guide
+
+## Source install users
+
+```bash
+git pull
+./scripts/install.sh
+codex-sw check
+```
+
+## npm users
+
+```bash
+codex-sw upgrade
+codex-sw check
+```
+
+## Breaking behavior notes
+
+- `codex-sw` is the preferred command namespace.
+- `codex-switcher` remains available for compatibility.
+- `codex-sw app stop` now targets only managed App processes launched by `codex-sw`.
+
+## Recovery
+
+If pointers are corrupted or profile directories are missing:
+
+```bash
+codex-sw recover
+codex-sw status
+```

package/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "@wangxt0223/codex-switcher",
+  "version": "0.4.0",
+  "description": "Profile-based account switcher for Codex CLI and Codex App using isolated CODEX_HOME directories.",
+  "license": "MIT",
+  "author": "wangxt",
+  "homepage": "https://github.com/wangxt/codex-switcher",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/wangxt/codex-switcher.git"
+  },
+  "keywords": [
+    "codex",
+    "codex-cli",
+    "account-switch",
+    "profile",
+    "codex-home"
+  ],
+  "bin": {
+    "codex-sw": "plugins/codex-switcher/scripts/codex-sw",
+    "codex-switcher": "plugins/codex-switcher/scripts/codex-switcher"
+  },
+  "files": [
+    "plugins/codex-switcher/**",
+    "docs/**",
+    "scripts/install.sh",
+    "scripts/uninstall.sh",
+    "CHANGELOG.md",
+    "LICENSE",
+    "README.md"
+  ],
+  "scripts": {
+    "lint": "bash -n plugins/codex-switcher/scripts/codex-switcher && bash -n plugins/codex-switcher/scripts/codex-sw",
+    "test": "plugins/codex-switcher/scripts/test-switcher.sh",
+    "check": "npm run lint && npm run test",
+    "prepublishOnly": "npm run check",
+    "release:npm": "./scripts/publish-npm.sh"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  }
+}

package/plugins/codex-switcher/.app.json

@@ -0,0 +1,3 @@
+{
+  "apps": []
+}

package/plugins/codex-switcher/.codex-plugin/plugin.json

@@ -0,0 +1,48 @@
+{
+  "name": "codex-switcher",
+  "version": "0.4.0",
+  "description": "Profile-based account switcher for Codex CLI and Codex App without modifying upstream source.",
+  "author": {
+    "name": "wangxt",
+    "email": "noreply@example.com",
+    "url": "https://github.com/wangxt"
+  },
+  "homepage": "https://github.com/wangxt/codex-switcher",
+  "repository": "https://github.com/wangxt/codex-switcher",
+  "license": "MIT",
+  "keywords": [
+    "codex",
+    "account-switching",
+    "profiles",
+    "codex-home"
+  ],
+  "skills": "./skills/",
+  "hooks": "./hooks.json",
+  "mcpServers": "./.mcp.json",
+  "apps": "./.app.json",
+  "interface": {
+    "displayName": "Codex Switcher",
+    "shortDescription": "Manage Codex App/CLI accounts via CODEX_HOME profiles.",
+    "longDescription": "Use isolated profile directories for Codex CLI and restart Codex App into a selected profile without patching Codex source code.",
+    "developerName": "wangxt",
+    "category": "Productivity",
+    "capabilities": [
+      "Shell Automation",
+      "Account Profile Switching"
+    ],
+    "websiteURL": "https://github.com/wangxt/codex-switcher",
+    "privacyPolicyURL": "https://openai.com/policies/row-privacy-policy/",
+    "termsOfServiceURL": "https://openai.com/policies/row-terms-of-use/",
+    "defaultPrompt": [
+      "Create a new Codex profile for my work account.",
+      "Switch Codex CLI to the personal profile.",
+      "Restart Codex App with the selected account profile."
+    ],
+    "brandColor": "#2563EB",
+    "composerIcon": "./assets/icon.png",
+    "logo": "./assets/logo.png",
+    "screenshots": [
+      "./assets/screenshot1.png"
+    ]
+  }
+}

package/plugins/codex-switcher/.mcp.json

@@ -0,0 +1,3 @@
+{
+  "mcpServers": {}
+}

package/plugins/codex-switcher/README.en.md

@@ -0,0 +1,112 @@
+# codex-sw
+
+[中文](README.md) | English
+
+Profile-based account switcher for Codex CLI and Codex App.
+
+## Core idea
+
+- One profile = one isolated `CODEX_HOME` directory: `~/.codex-profiles/<profile>`
+- CLI commands run under selected CLI profile
+- App is restarted under selected App profile
+- Current pointers are stored in `~/.codex-switcher/current_cli` and `~/.codex-switcher/current_app`
+
+## Commands
+
+```bash
+codex-sw add <profile>
+codex-sw remove <profile> [--force]
+codex-sw list
+codex-sw import-default <profile> [--with-auth] [--force]
+codex-sw use <profile> [--sync|--no-sync]
+codex-sw switch <profile> [--sync|--no-sync]
+codex-sw current [cli|app]
+codex-sw status
+
+codex-sw exec -- <codex args...>
+codex-sw login [profile] [--sync|--no-sync]
+codex-sw logout [profile]
+codex-sw env [profile]
+
+codex-sw app open [profile]
+codex-sw app use <profile>
+codex-sw app logout [profile]
+codex-sw app status
+codex-sw app stop
+
+codex-sw init [--shell zsh|bash]
+codex-sw upgrade [--dry-run]
+codex-sw recover
+codex-sw check
+codex-sw doctor [--fix]
+```
+
+## Typical flow
+
+```bash
+codex-sw add work
+codex-sw add personal
+
+codex-sw use work --sync
+codex-sw login --sync
+codex-sw exec -- login status
+
+codex-sw switch personal --sync
+codex-sw app use personal
+```
+
+## Migrate Existing App/CLI Data
+
+If your existing data is in `~/.codex`, import it into a profile first:
+
+```bash
+codex-sw import-default work
+```
+
+This copies records/projects/history but excludes `auth.json` by default.
+If you want to carry login state too:
+
+```bash
+codex-sw import-default work --with-auth
+```
+
+## Sync Behavior
+
+- `login --sync`: overwrite sync from default `~/.codex` to target profile, excluding `auth.json`.
+- `use/switch --sync`: overwrite sync from current CLI profile to target profile, excluding `auth.json`.
+- `--no-sync`: explicit no-sync mode (default behavior).
+
+Examples:
+
+```bash
+codex-sw login work --sync
+codex-sw switch personal --sync
+codex-sw use work --no-sync
+```
+
+## Upgrade
+
+```bash
+codex-sw upgrade
+```
+
+## Notes
+
+- Codex App is single-instance on macOS; switching App profile requires restart.
+- `codex-sw app stop` only stops app instances started and tracked by `codex-sw`.
+- `codex-sw app open/use <profile>` requires that profile already exists and is logged in.
+- `--sync` uses overwrite strategy (not merge): source overwrites target for all files except `auth.json`.
+- `codex-sw status` exit codes:
+  - `0`: both current profiles logged in
+  - `1`: at least one current profile not logged in
+  - `2`: pointer/profile integrity issue (run `codex-sw recover`)
+
+## Validation
+
+```bash
+./plugins/codex-switcher/scripts/test-switcher.sh
+```
+
+## Compatibility command
+
+`codex-switcher` is kept as a compatibility entrypoint and maps to the same implementation.

package/plugins/codex-switcher/README.md

@@ -0,0 +1,112 @@
+# codex-sw
+
+中文 | [English](README.en.md)
+
+为 Codex CLI 与 Codex App 提供基于 profile 的账号切换能力。
+
+## 核心设计
+
+- 一个 profile 对应一个独立 `CODEX_HOME`：`~/.codex-profiles/<profile>`
+- CLI 命令在当前 CLI profile 下执行
+- App 在当前 App profile 下重启
+- 当前指针存储在 `~/.codex-switcher/current_cli` 与 `~/.codex-switcher/current_app`
+
+## 命令
+
+```bash
+codex-sw add <profile>
+codex-sw remove <profile> [--force]
+codex-sw list
+codex-sw import-default <profile> [--with-auth] [--force]
+codex-sw use <profile> [--sync|--no-sync]
+codex-sw switch <profile> [--sync|--no-sync]
+codex-sw current [cli|app]
+codex-sw status
+
+codex-sw exec -- <codex args...>
+codex-sw login [profile] [--sync|--no-sync]
+codex-sw logout [profile]
+codex-sw env [profile]
+
+codex-sw app open [profile]
+codex-sw app use <profile>
+codex-sw app logout [profile]
+codex-sw app status
+codex-sw app stop
+
+codex-sw init [--shell zsh|bash]
+codex-sw upgrade [--dry-run]
+codex-sw recover
+codex-sw check
+codex-sw doctor [--fix]
+```
+
+## 典型流程
+
+```bash
+codex-sw add work
+codex-sw add personal
+
+codex-sw use work --sync
+codex-sw login --sync
+codex-sw exec -- login status
+
+codex-sw switch personal --sync
+codex-sw app use personal
+```
+
+## 迁移已有数据
+
+如果你原本在 `~/.codex` 下使用 Codex，可先导入到某个 profile：
+
+```bash
+codex-sw import-default work
+```
+
+默认会迁移记录/项目等数据，但不包含 `auth.json`。
+如需连登录态一起导入：
+
+```bash
+codex-sw import-default work --with-auth
+```
+
+## 同步行为
+
+- `login --sync`：从默认 `~/.codex` 覆盖同步到目标 profile，排除 `auth.json`。
+- `use/switch --sync`：从当前 CLI profile 覆盖同步到目标 profile，排除 `auth.json`。
+- `--no-sync`：显式关闭同步（默认行为）。
+
+示例：
+
+```bash
+codex-sw login work --sync
+codex-sw switch personal --sync
+codex-sw use work --no-sync
+```
+
+## 升级
+
+```bash
+codex-sw upgrade
+```
+
+## 说明
+
+- macOS 下 Codex App 是单实例；切换 App profile 需要重启。
+- `codex-sw app stop` 仅停止由 `codex-sw` 启动并跟踪的 App 进程。
+- `codex-sw app open/use <profile>` 要求该 profile 已存在且已登录。
+- `--sync` 为覆盖策略（不是合并）：源目录覆盖目标目录，`auth.json` 除外。
+- `codex-sw status` 返回码：
+  - `0`：当前 CLI/App profile 均已登录
+  - `1`：至少一个当前 profile 未登录
+  - `2`：指针或 profile 完整性异常（可执行 `codex-sw recover`）
+
+## 验证
+
+```bash
+./plugins/codex-switcher/scripts/test-switcher.sh
+```
+
+## 兼容命令
+
+`codex-switcher` 作为兼容入口保留，行为与 `codex-sw` 一致。

package/plugins/codex-switcher/hooks.json

@@ -0,0 +1,3 @@
+{
+  "hooks": []
+}