multi-codex 0.7.0__tar.gz → 0.9.0__tar.gz

{multi_codex-0.7.0 → multi_codex-0.9.0}/PKG-INFO

@@ -1,14 +1,22 @@
 Metadata-Version: 2.4
 Name: multi-codex
-Version: 0.7.0
+Version: 0.9.0
 Summary: Run several Codex CLI accounts side by side: separate CODEX_HOME directories, launchers and proxies.
 License: MIT
 Project-URL: Homepage, https://github.com/jakoes-wu/multi-codex
+Project-URL: Changelog, https://github.com/jakoes-wu/multi-codex/blob/main/CHANGELOG.md
+Project-URL: Issues, https://github.com/jakoes-wu/multi-codex/issues
+Keywords: codex,codex-cli,openai,multi-account,account-switcher,proxy,cli
 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.8
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Utilities
 Requires-Python: >=3.8
 Description-Content-Type: text/markdown
 License-File: LICENSE
@@ -18,6 +26,12 @@ Dynamic: license-file
 
 **English** | [简体中文](README.zh-CN.md)
 
+[![Release](https://img.shields.io/github/v/release/jakoes-wu/multi-codex)](https://github.com/jakoes-wu/multi-codex/releases)
+[![CI](https://github.com/jakoes-wu/multi-codex/actions/workflows/ci.yml/badge.svg)](https://github.com/jakoes-wu/multi-codex/actions/workflows/ci.yml)
+[![PyPI](https://img.shields.io/pypi/v/multi-codex)](https://pypi.org/project/multi-codex/)
+![Python](https://img.shields.io/badge/python-3.8%2B-blue)
+[![License: MIT](https://img.shields.io/badge/license-MIT-green)](LICENSE)
+
 Use several [Codex CLI](https://github.com/openai/codex) accounts on one machine, at the same time. Each account keeps its own login, settings, history and, if you like, its own proxy. No more logging out and in again.
 
 ```sh
@@ -26,6 +40,10 @@ codex-personal      # Codex, logged in with your personal account, in another te
 multi-codex list    # which account is logged in as whom
 ```
 
+![multi-codex demo: add two accounts and list them](https://raw.githubusercontent.com/jakoes-wu/multi-codex/main/docs/assets/demo.gif)
+
+<sub>The accounts in the demo are examples.</sub>
+
 ## How it works
 
 Codex keeps everything (settings, credentials, sessions) in one directory, `CODEX_HOME`, which is `~/.codex` by default. multi-codex gives every account its own directory and a small launcher command, `codex-<name>`, that starts Codex with that directory:
@@ -47,10 +65,12 @@ curl -fsSL https://raw.githubusercontent.com/jakoes-wu/multi-codex/main/install.
 multi-codex --version
 ```
 
-The `multi-codex` command and the `codex-<name>` launchers go to `~/.local/bin`. If your shell says `command not found`, that directory is not on your `PATH` yet; the installer prints a hint but never edits your shell profile. Add this line to `~/.zshrc` or `~/.bashrc` and open a new terminal:
+Other ways: `pipx install multi-codex` (from PyPI), or on macOS `brew install jakoes-wu/tap/multi-codex`. Either way, the `codex-<name>` launchers still go to `~/.local/bin`.
+
+The `multi-codex` command and the `codex-<name>` launchers go to `~/.local/bin`. If your shell says `command not found`, that directory is not on your `PATH` yet. The installer, `multi-codex add` and `multi-codex doctor` then print the exact command for your shell (zsh, bash or fish), but never edit your shell profile themselves. In zsh, for example, run this once (bash on macOS uses `~/.bash_profile`, bash on Linux `~/.bashrc`) and open a new terminal:
 
 ```sh
-export PATH="$HOME/.local/bin:$PATH"
+echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc
 ```
 
 In fish, run `fish_add_path ~/.local/bin` once instead.
@@ -70,7 +90,7 @@ Each command creates a directory (`~/.cx/work`) and a launcher (`codex-work`). A
 
 After `add`, multi-codex prints the next step: the login command, and a warning if `~/.local/bin` is not on your `PATH` yet. Running `multi-codex` without arguments shows these steps again.
 
-If an account should go through a proxy, give it a local port or a URL, for example `multi-codex add work --proxy 7901` (the same as `http://127.0.0.1:7901`). See [Proxy values](#proxy-values).
+If an account should go through a proxy, give it a local port or a URL, for example `multi-codex add work --proxy 7901` (the same as `http://127.0.0.1:7901`). See [Proxy values](#proxy-values). To change an existing account later, use `multi-codex set`, for example `multi-codex set work --proxy 7902`.
 
 ### 2. Log in once per account
 
@@ -91,7 +111,7 @@ codex-personal resume
 ### 4. Check that everything is right
 
 ```sh
-multi-codex list      # accounts, launcher state, logged-in e-mail and plan
+multi-codex list      # who is logged in, proxy, sharing, usage and anything that needs fixing
 multi-codex usage     # 5-hour and weekly usage; empty until you have used an account (--live asks right away)
 multi-codex doctor    # finds problems and prints the command that fixes each one
 ```
@@ -115,13 +135,14 @@ Without a name, the account is named after the e-mail address in `~/.codex/auth.
 | Open the desktop app with an account (macOS) | `multi-codex app work` | [VS Code and the desktop app](#vs-code-and-the-desktop-app-experimental) |
 | Change the account that plain `codex` and the Dock apps use | `multi-codex use work` (after `migrate-default`) | [Default account](#default-account) |
 | Always use one account inside a project | In the project directory: `multi-codex bind work`, then `multi-codex run` | [Directory bindings](#directory-bindings) |
-| Set or change an account's proxy | `multi-codex proxy work 7901` | [Proxy values](#proxy-values) |
-| Share `AGENTS.md`, skills and rules between accounts | Put them in `~/.codex-shared`, run `multi-codex init --shared-dir ~/.codex-shared`, then `multi-codex add work --shared` | [Shared resources](#shared-resources) |
+| Set or change an account's proxy | `multi-codex set work --proxy 7901` | [Proxy values](#proxy-values) |
+| Share `AGENTS.md`, skills and rules between accounts | Put them in `~/.codex-shared`, then run `multi-codex set work --shared` | [Shared resources](#shared-resources) |
 | Start a new account with another account's settings | `multi-codex add new --config-from work` | [Copying settings](#copying-settings-from-another-account) |
 | Give an account extra environment variables | `multi-codex env work KEY=VALUE` | [Environment variables](#per-account-environment-variables) |
 | Set up all accounts on a new machine | `curl -fsSL https://raw.githubusercontent.com/jakoes-wu/multi-codex/main/install.sh \| sh -s -- --config accounts.json` | [Declarative setup](#declarative-setup-with-apply) |
 | Get tab completion | `eval "$(multi-codex completion zsh)"` | [Shell completion](#shell-completion) |
 | See what a command would change | add `--dry-run` | [Commands](#commands) |
+| Rename an account | `multi-codex rename work client-a` (the directory and login stay) | [Renaming accounts](#renaming-accounts) |
 | Remove an account | `multi-codex remove work` (the directory is kept) | [Commands](#commands) |
 
 More questions are answered in the [FAQ](#faq).
@@ -139,12 +160,14 @@ More questions are answered in the [FAQ](#faq).
 | ---- | ---- |
 | `multi-codex init [--root DIR] [--bin-dir DIR] [--shared-dir DIR] [--shared-items A,B]` | Create or change global settings. |
 | `multi-codex migrate-default [NAME] [--source DIR] [--copy] [--keep-backup] [--proxy P] [--skip-process-check] [--accept-relogin]` | Turn the default directory into an account. Without NAME, the e-mail address in its `auth.json` is used. |
-| `multi-codex add NAME [--proxy P] [--shared \| --no-shared] [--adopt] [--config-from OTHER]` | Add an account, adopt an existing directory, or change its options. `--config-from` copies `config.toml` from another account once. |
+| `multi-codex add NAME [--proxy P] [--shared [DIR] \| --no-shared] [--shared-exclude ITEM] [--shared-include ITEM] [--adopt] [--config-from OTHER]` | Add an account, adopt an existing directory, or change its options. `--config-from` copies `config.toml` from another account once. |
+| `multi-codex set NAME [same options as add]` | Change an existing account; same options as `add`, but never creates one. |
+| `multi-codex rename OLD NEW` | Rename an account and its launcher; the directory, login and links stay. |
 | `multi-codex login NAME [-- ARGS]` | Run `codex login` with an account's environment; arguments after `--` go to `codex login`. Does not need `~/.local/bin` on `PATH`. |
 | `multi-codex proxy NAME PORT\|URL\|off\|inherit` | Set an account's proxy. |
 | `multi-codex remove NAME` | Unregister an account and delete its launcher. **The account directory is kept.** |
 | `multi-codex apply [-f FILE]` | Converge everything to the configuration (or to `FILE`). |
-| `multi-codex list [--json]` | Show accounts, the state of their launchers, and who is logged in. |
+| `multi-codex list [-v] [--json]` | Show accounts: who is logged in, proxy, sharing, usage and status. `-v` shows the full table. |
 | `multi-codex usage [NAME ...] [--live] [--timeout SEC] [--json]` | Show rate-limit usage. |
 | `multi-codex doctor [--json]` | Check the installation, configuration and accounts. Read-only. |
 | `multi-codex run [NAME] [-- COMMAND ...]` | Run a command (default: `codex`) with an account's environment. Without NAME, the account bound to the current directory is used. |
@@ -157,11 +180,23 @@ More questions are answered in the [FAQ](#faq).
 | `multi-codex restore NAME [--skip-process-check] [--accept-relogin]` | Undo `migrate-default`: move the account back to `~/.codex`. |
 | `multi-codex completion bash\|zsh\|fish` | Print a shell completion script. |
 
-Every write command accepts `--dry-run`. `init`, `add`, `proxy`, `remove`, `apply`, `bind`, `unbind` and `env` print only the items they change (or `already up to date`); `-v` / `--verbose` also prints unchanged items. `list`, `usage` and `doctor` never change anything; with `--json` they print a single JSON object on stdout (with a `"version": 1` field) and keep warnings on stderr. Use `--json` in scripts: the table layout is not guaranteed to stay the same.
+Every write command accepts `--dry-run`. `init`, `add`, `set`, `rename`, `proxy`, `remove`, `apply`, `bind`, `unbind` and `env` print only the items they change (or `already up to date`); `-v` / `--verbose` also prints unchanged items. For `list`, `-v` means the full table instead. `list`, `usage` and `doctor` never change anything; with `--json` they print a single JSON object on stdout (with a `"version": 1` field) and keep warnings on stderr. Use `--json` in scripts: the table layout is not guaranteed to stay the same.
 
 ### Login and usage
 
-`list` adds two columns, LOGIN and PLAN, read from each account's local `auth.json`. No token is ever printed, and nothing is sent anywhere. LOGIN is the e-mail address, `api-key`, `-` (not logged in), `keyring` (credentials are in the system keyring and cannot be read from files) or `unreadable`. PLAN is the plan recorded when the current token was issued; it is updated the next time Codex refreshes the token. If two accounts are logged in as the same ChatGPT user and workspace, `list` warns you: they share one quota.
+`list` shows one line per account:
+
+```text
+default: work
+NAME  LOGIN          PROXY                  SHARED  USAGE           STATUS
+work  w@example.com  http://127.0.0.1:7901  yes     5h 23%, 7d 41%  ok
+home  -              inherit                no      -               not logged in
+run `multi-codex doctor` for details
+```
+
+LOGIN is read from each account's local `auth.json`: the e-mail address, `api-key`, `-` (not logged in), `keyring` (credentials are in the system keyring and cannot be read from files) or `unreadable`. No token is ever printed, and nothing is sent anywhere. USAGE is the last usage snapshot in the account's local session logs, the same data as `multi-codex usage` (`reset` means the window has reset since; `*` means `sessions` is shared with other accounts, so the numbers may belong to another one). STATUS lists what needs fixing (`missing-dir`, `launcher missing`/`stale`/`conflict`, `not logged in`); `doctor` explains each problem. If two accounts are logged in as the same ChatGPT user and workspace, `list` warns you: they share one quota.
+
+`list -v` prints the full table of earlier versions: the root, launcher and shared directories, and the DIR, LAUNCHER and PLAN columns. PLAN is the plan recorded when the current token was issued; it is updated the next time Codex refreshes the token.
 
 `multi-codex usage` reads the most recent rate-limit snapshot from each account's session logs (`sessions/` and `archived_sessions/`). It is offline but can be out of date; a window that has reset since the snapshot is shown as `reset since snapshot`.
 
@@ -200,6 +235,14 @@ multi-codex unbind                             # remove the binding of the curre
 
 `multi-codex add new --config-from work` copies `config.toml` from `work` into `new` once; afterwards the two files are independent. An existing `config.toml` with different content is a conflict (nothing is written), and so is copying into an account that shares `config.toml`. The copy includes everything in the file, such as `cli_auth_credentials_store` or absolute paths that point into the other account.
 
+### Renaming accounts
+
+```sh
+multi-codex rename work client-a
+```
+
+The account and its launcher get the new name (`codex-client-a`; `codex-work` is deleted), and directory bindings and the default account follow. The directory stays where it is, so the login, sessions and shared links are kept; `config.json` records it as `"dir": "work"` (in `list --json`, `dir` is the full path instead). A name that is still used as another account's directory, such as `work` after this rename, cannot be given to a new account. Renaming only the letter case is not supported. Before downgrading to a version older than 0.9, rename the account back: older versions ignore `dir` and would use `<root>/client-a`.
+
 ### Per-account environment variables
 
 ```sh
@@ -209,6 +252,8 @@ multi-codex env work --unset TERM_PROGRAM
 multi-codex env work --clear
 ```
 
+Launchers (and `run`, `login`, `code` and `usage --live`, which use the same environment) clear `CODEX_API_KEY`, `CODEX_ACCESS_TOKEN` and `CODEX_SQLITE_HOME` inherited from your shell, so one exported API key or database location does not leak into every account. An account that needs an API key sets it here, for example `multi-codex env work CODEX_API_KEY=sk-…`; per-account variables are applied after the clearing.
+
 The variables are stored in `config.json` (`accounts.<name>.env`) and written into the launcher. Values are used literally (no `$VAR` expansion). `CODEX_HOME` and the proxy variables are reserved: use `multi-codex proxy` for proxies. A launcher with environment variables is readable only by you (mode 0700), and `list --json` shows only the variable names; still, the values are stored in plain text, so do not put secrets there that need stronger protection. Older versions of multi-codex ignore the `env` field and drop it on their next write; run `multi-codex env NAME --clear` before downgrading.
 
 ### VS Code and the desktop app (experimental)
@@ -294,7 +339,7 @@ Progress is recorded in `~/.config/multi-codex/migrate-journal.json`. If the mig
 
 Sockets and FIFOs (runtime files such as `ipc.sock`) are not copied in copy mode. On macOS, copy mode does not preserve extended attributes.
 
-If `CODEX_HOME`, `CODEX_SQLITE_HOME`, `CODEX_API_KEY` or `CODEX_ACCESS_TOKEN` is set in your environment, multi-codex warns you: these variables override or bypass per-account isolation.
+If `CODEX_HOME`, `CODEX_SQLITE_HOME`, `CODEX_API_KEY` or `CODEX_ACCESS_TOKEN` is set in your environment, multi-codex warns you: launchers set or clear them, but plain `codex` still uses them.
 
 ### Undoing a migration
 
@@ -317,13 +362,20 @@ If a migration stops with an error and you want to abandon it: the error message
 ## Shared resources
 
 ```sh
-multi-codex init --shared-dir ~/.codex-shared --shared-items AGENTS.md,skills,rules,agents
-multi-codex add work --shared
+multi-codex set work --shared
 ```
 
-Put the items you want to share into the shared directory first: items missing from it are skipped (`skip`), and nothing is linked for them. multi-codex creates the missing links and remembers which links it created. Turning sharing off removes only those links; links you made yourself are left alone. A real file or directory at a link location is a conflict and is never overwritten.
+Without a directory, `--shared` uses the shared directory already configured, or `~/.codex-shared` if none is set yet. Put the items you want to share there first: items missing from it are skipped (`skip`), and nothing is linked for them; if none of them is there, multi-codex says so. To choose which items are shared, use `multi-codex init --shared-items AGENTS.md,skills,rules,agents`.
 
-If you already linked an account to the shared directory by hand, `multi-codex add NAME --shared --adopt` takes those links over without recreating them: from then on, turning sharing off removes them as well. Only links that already point to the matching shared item are adopted.
+`--shared DIR` (for example `multi-codex set work --shared ~/my-shared`) changes the shared directory for **every** shared account, not only this one: their links move to the new directory, and links to items missing there are removed. Write the account name before `--shared`; `add --shared work` would take `work` as the directory.
+
+multi-codex creates the missing links and remembers which links it created. Turning sharing off removes only those links; links you made yourself are left alone. A real file or directory at a link location is a conflict and is never overwritten.
+
+If you already linked an account to the shared directory by hand, `multi-codex set NAME --shared --adopt` takes those links over without recreating them: from then on, turning sharing off removes them as well. Only links that already point to the matching shared item are adopted.
+
+One account can opt out of some shared items: `multi-codex set work --shared-exclude skills` removes the `skills` link multi-codex created in `work` (as if sharing were off for that item) and no longer creates it; `--shared-include skills` undoes that. Both options can be repeated, names match `shared.items` exactly, and `list` shows the exclusions as `yes (not: skills)`. To exclude `config.toml` and then copy another account's settings into it, run `--shared-exclude config.toml` and `--config-from` as two separate commands.
+
+Items that hold one account's own state can never be shared: `shared.items` must not contain the entries marked "No" in the table below. A configuration that lists one fails to load and names the item; remove it from `config.json`.
 
 ### What can be shared
 
@@ -339,7 +391,7 @@ Based on the Codex source code (openai/codex at `6b4daafd`):
 | `history.jsonl` | Prompt history | Yes | Reads and writes are file-locked; the histories of the accounts are merged. |
 | `auth.json`, `secrets/`, `.credentials.json`, `.env` | Credentials | **No** | They are the account. |
 | `installation_id` | Installation identifier | No | Sent with requests; sharing makes several accounts look like one installation. |
-| `*.sqlite` (`state_5.sqlite`, …) | Threads, logs, memories | **No** | `state_5.sqlite` records account IDs. |
+| `*.sqlite`, `*.sqlite-wal`, `*.sqlite-shm` (`state_5.sqlite`, …), `sqlite/` | Threads, logs, memories | **No** | `state_5.sqlite` records account IDs. |
 | `sessions/`, `archived_sessions/`, `session_index.jsonl` | Session logs | No | The index has only an in-process lock; sessions record the account that created them. |
 | `models_cache.json`, `cache/` | Caches | Not needed | Keyed by the account; a mismatch is a cache miss. |
 | `app-server-control/`, `app-server-daemon/`, `packages/`, `tmp/`, `.tmp/`, `log/`, `shell_snapshots/` | Runtime state | No | Per process or per session. |
@@ -402,8 +454,11 @@ Run the installer again; configuration, accounts and launchers are not touched:
 ```sh
 curl -fsSL https://raw.githubusercontent.com/jakoes-wu/multi-codex/main/install.sh | sh
 multi-codex --version
+multi-codex apply      # after upgrading from 0.8 or older: rewrites the launchers
 ```
 
+0.9 changed what the launchers contain. Until `multi-codex apply` (or any other write command) rewrites them, `list` shows `launcher stale` and `usage --live` refuses to run; the old launchers keep working.
+
 ## Exit codes
 
 | Code | Meaning |
@@ -424,7 +479,7 @@ cd multi-codex
 ./install.sh
 ```
 
-With pipx: `pipx install git+https://github.com/jakoes-wu/multi-codex`.
+With pipx: `pipx install multi-codex` (the latest release from PyPI), or `pipx install git+https://github.com/jakoes-wu/multi-codex` for the current `main` branch.
 
 The tool goes to `~/.local/share/multi-codex` and the `multi-codex` command to `~/.local/bin`. Use `--prefix DIR` to install somewhere else. Run `./install.sh --help` for all options.
 

multi_codex-0.7.0/src/multi_codex.egg-info/PKG-INFO → multi_codex-0.9.0/README.md

@@ -1,23 +1,13 @@
-Metadata-Version: 2.4
-Name: multi-codex
-Version: 0.7.0
-Summary: Run several Codex CLI accounts side by side: separate CODEX_HOME directories, launchers and proxies.
-License: MIT
-Project-URL: Homepage, https://github.com/jakoes-wu/multi-codex
-Classifier: Environment :: Console
-Classifier: License :: OSI Approved :: MIT License
-Classifier: Operating System :: MacOS
-Classifier: Operating System :: POSIX :: Linux
-Classifier: Programming Language :: Python :: 3
-Requires-Python: >=3.8
-Description-Content-Type: text/markdown
-License-File: LICENSE
-Dynamic: license-file
-
 # multi-codex
 
 **English** | [简体中文](README.zh-CN.md)
 
+[![Release](https://img.shields.io/github/v/release/jakoes-wu/multi-codex)](https://github.com/jakoes-wu/multi-codex/releases)
+[![CI](https://github.com/jakoes-wu/multi-codex/actions/workflows/ci.yml/badge.svg)](https://github.com/jakoes-wu/multi-codex/actions/workflows/ci.yml)
+[![PyPI](https://img.shields.io/pypi/v/multi-codex)](https://pypi.org/project/multi-codex/)
+![Python](https://img.shields.io/badge/python-3.8%2B-blue)
+[![License: MIT](https://img.shields.io/badge/license-MIT-green)](LICENSE)
+
 Use several [Codex CLI](https://github.com/openai/codex) accounts on one machine, at the same time. Each account keeps its own login, settings, history and, if you like, its own proxy. No more logging out and in again.
 
 ```sh
@@ -26,6 +16,10 @@ codex-personal      # Codex, logged in with your personal account, in another te
 multi-codex list    # which account is logged in as whom
 ```
 
+![multi-codex demo: add two accounts and list them](https://raw.githubusercontent.com/jakoes-wu/multi-codex/main/docs/assets/demo.gif)
+
+<sub>The accounts in the demo are examples.</sub>
+
 ## How it works
 
 Codex keeps everything (settings, credentials, sessions) in one directory, `CODEX_HOME`, which is `~/.codex` by default. multi-codex gives every account its own directory and a small launcher command, `codex-<name>`, that starts Codex with that directory:
@@ -47,10 +41,12 @@ curl -fsSL https://raw.githubusercontent.com/jakoes-wu/multi-codex/main/install.
 multi-codex --version
 ```
 
-The `multi-codex` command and the `codex-<name>` launchers go to `~/.local/bin`. If your shell says `command not found`, that directory is not on your `PATH` yet; the installer prints a hint but never edits your shell profile. Add this line to `~/.zshrc` or `~/.bashrc` and open a new terminal:
+Other ways: `pipx install multi-codex` (from PyPI), or on macOS `brew install jakoes-wu/tap/multi-codex`. Either way, the `codex-<name>` launchers still go to `~/.local/bin`.
+
+The `multi-codex` command and the `codex-<name>` launchers go to `~/.local/bin`. If your shell says `command not found`, that directory is not on your `PATH` yet. The installer, `multi-codex add` and `multi-codex doctor` then print the exact command for your shell (zsh, bash or fish), but never edit your shell profile themselves. In zsh, for example, run this once (bash on macOS uses `~/.bash_profile`, bash on Linux `~/.bashrc`) and open a new terminal:
 
 ```sh
-export PATH="$HOME/.local/bin:$PATH"
+echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc
 ```
 
 In fish, run `fish_add_path ~/.local/bin` once instead.
@@ -70,7 +66,7 @@ Each command creates a directory (`~/.cx/work`) and a launcher (`codex-work`). A
 
 After `add`, multi-codex prints the next step: the login command, and a warning if `~/.local/bin` is not on your `PATH` yet. Running `multi-codex` without arguments shows these steps again.
 
-If an account should go through a proxy, give it a local port or a URL, for example `multi-codex add work --proxy 7901` (the same as `http://127.0.0.1:7901`). See [Proxy values](#proxy-values).
+If an account should go through a proxy, give it a local port or a URL, for example `multi-codex add work --proxy 7901` (the same as `http://127.0.0.1:7901`). See [Proxy values](#proxy-values). To change an existing account later, use `multi-codex set`, for example `multi-codex set work --proxy 7902`.
 
 ### 2. Log in once per account
 
@@ -91,7 +87,7 @@ codex-personal resume
 ### 4. Check that everything is right
 
 ```sh
-multi-codex list      # accounts, launcher state, logged-in e-mail and plan
+multi-codex list      # who is logged in, proxy, sharing, usage and anything that needs fixing
 multi-codex usage     # 5-hour and weekly usage; empty until you have used an account (--live asks right away)
 multi-codex doctor    # finds problems and prints the command that fixes each one
 ```
@@ -115,13 +111,14 @@ Without a name, the account is named after the e-mail address in `~/.codex/auth.
 | Open the desktop app with an account (macOS) | `multi-codex app work` | [VS Code and the desktop app](#vs-code-and-the-desktop-app-experimental) |
 | Change the account that plain `codex` and the Dock apps use | `multi-codex use work` (after `migrate-default`) | [Default account](#default-account) |
 | Always use one account inside a project | In the project directory: `multi-codex bind work`, then `multi-codex run` | [Directory bindings](#directory-bindings) |
-| Set or change an account's proxy | `multi-codex proxy work 7901` | [Proxy values](#proxy-values) |
-| Share `AGENTS.md`, skills and rules between accounts | Put them in `~/.codex-shared`, run `multi-codex init --shared-dir ~/.codex-shared`, then `multi-codex add work --shared` | [Shared resources](#shared-resources) |
+| Set or change an account's proxy | `multi-codex set work --proxy 7901` | [Proxy values](#proxy-values) |
+| Share `AGENTS.md`, skills and rules between accounts | Put them in `~/.codex-shared`, then run `multi-codex set work --shared` | [Shared resources](#shared-resources) |
 | Start a new account with another account's settings | `multi-codex add new --config-from work` | [Copying settings](#copying-settings-from-another-account) |
 | Give an account extra environment variables | `multi-codex env work KEY=VALUE` | [Environment variables](#per-account-environment-variables) |
 | Set up all accounts on a new machine | `curl -fsSL https://raw.githubusercontent.com/jakoes-wu/multi-codex/main/install.sh \| sh -s -- --config accounts.json` | [Declarative setup](#declarative-setup-with-apply) |
 | Get tab completion | `eval "$(multi-codex completion zsh)"` | [Shell completion](#shell-completion) |
 | See what a command would change | add `--dry-run` | [Commands](#commands) |
+| Rename an account | `multi-codex rename work client-a` (the directory and login stay) | [Renaming accounts](#renaming-accounts) |
 | Remove an account | `multi-codex remove work` (the directory is kept) | [Commands](#commands) |
 
 More questions are answered in the [FAQ](#faq).
@@ -139,12 +136,14 @@ More questions are answered in the [FAQ](#faq).
 | ---- | ---- |
 | `multi-codex init [--root DIR] [--bin-dir DIR] [--shared-dir DIR] [--shared-items A,B]` | Create or change global settings. |
 | `multi-codex migrate-default [NAME] [--source DIR] [--copy] [--keep-backup] [--proxy P] [--skip-process-check] [--accept-relogin]` | Turn the default directory into an account. Without NAME, the e-mail address in its `auth.json` is used. |
-| `multi-codex add NAME [--proxy P] [--shared \| --no-shared] [--adopt] [--config-from OTHER]` | Add an account, adopt an existing directory, or change its options. `--config-from` copies `config.toml` from another account once. |
+| `multi-codex add NAME [--proxy P] [--shared [DIR] \| --no-shared] [--shared-exclude ITEM] [--shared-include ITEM] [--adopt] [--config-from OTHER]` | Add an account, adopt an existing directory, or change its options. `--config-from` copies `config.toml` from another account once. |
+| `multi-codex set NAME [same options as add]` | Change an existing account; same options as `add`, but never creates one. |
+| `multi-codex rename OLD NEW` | Rename an account and its launcher; the directory, login and links stay. |
 | `multi-codex login NAME [-- ARGS]` | Run `codex login` with an account's environment; arguments after `--` go to `codex login`. Does not need `~/.local/bin` on `PATH`. |
 | `multi-codex proxy NAME PORT\|URL\|off\|inherit` | Set an account's proxy. |
 | `multi-codex remove NAME` | Unregister an account and delete its launcher. **The account directory is kept.** |
 | `multi-codex apply [-f FILE]` | Converge everything to the configuration (or to `FILE`). |
-| `multi-codex list [--json]` | Show accounts, the state of their launchers, and who is logged in. |
+| `multi-codex list [-v] [--json]` | Show accounts: who is logged in, proxy, sharing, usage and status. `-v` shows the full table. |
 | `multi-codex usage [NAME ...] [--live] [--timeout SEC] [--json]` | Show rate-limit usage. |
 | `multi-codex doctor [--json]` | Check the installation, configuration and accounts. Read-only. |
 | `multi-codex run [NAME] [-- COMMAND ...]` | Run a command (default: `codex`) with an account's environment. Without NAME, the account bound to the current directory is used. |
@@ -157,11 +156,23 @@ More questions are answered in the [FAQ](#faq).
 | `multi-codex restore NAME [--skip-process-check] [--accept-relogin]` | Undo `migrate-default`: move the account back to `~/.codex`. |
 | `multi-codex completion bash\|zsh\|fish` | Print a shell completion script. |
 
-Every write command accepts `--dry-run`. `init`, `add`, `proxy`, `remove`, `apply`, `bind`, `unbind` and `env` print only the items they change (or `already up to date`); `-v` / `--verbose` also prints unchanged items. `list`, `usage` and `doctor` never change anything; with `--json` they print a single JSON object on stdout (with a `"version": 1` field) and keep warnings on stderr. Use `--json` in scripts: the table layout is not guaranteed to stay the same.
+Every write command accepts `--dry-run`. `init`, `add`, `set`, `rename`, `proxy`, `remove`, `apply`, `bind`, `unbind` and `env` print only the items they change (or `already up to date`); `-v` / `--verbose` also prints unchanged items. For `list`, `-v` means the full table instead. `list`, `usage` and `doctor` never change anything; with `--json` they print a single JSON object on stdout (with a `"version": 1` field) and keep warnings on stderr. Use `--json` in scripts: the table layout is not guaranteed to stay the same.
 
 ### Login and usage
 
-`list` adds two columns, LOGIN and PLAN, read from each account's local `auth.json`. No token is ever printed, and nothing is sent anywhere. LOGIN is the e-mail address, `api-key`, `-` (not logged in), `keyring` (credentials are in the system keyring and cannot be read from files) or `unreadable`. PLAN is the plan recorded when the current token was issued; it is updated the next time Codex refreshes the token. If two accounts are logged in as the same ChatGPT user and workspace, `list` warns you: they share one quota.
+`list` shows one line per account:
+
+```text
+default: work
+NAME  LOGIN          PROXY                  SHARED  USAGE           STATUS
+work  w@example.com  http://127.0.0.1:7901  yes     5h 23%, 7d 41%  ok
+home  -              inherit                no      -               not logged in
+run `multi-codex doctor` for details
+```
+
+LOGIN is read from each account's local `auth.json`: the e-mail address, `api-key`, `-` (not logged in), `keyring` (credentials are in the system keyring and cannot be read from files) or `unreadable`. No token is ever printed, and nothing is sent anywhere. USAGE is the last usage snapshot in the account's local session logs, the same data as `multi-codex usage` (`reset` means the window has reset since; `*` means `sessions` is shared with other accounts, so the numbers may belong to another one). STATUS lists what needs fixing (`missing-dir`, `launcher missing`/`stale`/`conflict`, `not logged in`); `doctor` explains each problem. If two accounts are logged in as the same ChatGPT user and workspace, `list` warns you: they share one quota.
+
+`list -v` prints the full table of earlier versions: the root, launcher and shared directories, and the DIR, LAUNCHER and PLAN columns. PLAN is the plan recorded when the current token was issued; it is updated the next time Codex refreshes the token.
 
 `multi-codex usage` reads the most recent rate-limit snapshot from each account's session logs (`sessions/` and `archived_sessions/`). It is offline but can be out of date; a window that has reset since the snapshot is shown as `reset since snapshot`.
 
@@ -200,6 +211,14 @@ multi-codex unbind                             # remove the binding of the curre
 
 `multi-codex add new --config-from work` copies `config.toml` from `work` into `new` once; afterwards the two files are independent. An existing `config.toml` with different content is a conflict (nothing is written), and so is copying into an account that shares `config.toml`. The copy includes everything in the file, such as `cli_auth_credentials_store` or absolute paths that point into the other account.
 
+### Renaming accounts
+
+```sh
+multi-codex rename work client-a
+```
+
+The account and its launcher get the new name (`codex-client-a`; `codex-work` is deleted), and directory bindings and the default account follow. The directory stays where it is, so the login, sessions and shared links are kept; `config.json` records it as `"dir": "work"` (in `list --json`, `dir` is the full path instead). A name that is still used as another account's directory, such as `work` after this rename, cannot be given to a new account. Renaming only the letter case is not supported. Before downgrading to a version older than 0.9, rename the account back: older versions ignore `dir` and would use `<root>/client-a`.
+
 ### Per-account environment variables
 
 ```sh
@@ -209,6 +228,8 @@ multi-codex env work --unset TERM_PROGRAM
 multi-codex env work --clear
 ```
 
+Launchers (and `run`, `login`, `code` and `usage --live`, which use the same environment) clear `CODEX_API_KEY`, `CODEX_ACCESS_TOKEN` and `CODEX_SQLITE_HOME` inherited from your shell, so one exported API key or database location does not leak into every account. An account that needs an API key sets it here, for example `multi-codex env work CODEX_API_KEY=sk-…`; per-account variables are applied after the clearing.
+
 The variables are stored in `config.json` (`accounts.<name>.env`) and written into the launcher. Values are used literally (no `$VAR` expansion). `CODEX_HOME` and the proxy variables are reserved: use `multi-codex proxy` for proxies. A launcher with environment variables is readable only by you (mode 0700), and `list --json` shows only the variable names; still, the values are stored in plain text, so do not put secrets there that need stronger protection. Older versions of multi-codex ignore the `env` field and drop it on their next write; run `multi-codex env NAME --clear` before downgrading.
 
 ### VS Code and the desktop app (experimental)
@@ -294,7 +315,7 @@ Progress is recorded in `~/.config/multi-codex/migrate-journal.json`. If the mig
 
 Sockets and FIFOs (runtime files such as `ipc.sock`) are not copied in copy mode. On macOS, copy mode does not preserve extended attributes.
 
-If `CODEX_HOME`, `CODEX_SQLITE_HOME`, `CODEX_API_KEY` or `CODEX_ACCESS_TOKEN` is set in your environment, multi-codex warns you: these variables override or bypass per-account isolation.
+If `CODEX_HOME`, `CODEX_SQLITE_HOME`, `CODEX_API_KEY` or `CODEX_ACCESS_TOKEN` is set in your environment, multi-codex warns you: launchers set or clear them, but plain `codex` still uses them.
 
 ### Undoing a migration
 
@@ -317,13 +338,20 @@ If a migration stops with an error and you want to abandon it: the error message
 ## Shared resources
 
 ```sh
-multi-codex init --shared-dir ~/.codex-shared --shared-items AGENTS.md,skills,rules,agents
-multi-codex add work --shared
+multi-codex set work --shared
 ```
 
-Put the items you want to share into the shared directory first: items missing from it are skipped (`skip`), and nothing is linked for them. multi-codex creates the missing links and remembers which links it created. Turning sharing off removes only those links; links you made yourself are left alone. A real file or directory at a link location is a conflict and is never overwritten.
+Without a directory, `--shared` uses the shared directory already configured, or `~/.codex-shared` if none is set yet. Put the items you want to share there first: items missing from it are skipped (`skip`), and nothing is linked for them; if none of them is there, multi-codex says so. To choose which items are shared, use `multi-codex init --shared-items AGENTS.md,skills,rules,agents`.
 
-If you already linked an account to the shared directory by hand, `multi-codex add NAME --shared --adopt` takes those links over without recreating them: from then on, turning sharing off removes them as well. Only links that already point to the matching shared item are adopted.
+`--shared DIR` (for example `multi-codex set work --shared ~/my-shared`) changes the shared directory for **every** shared account, not only this one: their links move to the new directory, and links to items missing there are removed. Write the account name before `--shared`; `add --shared work` would take `work` as the directory.
+
+multi-codex creates the missing links and remembers which links it created. Turning sharing off removes only those links; links you made yourself are left alone. A real file or directory at a link location is a conflict and is never overwritten.
+
+If you already linked an account to the shared directory by hand, `multi-codex set NAME --shared --adopt` takes those links over without recreating them: from then on, turning sharing off removes them as well. Only links that already point to the matching shared item are adopted.
+
+One account can opt out of some shared items: `multi-codex set work --shared-exclude skills` removes the `skills` link multi-codex created in `work` (as if sharing were off for that item) and no longer creates it; `--shared-include skills` undoes that. Both options can be repeated, names match `shared.items` exactly, and `list` shows the exclusions as `yes (not: skills)`. To exclude `config.toml` and then copy another account's settings into it, run `--shared-exclude config.toml` and `--config-from` as two separate commands.
+
+Items that hold one account's own state can never be shared: `shared.items` must not contain the entries marked "No" in the table below. A configuration that lists one fails to load and names the item; remove it from `config.json`.
 
 ### What can be shared
 
@@ -339,7 +367,7 @@ Based on the Codex source code (openai/codex at `6b4daafd`):
 | `history.jsonl` | Prompt history | Yes | Reads and writes are file-locked; the histories of the accounts are merged. |
 | `auth.json`, `secrets/`, `.credentials.json`, `.env` | Credentials | **No** | They are the account. |
 | `installation_id` | Installation identifier | No | Sent with requests; sharing makes several accounts look like one installation. |
-| `*.sqlite` (`state_5.sqlite`, …) | Threads, logs, memories | **No** | `state_5.sqlite` records account IDs. |
+| `*.sqlite`, `*.sqlite-wal`, `*.sqlite-shm` (`state_5.sqlite`, …), `sqlite/` | Threads, logs, memories | **No** | `state_5.sqlite` records account IDs. |
 | `sessions/`, `archived_sessions/`, `session_index.jsonl` | Session logs | No | The index has only an in-process lock; sessions record the account that created them. |
 | `models_cache.json`, `cache/` | Caches | Not needed | Keyed by the account; a mismatch is a cache miss. |
 | `app-server-control/`, `app-server-daemon/`, `packages/`, `tmp/`, `.tmp/`, `log/`, `shell_snapshots/` | Runtime state | No | Per process or per session. |
@@ -402,8 +430,11 @@ Run the installer again; configuration, accounts and launchers are not touched:
 ```sh
 curl -fsSL https://raw.githubusercontent.com/jakoes-wu/multi-codex/main/install.sh | sh
 multi-codex --version
+multi-codex apply      # after upgrading from 0.8 or older: rewrites the launchers
 ```
 
+0.9 changed what the launchers contain. Until `multi-codex apply` (or any other write command) rewrites them, `list` shows `launcher stale` and `usage --live` refuses to run; the old launchers keep working.
+
 ## Exit codes
 
 | Code | Meaning |
@@ -424,7 +455,7 @@ cd multi-codex
 ./install.sh
 ```
 
-With pipx: `pipx install git+https://github.com/jakoes-wu/multi-codex`.
+With pipx: `pipx install multi-codex` (the latest release from PyPI), or `pipx install git+https://github.com/jakoes-wu/multi-codex` for the current `main` branch.
 
 The tool goes to `~/.local/share/multi-codex` and the `multi-codex` command to `~/.local/bin`. Use `--prefix DIR` to install somewhere else. Run `./install.sh --help` for all options.
 

{multi_codex-0.7.0 → multi_codex-0.9.0}/pyproject.toml

@@ -9,12 +9,18 @@ description = "Run several Codex CLI accounts side by side: separate CODEX_HOME
 readme = "README.md"
 license = {text = "MIT"}
 requires-python = ">=3.8"
+keywords = ["codex", "codex-cli", "openai", "multi-account", "account-switcher", "proxy", "cli"]
 classifiers = [
     "Environment :: Console",
+    "Intended Audience :: Developers",
     "License :: OSI Approved :: MIT License",
     "Operating System :: MacOS",
     "Operating System :: POSIX :: Linux",
     "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.8",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Utilities",
 ]
 
 [project.scripts]
@@ -22,6 +28,8 @@ multi-codex = "multi_codex.cli:main"
 
 [project.urls]
 Homepage = "https://github.com/jakoes-wu/multi-codex"
+Changelog = "https://github.com/jakoes-wu/multi-codex/blob/main/CHANGELOG.md"
+Issues = "https://github.com/jakoes-wu/multi-codex/issues"
 
 [tool.setuptools.dynamic]
 version = {attr = "multi_codex.__version__"}

{multi_codex-0.7.0 → multi_codex-0.9.0}/src/multi_codex/__init__.py

@@ -1,3 +1,3 @@
 """multi-codex：管理多个 Codex CLI 账号目录、启动命令与代理设置。"""
 
-__version__ = "0.7.0"
+__version__ = "0.9.0"

{multi_codex-0.7.0 → multi_codex-0.9.0}/src/multi_codex/accounts.py

@@ -32,7 +32,27 @@ NO_ORPHANS: FrozenSet[str] = frozenset()
 
 
 def account_dir(config: Config, name: str) -> str:
-    return os.path.join(expand(config.root), name)
+    """账号目录。用账号记录的目录名（rename 后与账号名不同）；未登记的名字按名字本身拼。"""
+    account = config.find(name)
+    return os.path.join(expand(config.root), account.dir_name if account is not None else name)
+
+
+def dir_conflicts(config: Config) -> List[str]:
+    """两个账号会落到同一个目录时的说明文字（规则同 config._check_dir_names）。
+
+    parse_config 只检查读入的文件；这里检查命令算出的新配置，典型是 rename work job 之后 add work。
+    """
+    problems = []
+    for account in config.accounts.values():
+        for other in config.accounts.values():
+            if other is account:
+                continue
+            if account.dir_name.casefold() == other.dir_name.casefold() or \
+                    account.name.casefold() == other.dir_name.casefold():
+                problems.append("account {!r} would use the directory of account {!r}".format(
+                    account.name, other.name))
+                break
+    return problems
 
 
 def plan(old: Config, new: Config, *, config_exists: bool = True,
@@ -60,6 +80,9 @@ def plan(old: Config, new: Config, *, config_exists: bool = True,
                               "cannot change root from {} to {} while accounts are registered".format(
                                   old_root, new_root)))
 
+    for problem in dir_conflicts(new):
+        actions.append(Action(CONFLICT, "config", config_path(), problem))
+
     planned_deletes: Set[str] = set()
     for account in new.accounts.values():
         old_account = old.find(account.name)
@@ -70,7 +93,7 @@ def plan(old: Config, new: Config, *, config_exists: bool = True,
                                   "account {!r} is registered as {!r}; renaming is not supported".format(
                                       account.name, old_account.name)))
             continue
-        directory = os.path.join(new_root, account.name)
+        directory = os.path.join(new_root, account.dir_name)
         actions.extend(_plan_account_dir(directory, assumed))
         actions.extend(_plan_launcher(new_bin, account.name, directory, account.proxy, account.env))
         if old_account is not None and old_bin != new_bin:
@@ -79,11 +102,15 @@ def plan(old: Config, new: Config, *, config_exists: bool = True,
         actions.extend(shared.plan_shared(new, account, directory, old.shared_dir,
                                           adopt=account.name.casefold() in adopt_accounts))
 
+    new_dirs = {account.dir_name.casefold() for account in new.accounts.values()}
     for old_account in old.accounts.values():
         if new.find(old_account.name) is None:
             actions.extend(_plan_launcher_delete(old_bin, old_account.name, planned_deletes,
                                                  "account removed"))
-            actions.extend(shared.plan_remove_links(old_account, os.path.join(old_root, old_account.name),
+            # rename：旧名字从配置里消失，但目录由新名字接着用，共享链接必须留着。
+            if old_account.dir_name.casefold() in new_dirs:
+                continue
+            actions.extend(shared.plan_remove_links(old_account, os.path.join(old_root, old_account.dir_name),
                                                     old.shared_dir))
 
     if orphan_scope:
@@ -121,7 +148,7 @@ def plan_config_copy(config: Config, account: Account, content: str, source_name
     已有不同内容时不覆盖：那可能是用户已经改过的配置。
     """
     target = os.path.join(account_dir(config, account.name), "config.toml")
-    if account.shared and "config.toml" in config.shared_items:
+    if account.shared and "config.toml" in config.shared_items and "config.toml" not in account.shared_exclude:
         return [Action(CONFLICT, "config-file", target,
                        "config.toml is shared for this account and does not need copying")]
     kind = entry_kind(target)

{multi_codex-0.7.0 → multi_codex-0.9.0}/src/multi_codex/apps.py

@@ -33,15 +33,18 @@ def _private_dir(path: str) -> str:
     return path
 
 
-def gui_data_dir(config: Config, name: str, kind: str) -> str:
-    """返回并创建 <root>/.apps/<名>/<kind>（kind 为 vscode 或 desktop），各级目录都只允许本人访问。"""
+def gui_data_dir(config: Config, dir_name: str, kind: str) -> str:
+    """返回并创建 <root>/.apps/<账号目录名>/<kind>（kind 为 vscode 或 desktop），各级目录都只允许本人访问。
+
+    按目录名而不是账号名存放：rename 后 VS Code 与桌面端的登录状态、窗口与扩展数据都还在原处。
+    """
     apps_root = _private_dir(os.path.join(expand(config.root), ".apps"))
-    account_root = _private_dir(os.path.join(apps_root, name))
+    account_root = _private_dir(os.path.join(apps_root, dir_name))
     return _private_dir(os.path.join(account_root, kind))
 
 
-def desktop_log(config: Config, name: str) -> str:
-    path = os.path.join(expand(config.root), ".apps", name, "desktop.log")
+def desktop_log(config: Config, dir_name: str) -> str:
+    path = os.path.join(expand(config.root), ".apps", dir_name, "desktop.log")
     fd = os.open(path, os.O_CREAT | os.O_APPEND | os.O_WRONLY, 0o600)
     os.close(fd)
     os.chmod(path, 0o600)