ai-acct-autopilot 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Alnim (alnimra)
+
+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.md

@@ -0,0 +1,184 @@
+# ai-acct-autopilot
+
+**A terminal dashboard + autopilot for multiple Claude Code and Codex accounts.**
+Watches usage across every account, auto-switches before you hit the wall, and
+resumes running sessions on the fresh account — so an overnight agent run never
+dies to a rate limit while you sleep.
+
+![ai-acct-autopilot dashboard](assets/screenshot.png)
+
+## Why
+
+If you run serious agent workloads on subscription plans (Claude Max, ChatGPT
+Pro), you know the dance: watch the usage meter, and when it gets close to the
+5-hour or weekly limit, scramble to re-login into another account before your
+running sessions stall. Do it at your desk and it's annoying. Have it happen at
+3am during an overnight run and the night is lost.
+
+`ai-acct-autopilot` automates the whole dance:
+
+- **One dashboard** for every Claude and Codex account: 5h / weekly / opus /
+  sonnet bars, "% left", reset countdowns, usage trends — codexbar-style, in
+  your terminal.
+- **Auto-switch at the threshold** (default <5% left on the 5h *or* weekly
+  window): the healthiest account takes over, picked by live probed usage.
+- **Sessions keep running.** Claude sessions follow the switch automatically;
+  Codex sessions are restarted *and resumed mid-thread* by a supervisor shim.
+- **Tokens heal themselves.** Stale account credentials are refreshed in the
+  background (atomically, with backups) so usage bars never go blind and
+  browser re-logins become rare.
+- **Local cost panel**: today/30-day spend estimated at API rates from your
+  local session logs, per provider, all accounts combined — see what your
+  subscriptions are actually worth.
+
+Everything is local: your tokens never leave your machine, there is no
+telemetry, and the only network calls are to Anthropic/OpenAI's own endpoints
+with your own credentials.
+
+## Requirements
+
+- **macOS** (account storage uses the macOS keychain for Claude)
+- **Node 18+**
+- [Claude Code](https://code.claude.com) and/or [Codex CLI](https://developers.openai.com/codex) with subscription login(s)
+
+## Install
+
+```bash
+npm install -g ai-acct-autopilot
+# or from a clone:
+git clone https://github.com/alnimra/ai-acct-autopilot && cd ai-acct-autopilot && ./install.sh
+```
+
+This installs two commands: `ai-acct-autopilot` (the dashboard/autopilot) and
+`claude-acct` (the Claude account manager it builds on).
+
+## Quick start
+
+```bash
+# 1. Save your current Claude account, then add more (browser login each):
+claude-acct save you@example.com
+claude-acct add other@example.com        # overwrite-login; NEVER /logout
+
+# 2. Add codex accounts (isolated login — your current session stays alive):
+ai-acct-autopilot codex-save             # snapshot the current codex account
+ai-acct-autopilot codex-add other@example.com
+
+# 3. Install the codex supervisor shim (enables auto-resume of running sessions):
+ai-acct-autopilot codex-shim install
+
+# 4. Run it. Leave it in a terminal.
+ai-acct-autopilot
+```
+
+That's it. When the active account drops below 5% left, the switch happens by
+itself, a macOS notification tells you about it, and the journal at the bottom
+of the dashboard keeps the receipts.
+
+## How switching works (and the Claude/Codex asymmetry)
+
+| | Claude Code | Codex |
+|---|---|---|
+| Credential store | macOS keychain | `~/.codex/auth.json` |
+| Switch mechanism | keychain swap via `claude-acct use` | `auth.json` swap |
+| **Running sessions** | **follow the switch in ~30s** (Claude re-reads the keychain) | hold auth in memory — never re-read ([openai/codex#17041](https://github.com/openai/codex/issues/17041)) |
+| Fix for running sessions | not needed | **supervisor shim restarts + resumes them** |
+
+The codex supervisor shim (`codex-shim install`) wraps the codex binary. Every
+codex launch goes through it, and when the autopilot switches accounts it:
+
+1. captures each running session's id from the rollout file the codex process
+   holds open,
+2. terminates the process with a restart marker,
+3. relaunches `codex … resume <session-id>` — original flags preserved — so
+   the **same conversation continues on the new account** in the same terminal.
+
+Sessions you quit normally exit exactly like stock codex; ctrl-C still belongs
+to codex. Fail-open: if anything in the shim breaks, codex launches normally.
+
+### Adding codex accounts safely
+
+`codex login` inside a shared `~/.codex` **revokes the previous account's
+session** — that's why `codex-add` runs the login in a throwaway isolated
+`CODEX_HOME` and imports the result. Your existing sessions stay alive. Never
+add accounts with a plain `codex login`.
+
+## Commands
+
+| Command | What it does |
+|---|---|
+| `ai-acct-autopilot` | run the dashboard + autopilot (60s ticks) |
+| `ai-acct-autopilot --no-switch` | monitor only — shows the switch it WOULD make |
+| `ai-acct-autopilot --once --plain` | single tick, plain text (logging/cron) |
+| `ai-acct-autopilot codex-add <email>` | add a codex account via isolated login |
+| `ai-acct-autopilot codex-use <email>` | switch codex account (+ resume running sessions) |
+| `ai-acct-autopilot codex-list` / `codex-save` | list / snapshot codex accounts |
+| `ai-acct-autopilot codex-shim install\|status\|uninstall` | manage the supervisor shim |
+| `ai-acct-autopilot --test-decision` | run the decision-logic self-tests |
+| `claude-acct add\|save\|use\|list\|usage` | manage Claude accounts (by email) |
+
+Flags: `--interval N` (seconds, default 60) · `--threshold N` (switch when
+<N% left, default 5) · `--cooldown N` (minutes between switches, default 10).
+
+## Safety properties
+
+- **Never `/logout`** — logging out revokes Claude sessions server-side;
+  account capture always uses overwrite-login.
+- **Never switch into the unknown** — a target must pass a live usage probe
+  this tick; accounts with failed probes or revoked sessions are excluded.
+- **Atomic credential writes** with `.bak` of the previous blob; a failed
+  refresh never deletes anything.
+- **Cooldown + all-hot hold** — no thrashing; if every account is hot, it
+  holds, notifies once, and shows the earliest reset.
+- **Append-only journal** (`~/.claude/accounts/switch-journal.jsonl`) — every
+  switch, snapshot, and restart with timestamps and reasons.
+- **Local-only** — no telemetry, no third-party services, tokens never leave
+  the machine.
+
+## How usage is read
+
+- **Claude**: Anthropic's OAuth usage/profile endpoints, per saved account
+  token (refreshed in the background when stale).
+- **Codex**: `chatgpt.com/backend-api/wham/usage` per account token — works
+  for benched accounts with zero sessions; the **regular** account limit is
+  used (model-family buckets like the Spark research preview are ignored).
+  Rollout session logs provide the offline fallback and the trend sparkline.
+- **Costs**: estimated at public API rates from local session logs
+  (`~/.claude/projects`, `~/.codex/sessions`), with per-model pricing mirrored
+  from [CodexBar](https://github.com/steipete/CodexBar). Estimates, not bills —
+  they exist to show what your subscription usage would cost at API rates.
+
+See [docs/how-it-works.md](docs/how-it-works.md) for the full architecture:
+token lifecycles, the codex single-session discovery, supervisor internals,
+and every endpoint touched.
+
+## FAQ
+
+**Is this safe to run?** It only manages accounts you own, with credentials
+already on your machine, talking to the providers' own endpoints. Treat
+`~/.claude/accounts` and `~/.codex/accounts` like the secrets they are (the
+tool keeps them `0600`).
+
+**What about pinned sessions?** Claude worktree pins
+(`claude-acct pin`) are respected — pinned sessions never follow the global
+switch, by design.
+
+**A codex switch happened mid-turn — did I lose work?** The thread resumes,
+but an in-flight turn is lost (it was about to die to the rate limit anyway).
+Re-ask and continue.
+
+**npm upgraded codex and the shim disappeared.** That's the fail-safe
+direction: upgrades restore stock codex. Re-run
+`ai-acct-autopilot codex-shim install`.
+
+**Linux/Windows?** Not yet — Claude account storage is macOS-keychain-based.
+The codex side is mostly portable; PRs welcome.
+
+## Credits
+
+- [CodexBar](https://github.com/steipete/CodexBar) for the pricing tables,
+  the `wham/usage` endpoint path, and the visual inspiration.
+- Built end-to-end with [Claude Code](https://claude.com/claude-code).
+
+## License
+
+[MIT](LICENSE)