codex-accounts 0.1.0__py3-none-any.whl

codex_accounts-0.1.0.dist-info/METADATA

@@ -0,0 +1,238 @@
+Metadata-Version: 2.4
+Name: codex-accounts
+Version: 0.1.0
+Summary: Multi-account CLI manager for the OpenAI Codex desktop app
+Project-URL: Homepage, https://github.com/wikty/codex-accounts
+Project-URL: Documentation, https://github.com/wikty/codex-accounts#readme
+Project-URL: Issues, https://github.com/wikty/codex-accounts/issues
+Project-URL: Source, https://github.com/wikty/codex-accounts
+Project-URL: Changelog, https://github.com/wikty/codex-accounts/blob/main/CHANGELOG.md
+Author: codex-accounts contributors
+License: MIT License
+        
+        Copyright (c) 2026 wikty and codex-switch contributors
+        
+        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.
+License-File: LICENSE
+Keywords: account-switcher,chatgpt,cli,codex,multi-account,openai
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: MacOS
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Utilities
+Requires-Python: >=3.9
+Provides-Extra: dev
+Requires-Dist: pre-commit>=4.0; extra == 'dev'
+Requires-Dist: pytest-cov>=4.0; extra == 'dev'
+Requires-Dist: pytest>=7.0; extra == 'dev'
+Requires-Dist: ruff>=0.5; extra == 'dev'
+Description-Content-Type: text/markdown
+
+<!-- markdownlint-disable MD041 -->
+<h1 align="center">codex-accounts</h1>
+
+<p align="center">
+  <em>A multi-account CLI manager for the OpenAI Codex desktop app.</em>
+</p>
+
+<p align="center">
+  <a href="https://github.com/wikty/codex-accounts/actions/workflows/ci.yml"><img alt="CI" src="https://img.shields.io/github/actions/workflow/status/wikty/codex-accounts/ci.yml?branch=main&label=tests"></a>
+  <a href="https://pypi.org/project/codex-accounts/"><img alt="PyPI" src="https://img.shields.io/pypi/v/codex-accounts.svg"></a>
+  <a href="https://pypi.org/project/codex-accounts/"><img alt="Python" src="https://img.shields.io/pypi/pyversions/codex-accounts.svg"></a>
+  <a href="./LICENSE"><img alt="License" src="https://img.shields.io/badge/license-MIT-blue.svg"></a>
+</p>
+
+<p align="center">
+  <a href="./README.zh-CN.md">中文文档</a> · <a href="./docs/installation.md">Install</a> · <a href="./docs/add-account.md">Add an account</a> · <a href="./docs/faq.md">FAQ</a>
+</p>
+
+---
+
+The OpenAI Codex desktop app stores all sessions, logs, and UI state in
+`~/.codex/` — and the underlying SQLite database has **no notion of which
+account a row belongs to**. The moment you switch to a different ChatGPT
+account, every previous session disappears from the sidebar.
+
+**codex-accounts** fixes this by swapping the relevant files in and out of
+`~/.codex/`, giving you clean multi-account isolation with a single command:
+
+```console
+$ codex-accounts use work
+✓ switched to: work  (auth mode)
+
+$ codex-accounts list
+Accounts (/Users/you/.codex-accounts):
+
+  ▶ work       work@example.com    Plus       5d left      2h ago    ← current
+    personal   personal@me.io      Plus       9d left      yesterday
+    research   lab@university.edu  Pro        1d left ⚠    3d ago
+```
+
+## Features
+
+- **One-command switching** — `codex-accounts use <name>` saves the current
+  account and activates the target in a single step.
+- **Two isolation modes** — share session history across all accounts
+  (default) or fully isolate sessions, history, and shell snapshots per
+  account (`--no-share-sessions`).
+- **Live quota** — `quota` and `list -a` query the same private endpoint
+  the Codex client uses for its 5h/weekly progress bars.
+- **Local usage stats** — `stats` reads the Codex SQLite database directly
+  for offline token-usage breakdowns.
+- **Auto-refresh** — `refresh` opens the 5-hour window across every
+  account so a sliding daily allotment never goes unused (see
+  [docs/auto-refresh.md](./docs/auto-refresh.md)).
+- **Zero dependencies** — pure stdlib Python; ships as a single console
+  script.
+
+## Requirements
+
+| | Supported |
+|---|---|
+| **OS** | macOS 12+ (primary), Linux (best-effort, PRs welcome) |
+| **Python** | 3.9+ |
+| **Codex desktop app** | already installed and signed in at least once |
+
+> Windows is not currently supported. The path conventions and process
+> detection in `codex_switch.utils` would need to be extended; PRs welcome.
+
+## Install
+
+```bash
+# Recommended: isolated install with pipx
+pipx install codex-accounts
+
+# Or with pip
+pip install --user codex-accounts
+```
+
+For a no-package-manager install of the bundled launcher script, see
+[`docs/installation.md`](./docs/installation.md).
+
+## Quick start
+
+```bash
+# 1. Snapshot the account you're already logged in to
+codex-accounts save work
+
+# 2. Add a second account (interactive)
+codex-accounts init personal      # placeholder dir
+codex-accounts use   personal     # clears auth.json so Codex prompts you to log in
+open -a Codex                   # finish OAuth in the browser
+codex-accounts save  personal     # capture the new account's data
+
+# 3. Day-to-day
+codex-accounts list               # see everything at a glance
+codex-accounts use work           # switch back
+codex-accounts quota              # check 5h / weekly limits
+codex-accounts stats              # local token usage
+```
+
+See [docs/add-account.md](./docs/add-account.md) for a full walkthrough.
+
+## Commands
+
+| Command | What it does |
+|---|---|
+| `list [-a]` | List saved accounts (`-a` adds live quota) |
+| `current` | Print the active account |
+| `info [name]` | Email, plan, token expiry, notes |
+| `save <name> [--auth-only]` | Snapshot current Codex state under `<name>` |
+| `use <name> [--no-share-sessions]` | Activate `<name>` (auto-saves the current one first) |
+| `init <name>` | Create an empty snapshot directory (no copy) |
+| `note <name> <text>` | Attach a free-text note |
+| `rename <old> <new>` | Rename an account snapshot |
+| `delete <name>` | Remove a snapshot directory |
+| `stats [name]` | Token usage from local SQLite |
+| `quota [name]` | Live quota via private API (requires network) |
+| `refresh` | Open the 5h window on every account (cron-friendly) |
+| `doctor` | Environment dump for bug reports |
+
+Run `codex-accounts <cmd> --help` for command-specific options.
+
+## How it works
+
+```
+~/.codex/                           ~/.codex-accounts/work/
+├── auth.json          <─ swap ─>   ├── auth.json
+├── state_*.sqlite     <─ swap ─>   ├── state_*.sqlite       (FULL mode only)
+├── sessions/          <─ swap ─>   ├── dirs/sessions/       (FULL mode only)
+├── config.toml                     └── meta.json            (notes, timestamps)
+├── skills/  rules/  memories/     (shared across all accounts — never swapped)
+└── installation_id
+```
+
+- **AUTH mode** (default for `use`) — only `auth.json` is swapped. Sessions
+  and history live in `~/.codex/` and are visible from every account. This
+  is what most people want.
+- **FULL mode** (`use --no-share-sessions`) — session DBs, log DBs, JSONL
+  index, the `sessions/`/`archived_sessions/`/`shell_snapshots/`
+  directories, and the global UI state file are all swapped. Use this when
+  you genuinely want separate session sidebars per account.
+
+The exact file list lives in
+[`src/codex_switch/config.py`](./src/codex_switch/config.py) and uses
+**glob patterns** (`state_*.sqlite`, `logs_*.sqlite`) so future Codex
+schema bumps don't silently miss files.
+
+## Security & privacy
+
+- `~/.codex-accounts/` and every snapshot directory inside it are created
+  with mode `0700`.
+- Account names are validated against `^[A-Za-z0-9][A-Za-z0-9_.-]{0,63}$`
+  to prevent path traversal.
+- `auth.json` is the same plaintext OAuth bundle the Codex client itself
+  stores. Treat snapshot directories with the same care you'd treat
+  `~/.codex/` — back them up, but do not check them into git or sync them
+  to anywhere unencrypted.
+- `quota`, `list -a`, and `refresh` make network calls to
+  `chatgpt.com/backend-api`. All other commands are fully offline.
+- See [`SECURITY.md`](./SECURITY.md) for vulnerability reporting.
+
+## Disclaimers
+
+- This project is **not affiliated with OpenAI** in any way.
+- `quota`, `list -a`, and `refresh` rely on private endpoints
+  (`/backend-api/wham/usage` and `/backend-api/codex/responses`) that were
+  located by reverse-engineering the Codex desktop client. They can change
+  at any time. See
+  [`docs/internals/codex-app-internals.md`](./docs/internals/codex-app-internals.md)
+  for the methodology used to re-discover them when a Codex update breaks
+  the integration.
+- `refresh` sends low-cost API requests on your behalf. Read
+  [`docs/auto-refresh.md`](./docs/auto-refresh.md) — including the
+  rate-limit and abuse-prevention caveats — before enabling the cron job.
+
+## Contributing
+
+Pull requests, bug reports, and "I tried it on Linux and X broke" notes
+are all welcome. See [`CONTRIBUTING.md`](./CONTRIBUTING.md) for the dev
+loop, and [`CODE_OF_CONDUCT.md`](./CODE_OF_CONDUCT.md) for community
+expectations.
+
+## License
+
+[MIT](./LICENSE) © codex-accounts contributors.

