@youdie006/swapdex 0.2.0 → 0.2.2

package/README.md

@@ -3,7 +3,7 @@
 <img src="https://raw.githubusercontent.com/youdie006/swapdex/main/docs/cli-banner.png" alt="swapdex - switch Claude Code and Codex login accounts, one command, all local" width="760" />
 
 [![CI](https://github.com/youdie006/swapdex/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/youdie006/swapdex/actions/workflows/ci.yml)
-[![license](https://img.shields.io/badge/license-MIT-1e1d1a.svg)](https://github.com/youdie006/swapdex/blob/main/LICENSE)
+[![license](https://img.shields.io/badge/license-MIT-1e1d1a.svg)](LICENSE)
 [![local only](https://img.shields.io/badge/network-none-7a3be0.svg)](#what-it-will-not-do)
 
 </div>
@@ -12,6 +12,10 @@ One command to flip your Claude Code or Codex CLI from your work account to your
 personal one, and back. No re-login, no browser, no copying tokens around.
 100% local. Never touches the network.
 
+<div align="center">
+<img src="https://raw.githubusercontent.com/youdie006/swapdex/main/docs/demo.gif" alt="swapdex demo: ls, use personal, status, restore, doctor" width="760" />
+</div>
+
 ---
 
 ## Why
@@ -26,6 +30,10 @@ It is a **switcher, not a rotator.** It manages accounts you already own for
 distinct purposes. It has no feature for cycling accounts to get around a rate
 limit -- see [What it will not do](#what-it-will-not-do).
 
+Safety is the design center: swapdex captures the *live* login before it swaps,
+so a switch can never lose or clobber an account, and it only ever hands the
+official CLI its own credentials -- no wrapper, no proxy, no client spoofing.
+
 ## Concepts
 
 - **Profile** -- a named, point-in-time snapshot of a live login (the credential
@@ -51,9 +59,10 @@ npm install -g @youdie006/swapdex
 curl -fsSL https://raw.githubusercontent.com/youdie006/swapdex/main/install.sh | sh
 ```
 
-Linux / WSL first (macOS Keychain support is planned). Requires the Claude Code
+Linux / WSL first; on macOS, Codex works today and Claude-via-Keychain is
+[issue #1](https://github.com/youdie006/swapdex/issues/1). Requires the Claude Code
 and/or Codex CLI already installed and logged in. Full command, exit-code, and
-environment reference: [docs/COMMANDS.md](https://github.com/youdie006/swapdex/blob/main/docs/COMMANDS.md).
+environment reference: [docs/COMMANDS.md](docs/COMMANDS.md).
 
 ## Use
 
@@ -68,11 +77,22 @@ swapdex status
 
 # Switch (takes effect on your next message -- no restart)
 swapdex use personal
+swapdex use -                       # toggle back to the previous profile
+swapdex use w                       # a unique prefix is enough
 swapdex use work --tool codex
 swapdex use work --dry-run          # show what would change, write nothing
 
 # Sessions grouped by the account active when they ran (needs sessionwiki)
 swapdex sessions
+
+# Recent local token usage per tool (5h/7d) -- tells you when to switch
+swapdex usage
+
+# Made a bad switch? Put back the login that was live before it
+swapdex restore
+
+# Anything off? Every finding comes with its fix
+swapdex doctor
 ```
 
 `status` shows the live account per tool, matched back to a saved profile:
@@ -85,6 +105,40 @@ codex: you@personal.com (profile 'personal')
 The active account is always read from the **live** login, so if you `/login`
 directly in the CLI, swapdex reports the truth rather than a stale guess.
 
+For your shell prompt or statusline, `status --short` prints one compact line:
+
+```sh
+$ swapdex status --short
+claude:work codex:personal
+```
+
+e.g. in a starship prompt: `command = "swapdex status --short"` in a
+[custom module](https://starship.rs/config/#custom-commands), or in `PS1`
+via `$(swapdex status --short)`.
+
+It also drops straight into **Claude Code's own status line**, so the active
+account is always visible inside the tool you are switching
+(`~/.claude/settings.json`):
+
+```json
+{
+  "statusLine": { "type": "command", "command": "swapdex status --short" }
+}
+```
+
+`usage` reads your local session logs (no network) to gauge how heavily you've
+been using each tool lately, so you know when to switch to a fresher account:
+
+```
+Local usage - this machine, approximate (not the billed quota):
+  claude-code  5h:   8.2M tok / 12 sess    7d:   61.4M tok / 88 sess
+  codex        5h:   1.1M tok / 3 sess     7d:   9.7M tok / 24 sess
+```
+
+It sums tokens from `~/.claude` and `~/.codex` transcripts, which are not tagged
+by account, so this is a machine-wide activity gauge rather than a per-account
+balance -- deliberately a hint, not a quota-dodging auto-rotator.
+
 ## How it works
 
 Each CLI keeps its login in a small on-disk file:
@@ -105,8 +159,11 @@ servers, and settings in that file are never touched.
 - Writes are atomic (temp file created `0600`, then renamed) so an interrupted
   switch can never leave a half-written credential that bricks the CLI.
 - Symlinked credential paths and running as root are refused.
-- `use` backs up the current login and verifies the backup before overwriting,
-  so a switch can never lose an un-saved login.
+- `use` writes a backup of the current login (fsynced, or the switch aborts)
+  before overwriting anything, and `swapdex restore` brings it back in one
+  command if the switch was a mistake. The store keeps the last 2 backups per
+  tool, and `use` warns when the outgoing login is not saved as a profile --
+  so save accounts you care about with `add`.
 - No token, refresh token, or home path is ever printed.
 
 **The store holds plaintext refresh tokens.** Protect `~/.local/share/swapdex`
@@ -124,11 +181,17 @@ cannot happen:
 - **No auto-rotation.** There is no `--auto`, `--next`, or
   `--when-rate-limited` flag. `use` only ever switches to a name you type.
 - **No token export.** There is no command that prints a saved credential.
+- **No wrapper, no client spoofing.** swapdex swaps the credential file that the
+  official `claude` / `codex` binary already reads, then gets out of the way. It
+  never sits between the CLI and the API, never proxies requests, and never
+  presents itself as the official client. Your traffic is the real CLI's traffic.
 
 Anthropic and OpenAI both permit multiple accounts for genuinely different
 purposes but forbid using multiple accounts to get around a single workload's
-rate limit, and forbid using OAuth tokens outside the official CLI. swapdex is
-built for the former and structurally cannot do the latter. See
+rate limit, and forbid routing subscription OAuth tokens through third-party
+tools or spoofing the official client. swapdex is built for the former and
+structurally cannot do the latter -- it only ever hands the real CLI its own
+credentials. See
 [Anthropic Usage Policy](https://www.anthropic.com/legal/usage-policy) and
 [OpenAI Usage Policies](https://openai.com/policies/usage-policies/).
 
@@ -151,8 +214,33 @@ swapdex is the accounts layer of a small local AI-CLI stack:
 - [prodex](https://github.com/youdie006/prodex) -- share one logged-in ChatGPT
   Pro session across agents. swapdex coexists with it without touching its auth.
 
+## Alternatives
+
+Good tools exist in this space; they make different trade-offs (each line from
+that project's README, July 2026):
+
+- [claude-swap](https://github.com/realiti4/claude-swap) -- Claude Code only,
+  a TUI with live usage bars, and *optional auto-switching* near your limit.
+  If you want auto-rotation, use it -- swapdex deliberately refuses to have
+  that feature.
+- [aisw](https://github.com/burakdede/aisw) -- cross-tool including Gemini,
+  OS-keyring storage, Windows support. More features, bigger surface.
+- [caam](https://github.com/Dicklesworthstone/coding_agent_account_manager) --
+  cross-tool with a shell wrapper and automatic rotation on rate limits; the
+  philosophical opposite of swapdex.
+
+Pick swapdex if you want the smallest thing that switches Claude Code and
+Codex together, can always undo (`restore`), diagnoses itself (`doctor`),
+and structurally cannot rotate, proxy, or touch the network.
+
 ## Roadmap
 
+- **Claude Code on macOS (Keychain).** On macOS, Claude Code keeps its login in
+  the Keychain rather than a file; swapdex detects this and refuses honestly
+  instead of half-switching, but switching it is not supported yet. Design and
+  constraints: [issue #1](https://github.com/youdie006/swapdex/issues/1) --
+  contributions from macOS users welcome (Codex already works on macOS).
+
 Being considered, explicitly opt-in and advisory-only:
 
 - **Per-directory hints (cross-tool).** Bind a directory to a profile and have

package/package.json

@@ -1,12 +1,13 @@
 {
   "name": "@youdie006/swapdex",
-  "version": "0.2.0",
+  "version": "0.2.2",
   "description": "Switch between multiple Claude Code and Codex login accounts, locally and safely.",
   "bin": {
     "swapdex": "bin/swapdex.js"
   },
   "scripts": {
-    "postinstall": "node install.js"
+    "postinstall": "node install.js",
+    "prepublishOnly": "cp ../README.md ./README.md"
   },
   "files": [
     "README.md",