codex-accounts 0.1.0__tar.gz

codex_accounts-0.1.0/.gitignore

@@ -0,0 +1,66 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+build/
+dist/
+*.egg-info/
+*.egg
+.eggs/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.coverage
+.coverage.*
+coverage.xml
+htmlcov/
+.tox/
+.nox/
+
+# Virtual environments
+.venv/
+venv/
+env/
+ENV/
+.python-version
+.envrc
+.direnv/
+
+# Editors / OS
+.idea/
+.vscode/
+*.swp
+*.swo
+.DS_Store
+Thumbs.db
+*.orig
+
+# Local artifacts
+*.log
+/tmp/
+.scratch/
+.cache/
+.hypothesis/
+
+# User-specific overrides committed by accident
+codex-switch.local.*
+
+# Secrets / local auth snapshots
+.env
+.env.*
+auth.json
+*.pem
+*.p12
+*.key
+
+# Local Codex data copies accidentally brought into the repo
+.codex/
+.codex-accounts/
+
+# Local databases and log exports used during debugging
+*.db
+*.sqlite
+*.sqlite3
+*.jsonl

codex_accounts-0.1.0/CHANGELOG.md

@@ -0,0 +1,31 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.1.0] - 2026-05-30
+
+Initial open-source release. The project began as a single-file Bash
+script for personal use; this version is a from-scratch rewrite as a
+clean Python package.
+
+### Added
+- Python package `codex_switch` with stdlib-only dependencies.
+- Subcommands: `list`, `current`, `info`, `save`, `use`, `init`, `note`,
+  `rename`, `delete`, `stats`, `quota`, `refresh`, `doctor`.
+- Two swap modes (`AUTH` and `FULL`) selectable via `--no-share-sessions`.
+- Glob-based file matching (`state_*.sqlite`, `logs_*.sqlite`) so Codex
+  schema bumps no longer require code changes.
+- Account-name validation against `^[A-Za-z0-9][A-Za-z0-9_.-]{0,63}$`.
+- Automatic `chmod 0700` on accounts home and per-account directories.
+- LaunchAgent template for the daily `refresh` cron job.
+- Shell completions for bash and zsh.
+- Pytest suite with isolated `CODEX_HOME` / `CODEX_SWITCH_HOME` fixtures.
+- GitHub Actions CI matrix on macOS and Ubuntu.
+
+[Unreleased]: https://github.com/wikty/codex-accounts/compare/v0.1.0...HEAD
+[0.1.0]: https://github.com/wikty/codex-accounts/releases/tag/v0.1.0

codex_accounts-0.1.0/CODE_OF_CONDUCT.md

@@ -0,0 +1,29 @@
+# Code of Conduct
+
+This project follows version 2.1 of the **Contributor Covenant**, which is
+the de-facto community standard for open-source projects.
+
+The full text is available at:
+<https://www.contributor-covenant.org/version/2/1/code_of_conduct/>
+
+## TL;DR
+
+- Be welcoming, patient, and respectful in every interaction — issues,
+  pull requests, discussions, code reviews, chat.
+- Critique code, not contributors. Assume good intent and ask for
+  clarification before escalating.
+- Off-topic, personal, or hostile content has no place in this
+  repository.
+
+## Reporting
+
+If you believe someone has acted contrary to this Code of Conduct, please
+open a private report through GitHub's "Report content" flow on the
+relevant issue, comment, or pull request. Maintainers will review and
+respond as quickly as we can.
+
+## Enforcement
+
+Maintainers may, at their discretion, remove comments, close issues or
+pull requests, or block contributors who repeatedly violate this Code of
+Conduct after a warning.

codex_accounts-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,97 @@
+# Contributing to codex-accounts
+
+Thanks for considering a contribution! This project is small enough that
+process can stay light — please follow the conventions below and we'll
+keep moving fast.
+
+## Quick dev loop
+
+```bash
+git clone https://github.com/wikty/codex-accounts.git
+cd codex-accounts
+
+# Set up a virtualenv and install in editable mode with dev extras
+python3 -m venv .venv
+source .venv/bin/activate
+pip install -e ".[dev]"
+
+# Install git hooks
+pre-commit install
+
+# Run the test suite
+pytest
+
+# Lint
+ruff check .
+ruff format --check .
+
+# Run the full local gate (including secret scanning)
+pre-commit run --all-files
+```
+
+The CLI is then available as `codex-accounts` inside the venv. It reads
+its paths from `CODEX_HOME` and `CODEX_SWITCH_HOME` env vars, so you can
+point it at a sandbox while iterating:
+
+```bash
+export CODEX_HOME=/tmp/cs-sandbox/codex
+export CODEX_SWITCH_HOME=/tmp/cs-sandbox/accounts
+mkdir -p "$CODEX_HOME" "$CODEX_SWITCH_HOME"
+codex-accounts doctor
+```
+
+## Code style
+
+- **Python 3.9+** with `from __future__ import annotations`.
+- **stdlib only** in the runtime package. Dev-time deps belong in the
+  `dev` extra of `pyproject.toml`.
+- Type hints on every public function. Internal helpers are encouraged
+  to have them too.
+- Run `ruff check` and `ruff format` before opening a PR.
+- Run `pre-commit run --all-files` before opening a PR when you've touched
+  config, docs, or shell scripts.
+- Comments explain *why*, not *what*. The reviewer can read the code.
+
+## Tests
+
+- Every behavioural change ships with a test. There's no formal coverage
+  threshold, but new modules should land with smoke tests at minimum.
+- Tests must not touch a real `~/.codex/` — use the `codex_env` fixture
+  defined in `tests/conftest.py`, which isolates `CODEX_HOME` and
+  `CODEX_SWITCH_HOME` under a `tmp_path`.
+- Avoid network calls in tests. The `api` module is intentionally a thin
+  wrapper around `urllib` so it can be stubbed with `monkeypatch`.
+- Never commit real `auth.json`, SQLite snapshots, JSONL exports, or any
+  sample copied from `~/.codex/` or `~/.codex-accounts/`. Keep real debug
+  data outside the repository and use redacted fixtures only.
+
+## Commits & pull requests
+
+- Keep commits scoped and reviewable. "WIP" commits get squashed.
+- Reference an issue number in the PR description when relevant.
+- The PR description should answer:
+  1. **What** changed?
+  2. **Why** is the change needed?
+  3. **How** was it verified (commands run, scenarios tested)?
+
+## Areas where help is especially welcome
+
+- **Linux compatibility.** The code paths are mostly portable but
+  `is_codex_running()` and the install scripts are macOS-tuned. Anyone
+  running the Codex Linux client: please open issues with concrete
+  reproductions.
+- **Codex schema watchdog.** When OpenAI bumps the SQLite schema or
+  rotates the private API path, the integration breaks silently. PRs
+  that add detection or fallbacks are very welcome.
+- **Documentation translations.** We currently ship English and
+  Simplified Chinese READMEs; other languages welcome.
+
+## Releasing (maintainers)
+
+1. Update `CHANGELOG.md` — move `[Unreleased]` into a dated section.
+2. Bump `version` in `pyproject.toml` and `src/codex_switch/__init__.py`.
+3. Tag `vX.Y.Z`, push, let CI build & publish.
+
+## Code of Conduct
+
+Participation is governed by the [Contributor Covenant](./CODE_OF_CONDUCT.md).

codex_accounts-0.1.0/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_accounts-0.1.0/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,185 @@
+<!-- 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.