codex_accounts-0.1.0.dist-info/RECORD

@@ -0,0 +1,13 @@
+codex_switch/__init__.py,sha256=BiLmZ6V2piAf3RgFOqS6bgaBQ_XIWPh0UtuB7Vp_mvM,161
+codex_switch/__main__.py,sha256=0DSFlsXKCZR4_qi1Xr1Db5sD92rVcy-DCWOeTlqrMYU,178
+codex_switch/accounts.py,sha256=dnODuy9dJNxxNtppVyO-kE4jgdhBajFqE0q-L3zfb4I,8362
+codex_switch/api.py,sha256=7MjdCxmzxTpvo0JhwvIbU9ShzYCVE0BPRfSTb58JCnc,4696
+codex_switch/cli.py,sha256=uKnCvQBNijGCW4RQSyL-dL3Hdffo8HZzupZaibYZqg8,18510
+codex_switch/config.py,sha256=wpJzHGJ5mzWBdJIFd-nHjXyWv72FAvaaoRsxl2cFx6k,3113
+codex_switch/stats.py,sha256=ZEgn_MWc-rmct4OuA4qJVOmoW3i2Veb7H3XHUtHRsI0,4400
+codex_switch/utils.py,sha256=wWU_MfQTbPvZbRGenipvj5nJqOaTH3R63INiW0zVxgk,8395
+codex_accounts-0.1.0.dist-info/METADATA,sha256=3dcbjaJtJVZXn0iigYRTNgxv5Il6Sn7yz8WWy0x1gto,10410
+codex_accounts-0.1.0.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+codex_accounts-0.1.0.dist-info/entry_points.txt,sha256=fNQGxFS_sj-X-ZESkv-fFQ_znoeEok4uWpYchhebsdE,57
+codex_accounts-0.1.0.dist-info/licenses/LICENSE,sha256=_w2Q2dtFmeUQTQt6O7iit67OVvgDc04cbEqJbB1H3T4,1092
+codex_accounts-0.1.0.dist-info/RECORD,,

codex_accounts-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.29.0
+Root-Is-Purelib: true
+Tag: py3-none-any

codex_accounts-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+codex-accounts = codex_switch.cli:main

codex_accounts-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 wikty and codex-switch contributors
+
+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.

codex_switch/__init__.py

@@ -0,0 +1,6 @@
+"""codex-accounts: a multi-account CLI for the OpenAI Codex desktop app."""
+
+from __future__ import annotations
+
+__version__ = "0.1.0"
+__all__ = ["__version__"]

codex_switch/__main__.py

@@ -0,0 +1,8 @@
+"""Entry point for ``python -m codex_switch``."""
+
+from __future__ import annotations
+
+from codex_switch.cli import main
+
+if __name__ == "__main__":
+    raise SystemExit(main())

codex_switch/accounts.py

@@ -0,0 +1,265 @@
+"""Account snapshot management: save / load / list / init / rename / delete."""
+
+from __future__ import annotations
+
+import json
+import shutil
+from collections.abc import Iterable, Iterator
+from dataclasses import dataclass
+from datetime import datetime, timezone
+from enum import Enum
+from pathlib import Path
+
+from codex_switch import config, utils
+from codex_switch.utils import AuthInfo
+
+
+class SwapMode(str, Enum):
+    """How much state to swap when saving/loading an account.
+
+    * ``AUTH`` — only ``auth.json``.  Sessions and history are shared across
+      accounts (the default).
+    * ``FULL`` — every per-account file and directory listed in
+      :mod:`codex_switch.config` is swapped, giving complete isolation.
+    """
+
+    AUTH = "auth"
+    FULL = "full"
+
+    def patterns(self) -> tuple[str, ...]:
+        return config.AUTH_FILES if self is SwapMode.AUTH else config.ACCOUNT_FILE_PATTERNS
+
+    def dirs(self) -> tuple[str, ...]:
+        return () if self is SwapMode.AUTH else config.ACCOUNT_DIRS
+
+
+@dataclass
+class Account:
+    """A snapshot directory under ``~/.codex-accounts/``."""
+
+    name: str
+    path: Path
+
+    @property
+    def auth_file(self) -> Path:
+        return self.path / "auth.json"
+
+    @property
+    def meta_file(self) -> Path:
+        return self.path / "meta.json"
+
+    @property
+    def dirs_root(self) -> Path:
+        return self.path / "dirs"
+
+    def read_meta(self) -> dict:
+        if not self.meta_file.exists():
+            return {}
+        try:
+            with self.meta_file.open(encoding="utf-8") as fh:
+                data = json.load(fh)
+            return data if isinstance(data, dict) else {}
+        except (OSError, json.JSONDecodeError):
+            return {}
+
+    def update_meta(self, **changes: object) -> None:
+        meta = self.read_meta()
+        meta.update({k: v for k, v in changes.items() if v is not None})
+        utils.ensure_private_dir(self.path)
+        with self.meta_file.open("w", encoding="utf-8") as fh:
+            json.dump(meta, fh, ensure_ascii=False, indent=2)
+            fh.write("\n")
+
+
+# ---------------------------------------------------------------------------
+# Current account pointer
+# ---------------------------------------------------------------------------
+
+
+def current_name() -> str | None:
+    f = config.current_file()
+    if not f.exists():
+        return None
+    try:
+        name = f.read_text(encoding="utf-8").strip()
+    except OSError:
+        return None
+    return name or None
+
+
+def set_current(name: str) -> None:
+    utils.ensure_private_dir(config.accounts_home())
+    config.current_file().write_text(name + "\n", encoding="utf-8")
+
+
+# ---------------------------------------------------------------------------
+# Discovery
+# ---------------------------------------------------------------------------
+
+
+def list_accounts() -> list[Account]:
+    home = config.accounts_home()
+    if not home.is_dir():
+        return []
+    out: list[Account] = []
+    for entry in sorted(home.iterdir(), key=lambda p: p.name.lower()):
+        if entry.name.startswith("."):
+            continue
+        if not entry.is_dir():
+            continue
+        out.append(Account(name=entry.name, path=entry))
+    return out
+
+
+def get_account(name: str, *, must_exist: bool = True) -> Account:
+    utils.validate_account_name(name)
+    path = config.accounts_home() / name
+    if must_exist and not path.is_dir():
+        raise FileNotFoundError(f"account '{name}' not found under {config.accounts_home()}")
+    return Account(name=name, path=path)
+
+
+def auth_file_for(name: str) -> Path:
+    """Return the live or snapshotted ``auth.json`` for ``name``.
+
+    The currently active account reads from ``~/.codex/auth.json`` so we
+    pick up the freshest token; other accounts use their snapshot copy.
+    """
+    if current_name() == name:
+        return config.codex_home() / "auth.json"
+    return config.accounts_home() / name / "auth.json"
+
+
+def read_auth(name: str) -> AuthInfo | None:
+    return utils.decode_auth_file(auth_file_for(name))
+
+
+# ---------------------------------------------------------------------------
+# Snapshot mutations
+# ---------------------------------------------------------------------------
+
+
+def _iter_matches(root: Path, patterns: Iterable[str]) -> Iterator[Path]:
+    seen: set[Path] = set()
+    for pattern in patterns:
+        for match in sorted(root.glob(pattern)):
+            if match in seen:
+                continue
+            seen.add(match)
+            yield match
+
+
+def init_account(name: str) -> Account:
+    """Create an empty snapshot directory (no files copied)."""
+    utils.validate_account_name(name)
+    home = config.accounts_home()
+    utils.ensure_private_dir(home)
+    path = home / name
+    if path.exists():
+        raise FileExistsError(f"account '{name}' already exists at {path}")
+    utils.ensure_private_dir(path)
+    utils.ensure_private_dir(path / "dirs")
+    Account(name=name, path=path).update_meta(
+        created_at=_now_iso(),
+    )
+    return Account(name=name, path=path)
+
+
+def save_account(name: str, mode: SwapMode = SwapMode.FULL) -> Account:
+    """Copy live Codex state into the account snapshot directory."""
+    utils.validate_account_name(name)
+    home = config.accounts_home()
+    utils.ensure_private_dir(home)
+    dest = home / name
+    utils.ensure_private_dir(dest)
+    utils.ensure_private_dir(dest / "dirs")
+
+    src = config.codex_home()
+    if not src.is_dir():
+        raise FileNotFoundError(
+            f"Codex home not found at {src} — is the Codex desktop app installed?"
+        )
+
+    for live in _iter_matches(src, mode.patterns()):
+        if not live.is_file():
+            continue
+        shutil.copy2(live, dest / live.name)
+
+    for d in mode.dirs():
+        src_dir = src / d
+        if not src_dir.is_dir():
+            continue
+        target = dest / "dirs" / d
+        if target.exists():
+            shutil.rmtree(target)
+        shutil.copytree(src_dir, target, symlinks=True)
+
+    account = Account(name=name, path=dest)
+    account.update_meta(last_used_at=_now_iso())
+    return account
+
+
+def load_account(name: str, mode: SwapMode = SwapMode.FULL) -> Account:
+    """Copy the account snapshot back into the live Codex home."""
+    account = get_account(name, must_exist=True)
+    dest = config.codex_home()
+    utils.ensure_private_dir(dest)
+
+    # Files: replace if snapshot has them, delete from live home if not.
+    snap_files = {p.name: p for p in _iter_matches(account.path, mode.patterns())}
+    live_files = {p.name: p for p in _iter_matches(dest, mode.patterns())}
+
+    for name_, src in snap_files.items():
+        shutil.copy2(src, dest / name_)
+
+    for name_, live in live_files.items():
+        if name_ not in snap_files:
+            live.unlink(missing_ok=True)
+
+    # Directories: only swap when in FULL mode; preserve live dirs otherwise.
+    for d in mode.dirs():
+        live_dir = dest / d
+        snap_dir = account.path / "dirs" / d
+        if snap_dir.is_dir():
+            if live_dir.exists():
+                shutil.rmtree(live_dir)
+            shutil.copytree(snap_dir, live_dir, symlinks=True)
+
+    set_current(name)
+    account.update_meta(last_used_at=_now_iso())
+    return account
+
+
+def rename_account(old: str, new: str) -> Account:
+    src = get_account(old, must_exist=True)
+    utils.validate_account_name(new)
+    dst_path = config.accounts_home() / new
+    if dst_path.exists():
+        raise FileExistsError(f"account '{new}' already exists")
+    src.path.rename(dst_path)
+    if current_name() == old:
+        set_current(new)
+    return Account(name=new, path=dst_path)
+
+
+def delete_account(name: str, *, dry_run: bool = False) -> Path:
+    account = get_account(name, must_exist=True)
+    if current_name() == name:
+        raise RuntimeError(f"cannot delete the currently active account '{name}'; switch first")
+    if not dry_run:
+        shutil.rmtree(account.path)
+    return account.path
+
+
+def set_note(name: str, text: str) -> None:
+    account = get_account(name, must_exist=True)
+    account.update_meta(notes=text)
+
+
+# ---------------------------------------------------------------------------
+# Misc
+# ---------------------------------------------------------------------------
+
+
+def _now_iso() -> str:
+    return datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ")