multi-claude-cli 0.8.0__tar.gz → 0.9.1__tar.gz

{multi_claude_cli-0.8.0 → multi_claude_cli-0.9.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: multi-claude-cli
-Version: 0.8.0
+Version: 0.9.1
 Summary: Run several Claude Code accounts side by side: separate CLAUDE_CONFIG_DIR directories, launchers, proxies, environment variables and arguments.
 License: MIT
 Project-URL: Homepage, https://github.com/jakoes-wu/multi-claude
@@ -37,7 +37,7 @@ Dynamic: license-file
 
 Use several [Claude Code](https://code.claude.com/docs) accounts on one machine, at the same time. Each account keeps its own login, settings and history and, if you like, its own proxy. No more logging out and in again.
 
-It never reads your login, never connects to the network and never edits your shell startup files.
+It never copies or exports your login and never edits your shell startup files. Only `list` reads an account's access token and goes online, to ask Anthropic for the current plan (renewing the token first if it has expired); `list --offline` skips all of that.
 
 ```sh
 claude-work        # Claude Code with your work account
@@ -64,8 +64,8 @@ The launchers are plain shell scripts. They keep working even if you uninstall m
 
 ## Features
 
-- **Never reads your login** — the only keychain call checks whether an item exists; the contents of keychain items and `.credentials.json` are never opened. `migrate-default` and `restore` move whole account directories, and on Linux the credentials file moves with its directory without being opened.
-- **No network** — multi-claude itself makes no network connections: no telemetry, no usage reporting, no update checks. Only the installer, pipx or Homebrew download the package.
+- **Your login stays yours** — logins are never copied or exported. One command touches them: `list` takes each account's access token (from the keychain, or `.credentials.json` on Linux) to ask Anthropic which plan the account is on, and when that token has expired it renews it the way Claude Code does and saves the new one in the same place. Tokens stay in memory and go only to Anthropic (`api.anthropic.com`, and `platform.claude.com` for a renewal), through that account's proxy. `list --no-refresh` never writes, `list --offline` reads nothing. Every other command only checks whether a login exists. `migrate-default` and `restore` move whole account directories, and on Linux the credentials file moves with its directory without being opened.
+- **Only `list` goes online** — its plan lookup (one request per account, plus one to renew an expired token) is the only connection multi-claude makes: no telemetry, no usage reporting, no update checks. `list --offline` makes none. Only the installer, pipx or Homebrew download the package.
 - **Leaves your shell alone** — when `PATH` needs a change, it prints the line to add instead of editing `~/.zshrc` or `~/.bashrc`.
 - **Changes only what you ask** — it writes its own configuration and state, the launchers, account directories (including the VS Code data that `code` keeps in `<root>/.apps`) and shared links. A Claude Code settings file is changed only by `statusline install` (the file you name, with a backup) and `add --config-from` (the new account's `settings.json`).
 - **Migrate the default account** — move your existing `~/.claude` into the account root without logging out. `claude` keeps working exactly as before.
@@ -76,11 +76,31 @@ The launchers are plain shell scripts. They keep working even if you uninstall m
 - **Idempotent** — every command can be re-run safely. Write commands print only what changes (`--verbose` lists everything); conflicts with files multi-claude does not own are reported without changing anything; an interrupted migration resumes where it stopped.
 - **Optional shared resources** — link `CLAUDE.md`, `skills`, `agents` and `commands` from one shared directory into selected accounts.
 
-## Requirements
+## Prerequisites
 
-- macOS or Linux (Windows is planned; inside WSL, use the Linux instructions)
-- Python 3.8 or newer (standard library only)
-- Claude Code (`claude`) on your `PATH`
+**Servers.** None. multi-claude runs only on your own computer; its only network requests are the plan lookups and token renewals of `list`, sent to Anthropic.
+
+**Your computer.**
+
+| | Needed | Optional |
+| ---- | ---- | ---- |
+| Operating system | macOS or Linux (WSL counts as Linux) | — |
+| Tools | Python 3.8+ (`python3`, standard library only); Claude Code (`claude`); `curl` or `wget`, and `tar`, for the installer | `pipx` or Homebrew, to install from PyPI or the tap; `lsof`, so that `migrate-default` and `restore` can find processes using `~/.claude` (Linux falls back to `/proc`); VS Code's `code` command, for `multi-claude code` |
+
+Install what is missing:
+
+```sh
+# macOS (with Homebrew, https://brew.sh); curl, tar and lsof come with macOS
+brew install python
+curl -fsSL https://claude.ai/install.sh | bash    # Claude Code, if you do not have it yet
+
+# Debian / Ubuntu / WSL
+sudo apt update
+sudo apt install -y python3 curl tar lsof
+curl -fsSL https://claude.ai/install.sh | bash    # Claude Code, if you do not have it yet
+```
+
+Windows itself is not supported yet; use WSL. Other ways to install Claude Code: https://code.claude.com/docs/en/setup
 
 ## Installation
 
@@ -261,7 +281,7 @@ work   23% 14:00  41% Fri  12m ago
 home   -          -        no data (start claude-home once)
 ```
 
-The numbers are the last values Claude Code itself cached in the account's `.claude.json` (for the default identity, `~/.claude.json`). multi-claude never reads credentials and never calls the network, so the data can be old: `UPDATED` shows its age, and values older than an hour are marked `stale`. Claude Code writes this cache itself; when it refreshes it is not documented. A window whose reset time has passed shows `reset`.
+The numbers are the last values Claude Code itself cached in the account's `.claude.json` (for the default identity, `~/.claude.json`). `usage` never reads credentials and never calls the network, so the data can be old: `UPDATED` shows its age, and values older than an hour are marked `stale`. Claude Code writes this cache itself; when it refreshes it is not documented. A window whose reset time has passed shows `reset`.
 
 For fresher numbers, let your status line record them. Claude Code passes the 5-hour and 7-day usage to the `statusLine` command each time it redraws the status line (Pro and Max plans, after the first response of a session). Wrap the `statusLine` command of the settings file that is actually in effect:
 
@@ -293,6 +313,24 @@ work:
 
 `list` shows when each account was last used (`LAST USED`), from the newest session file or prompt history in its directory; a `handoff` into an account counts as use.
 
+#### Plan and billing
+
+```text
+NAME   LOGIN     PLAN      BILLING      PROXY                  SHARED  5H         7D       LAST USED  STATUS
+work   keychain  max (5x)  stripe       http://127.0.0.1:7890  no      23% 14:00  41% Fri  5m ago     ok
+home   keychain  pro       apple        inherit                no      -          -        2d ago     ok
+old    keychain  token expired  -       inherit                no      -          -        9d ago     ok
+```
+
+`PLAN` and `BILLING` are not cached values: every `list` asks Anthropic (`GET https://api.anthropic.com/api/oauth/profile`, the request Claude Code itself makes) with the account's own access token. `PLAN` is the subscription — `pro`, `max (5x)`, `max (20x)`, `team`, `enterprise`. `BILLING` is where the subscription is paid: `stripe` (claude.ai), `apple` (App Store), `google-play`, `aws-marketplace` and so on.
+
+- The request uses the account's proxy setting, exactly like its launcher: the configured proxy, the proxy variables of your shell for `inherit`, none for `off`. If a proxy is configured and fails, the lookup fails; it never falls back to a direct connection. Only `http://` proxies work for the lookup.
+- Access tokens last a few hours. When one has expired, `list` renews it first: it takes the same lock as Claude Code (`.oauth_refresh.lock` in the account directory), posts the refresh token to `https://platform.claude.com/v1/oauth/token`, and saves the new tokens where the old ones were, keeping everything else in the login untouched. A running Claude session picks the new token up by itself. If another process has just renewed the token, `list` uses that result and writes nothing; if another process holds the lock, `list` does not wait and shows `token expired` this time. This follows what Claude Code 2.1.295 does; it is not a documented interface.
+- `token expired` means the access token has run out and could not be renewed; the subscription itself is not affected. The reason is on stderr (`token refresh failed for work: lock_busy`). Start `claude-NAME` once and run `list` again; when the reason is `refresh_rejected` or `no_refresh_token`, log in again with `multi-claude login NAME`. `list --no-refresh` never renews and never writes to a login.
+- `-` means the account has no OAuth login, and `rejected` that the server refused the token.
+- `error` comes with a reason on stderr, for example `plan lookup failed for work: timeout (via 127.0.0.1:7890, 10.01s)`. `tls_failed` usually means the Python that runs multi-claude has no root certificates (python.org installers ship an `Install Certificates.command`).
+- `list --offline` skips the lookup — no token is read, nothing is sent — and prints the table without the two columns. `list --json` carries the same data in each account's `plan` object (`refresh` tells whether a token was renewed); scripts should use it instead of parsing the table. The lookup adds about a second, at most 15; a renewal that is under way is allowed to finish first (the first Ctrl-C only prints a notice), so that the new login is not lost.
+
 ### Handing a session over to another account
 
 Each account keeps its own sessions, so `claude --resume` in one account cannot see the sessions of another. `handoff` copies one session (its `.jsonl` file and the folder next to it with subagent transcripts and saved tool output) into the same project folder of another account:
@@ -427,7 +465,7 @@ By default the numbers come from the cache that Claude Code writes in `.claude.j
 
 ### Does multi-claude read or copy my login?
 
-It never reads it: its only keychain call checks whether an item exists, and it never opens `.credentials.json`. It does not export, upload or back up logins. `migrate-default` and `restore` move a whole account directory; on Linux the credentials file is inside it and moves with it (in copy mode it is copied as part of the directory, verified, and the original directory is then removed unless you pass `--keep-backup`), still without being opened. On macOS a login is tied to the account directory's path, which is why `rename` keeps the directory.
+It never copies, exports, uploads or backs up a login. One command touches one: `list` takes each account's access token to ask Anthropic for the account's plan, and renews the token when it has expired, saving the new one where the old one was (see [Plan and billing](#plan-and-billing)). Tokens stay in memory and are sent only to Anthropic. `list --no-refresh` never writes and `list --offline` does not read. All other commands only check whether a login exists. `migrate-default` and `restore` move a whole account directory; on Linux the credentials file is inside it and moves with it (in copy mode it is copied as part of the directory, verified, and the original directory is then removed unless you pass `--keep-backup`), still without being opened. On macOS a login is tied to the account directory's path, which is why `rename` keeps the directory.
 
 ## Reference
 
@@ -447,7 +485,7 @@ It never reads it: its only keychain call checks whether an item exists, and it
 | `multi-claude args (NAME \| --defaults) -- [ARG ...]` | Replace the fixed arguments; `--` with nothing after it clears them. |
 | `multi-claude remove NAME` | Unregister an account and delete its launcher. **The directory and the login are kept.** |
 | `multi-claude apply [-f FILE]` | Converge everything to the configuration (or to `FILE`). |
-| `multi-claude list [--verbose \| --json \| --names]` | Show accounts, launchers and login state. `--json` adds usage and is meant for scripts; `--names` prints only the names. |
+| `multi-claude list [--verbose \| --json \| --names] [--no-refresh] [--offline]` | Show accounts, launchers, login state and the plan and billing channel looked up from Anthropic. `--json` adds usage and is meant for scripts; `--names` prints only the names; `--no-refresh` does not renew expired access tokens (never writes to a login); `--offline` skips the plan lookup (no token read, no network). |
 | `multi-claude usage [NAME] [--json]` | Show the last known 5-hour and 7-day usage of each account. |
 | `multi-claude usage --history [NAME] [--days N] [--by day\|model] [--json]` | Token usage per day or model, counted from the session files on this machine (default: 7 days). |
 | `multi-claude doctor [--json] [--verbose]` | Check the configuration, launchers, account directories, shared links, logins and environment. |

{multi_claude_cli-0.8.0 → multi_claude_cli-0.9.1}/README.md

@@ -10,7 +10,7 @@
 
 Use several [Claude Code](https://code.claude.com/docs) accounts on one machine, at the same time. Each account keeps its own login, settings and history and, if you like, its own proxy. No more logging out and in again.
 
-It never reads your login, never connects to the network and never edits your shell startup files.
+It never copies or exports your login and never edits your shell startup files. Only `list` reads an account's access token and goes online, to ask Anthropic for the current plan (renewing the token first if it has expired); `list --offline` skips all of that.
 
 ```sh
 claude-work        # Claude Code with your work account
@@ -37,8 +37,8 @@ The launchers are plain shell scripts. They keep working even if you uninstall m
 
 ## Features
 
-- **Never reads your login** — the only keychain call checks whether an item exists; the contents of keychain items and `.credentials.json` are never opened. `migrate-default` and `restore` move whole account directories, and on Linux the credentials file moves with its directory without being opened.
-- **No network** — multi-claude itself makes no network connections: no telemetry, no usage reporting, no update checks. Only the installer, pipx or Homebrew download the package.
+- **Your login stays yours** — logins are never copied or exported. One command touches them: `list` takes each account's access token (from the keychain, or `.credentials.json` on Linux) to ask Anthropic which plan the account is on, and when that token has expired it renews it the way Claude Code does and saves the new one in the same place. Tokens stay in memory and go only to Anthropic (`api.anthropic.com`, and `platform.claude.com` for a renewal), through that account's proxy. `list --no-refresh` never writes, `list --offline` reads nothing. Every other command only checks whether a login exists. `migrate-default` and `restore` move whole account directories, and on Linux the credentials file moves with its directory without being opened.
+- **Only `list` goes online** — its plan lookup (one request per account, plus one to renew an expired token) is the only connection multi-claude makes: no telemetry, no usage reporting, no update checks. `list --offline` makes none. Only the installer, pipx or Homebrew download the package.
 - **Leaves your shell alone** — when `PATH` needs a change, it prints the line to add instead of editing `~/.zshrc` or `~/.bashrc`.
 - **Changes only what you ask** — it writes its own configuration and state, the launchers, account directories (including the VS Code data that `code` keeps in `<root>/.apps`) and shared links. A Claude Code settings file is changed only by `statusline install` (the file you name, with a backup) and `add --config-from` (the new account's `settings.json`).
 - **Migrate the default account** — move your existing `~/.claude` into the account root without logging out. `claude` keeps working exactly as before.
@@ -49,11 +49,31 @@ The launchers are plain shell scripts. They keep working even if you uninstall m
 - **Idempotent** — every command can be re-run safely. Write commands print only what changes (`--verbose` lists everything); conflicts with files multi-claude does not own are reported without changing anything; an interrupted migration resumes where it stopped.
 - **Optional shared resources** — link `CLAUDE.md`, `skills`, `agents` and `commands` from one shared directory into selected accounts.
 
-## Requirements
+## Prerequisites
 
-- macOS or Linux (Windows is planned; inside WSL, use the Linux instructions)
-- Python 3.8 or newer (standard library only)
-- Claude Code (`claude`) on your `PATH`
+**Servers.** None. multi-claude runs only on your own computer; its only network requests are the plan lookups and token renewals of `list`, sent to Anthropic.
+
+**Your computer.**
+
+| | Needed | Optional |
+| ---- | ---- | ---- |
+| Operating system | macOS or Linux (WSL counts as Linux) | — |
+| Tools | Python 3.8+ (`python3`, standard library only); Claude Code (`claude`); `curl` or `wget`, and `tar`, for the installer | `pipx` or Homebrew, to install from PyPI or the tap; `lsof`, so that `migrate-default` and `restore` can find processes using `~/.claude` (Linux falls back to `/proc`); VS Code's `code` command, for `multi-claude code` |
+
+Install what is missing:
+
+```sh
+# macOS (with Homebrew, https://brew.sh); curl, tar and lsof come with macOS
+brew install python
+curl -fsSL https://claude.ai/install.sh | bash    # Claude Code, if you do not have it yet
+
+# Debian / Ubuntu / WSL
+sudo apt update
+sudo apt install -y python3 curl tar lsof
+curl -fsSL https://claude.ai/install.sh | bash    # Claude Code, if you do not have it yet
+```
+
+Windows itself is not supported yet; use WSL. Other ways to install Claude Code: https://code.claude.com/docs/en/setup
 
 ## Installation
 
@@ -234,7 +254,7 @@ work   23% 14:00  41% Fri  12m ago
 home   -          -        no data (start claude-home once)
 ```
 
-The numbers are the last values Claude Code itself cached in the account's `.claude.json` (for the default identity, `~/.claude.json`). multi-claude never reads credentials and never calls the network, so the data can be old: `UPDATED` shows its age, and values older than an hour are marked `stale`. Claude Code writes this cache itself; when it refreshes it is not documented. A window whose reset time has passed shows `reset`.
+The numbers are the last values Claude Code itself cached in the account's `.claude.json` (for the default identity, `~/.claude.json`). `usage` never reads credentials and never calls the network, so the data can be old: `UPDATED` shows its age, and values older than an hour are marked `stale`. Claude Code writes this cache itself; when it refreshes it is not documented. A window whose reset time has passed shows `reset`.
 
 For fresher numbers, let your status line record them. Claude Code passes the 5-hour and 7-day usage to the `statusLine` command each time it redraws the status line (Pro and Max plans, after the first response of a session). Wrap the `statusLine` command of the settings file that is actually in effect:
 
@@ -266,6 +286,24 @@ work:
 
 `list` shows when each account was last used (`LAST USED`), from the newest session file or prompt history in its directory; a `handoff` into an account counts as use.
 
+#### Plan and billing
+
+```text
+NAME   LOGIN     PLAN      BILLING      PROXY                  SHARED  5H         7D       LAST USED  STATUS
+work   keychain  max (5x)  stripe       http://127.0.0.1:7890  no      23% 14:00  41% Fri  5m ago     ok
+home   keychain  pro       apple        inherit                no      -          -        2d ago     ok
+old    keychain  token expired  -       inherit                no      -          -        9d ago     ok
+```
+
+`PLAN` and `BILLING` are not cached values: every `list` asks Anthropic (`GET https://api.anthropic.com/api/oauth/profile`, the request Claude Code itself makes) with the account's own access token. `PLAN` is the subscription — `pro`, `max (5x)`, `max (20x)`, `team`, `enterprise`. `BILLING` is where the subscription is paid: `stripe` (claude.ai), `apple` (App Store), `google-play`, `aws-marketplace` and so on.
+
+- The request uses the account's proxy setting, exactly like its launcher: the configured proxy, the proxy variables of your shell for `inherit`, none for `off`. If a proxy is configured and fails, the lookup fails; it never falls back to a direct connection. Only `http://` proxies work for the lookup.
+- Access tokens last a few hours. When one has expired, `list` renews it first: it takes the same lock as Claude Code (`.oauth_refresh.lock` in the account directory), posts the refresh token to `https://platform.claude.com/v1/oauth/token`, and saves the new tokens where the old ones were, keeping everything else in the login untouched. A running Claude session picks the new token up by itself. If another process has just renewed the token, `list` uses that result and writes nothing; if another process holds the lock, `list` does not wait and shows `token expired` this time. This follows what Claude Code 2.1.295 does; it is not a documented interface.
+- `token expired` means the access token has run out and could not be renewed; the subscription itself is not affected. The reason is on stderr (`token refresh failed for work: lock_busy`). Start `claude-NAME` once and run `list` again; when the reason is `refresh_rejected` or `no_refresh_token`, log in again with `multi-claude login NAME`. `list --no-refresh` never renews and never writes to a login.
+- `-` means the account has no OAuth login, and `rejected` that the server refused the token.
+- `error` comes with a reason on stderr, for example `plan lookup failed for work: timeout (via 127.0.0.1:7890, 10.01s)`. `tls_failed` usually means the Python that runs multi-claude has no root certificates (python.org installers ship an `Install Certificates.command`).
+- `list --offline` skips the lookup — no token is read, nothing is sent — and prints the table without the two columns. `list --json` carries the same data in each account's `plan` object (`refresh` tells whether a token was renewed); scripts should use it instead of parsing the table. The lookup adds about a second, at most 15; a renewal that is under way is allowed to finish first (the first Ctrl-C only prints a notice), so that the new login is not lost.
+
 ### Handing a session over to another account
 
 Each account keeps its own sessions, so `claude --resume` in one account cannot see the sessions of another. `handoff` copies one session (its `.jsonl` file and the folder next to it with subagent transcripts and saved tool output) into the same project folder of another account:
@@ -400,7 +438,7 @@ By default the numbers come from the cache that Claude Code writes in `.claude.j
 
 ### Does multi-claude read or copy my login?
 
-It never reads it: its only keychain call checks whether an item exists, and it never opens `.credentials.json`. It does not export, upload or back up logins. `migrate-default` and `restore` move a whole account directory; on Linux the credentials file is inside it and moves with it (in copy mode it is copied as part of the directory, verified, and the original directory is then removed unless you pass `--keep-backup`), still without being opened. On macOS a login is tied to the account directory's path, which is why `rename` keeps the directory.
+It never copies, exports, uploads or backs up a login. One command touches one: `list` takes each account's access token to ask Anthropic for the account's plan, and renews the token when it has expired, saving the new one where the old one was (see [Plan and billing](#plan-and-billing)). Tokens stay in memory and are sent only to Anthropic. `list --no-refresh` never writes and `list --offline` does not read. All other commands only check whether a login exists. `migrate-default` and `restore` move a whole account directory; on Linux the credentials file is inside it and moves with it (in copy mode it is copied as part of the directory, verified, and the original directory is then removed unless you pass `--keep-backup`), still without being opened. On macOS a login is tied to the account directory's path, which is why `rename` keeps the directory.
 
 ## Reference
 
@@ -420,7 +458,7 @@ It never reads it: its only keychain call checks whether an item exists, and it
 | `multi-claude args (NAME \| --defaults) -- [ARG ...]` | Replace the fixed arguments; `--` with nothing after it clears them. |
 | `multi-claude remove NAME` | Unregister an account and delete its launcher. **The directory and the login are kept.** |
 | `multi-claude apply [-f FILE]` | Converge everything to the configuration (or to `FILE`). |
-| `multi-claude list [--verbose \| --json \| --names]` | Show accounts, launchers and login state. `--json` adds usage and is meant for scripts; `--names` prints only the names. |
+| `multi-claude list [--verbose \| --json \| --names] [--no-refresh] [--offline]` | Show accounts, launchers, login state and the plan and billing channel looked up from Anthropic. `--json` adds usage and is meant for scripts; `--names` prints only the names; `--no-refresh` does not renew expired access tokens (never writes to a login); `--offline` skips the plan lookup (no token read, no network). |
 | `multi-claude usage [NAME] [--json]` | Show the last known 5-hour and 7-day usage of each account. |
 | `multi-claude usage --history [NAME] [--days N] [--by day\|model] [--json]` | Token usage per day or model, counted from the session files on this machine (default: 7 days). |
 | `multi-claude doctor [--json] [--verbose]` | Check the configuration, launchers, account directories, shared links, logins and environment. |

{multi_claude_cli-0.8.0 → multi_claude_cli-0.9.1}/src/multi_claude/__init__.py

@@ -1,3 +1,3 @@
 """multi-claude：管理多个 Claude Code 账号的配置目录、启动命令、代理与启动参数。"""
 
-__version__ = "0.8.0"
+__version__ = "0.9.1"

{multi_claude_cli-0.8.0 → multi_claude_cli-0.9.1}/src/multi_claude/cli.py

@@ -19,8 +19,8 @@ from datetime import datetime, timedelta, timezone
 from typing import List, Optional, Tuple
 
 from . import (__version__, accounts, bundle, completion, doctor, history, hook, identity, launcher, migrate,
-               platform, restore, routes, sessions, shellpath, statusline, usage)
-from .actions import error, info, warn
+               plan, platform, refresh, restore, routes, sessions, shellpath, statusline, usage)
+from .actions import LOG_PREFIX, error, info, warn
 from .config import (DEFAULT_SHARED_DIR, DEFAULT_SHARED_ITEMS, IDENTITY_DEFAULT, IDENTITY_DIR, Account, Config, ConfigError, RouteRule,
                      is_unshareable, load_config, normalize_proxy, parse_config, validate_env_key, validate_name,
                      validate_route_path, validate_value, config_path)
@@ -166,12 +166,18 @@ def build_parser() -> argparse.ArgumentParser:
     p_apply.add_argument("-f", "--file", help="use this file as the new configuration")
     _add_write_options(p_apply)
 
-    p_list = sub.add_parser("list", description="show accounts and their status")
+    p_list = sub.add_parser("list", description="show accounts and their status; looks up each account's plan "
+                            "and billing channel from Anthropic unless --offline is given")
     list_mode = p_list.add_mutually_exclusive_group()
     list_mode.add_argument("--verbose", action="store_true",
                            help="show every field, the global settings and the keychain details")
     list_mode.add_argument("--json", action="store_true", help="print machine-readable JSON (includes usage)")
     list_mode.add_argument("--names", action="store_true", help="print only the account names, one per line")
+    p_list.add_argument("--no-refresh", action="store_true",
+                        help="do not renew an expired access token (never write to the login); "
+                             "such accounts show 'token expired'")
+    p_list.add_argument("--offline", action="store_true",
+                        help="skip the plan lookup: do not read access tokens and do not connect to the network")
 
     p_usage = sub.add_parser("usage", description="show the last known 5-hour and 7-day usage of each account "
                                            "(from Claude Code's own cache; never reads credentials)")
@@ -397,7 +403,8 @@ def main(argv: Optional[List[str]] = None) -> int:
             warn(notice)
         # list 与 usage 只读：不加写锁，迁移未完成时也放行。
         if args.command == "list":
-            return cmd_list(verbose=args.verbose, as_json=args.json, names_only=args.names)
+            return cmd_list(verbose=args.verbose, as_json=args.json, names_only=args.names, offline=args.offline,
+                            refresh_tokens=not args.no_refresh)
         if args.command == "usage":
             if args.history:
                 return cmd_usage_history(args.name, args.days, args.by or "day", args.json)
@@ -979,7 +986,7 @@ _EMAIL_LIKE = re.compile(r"^[^@\s]+@[^@\s]+\.[^@\s]+$")
 def cmd_login(name: str, claude_args: List[str]) -> int:
     """以账号的身份环境运行 `claude auth login …`（方案 feature-easier-onboarding §5.1.4）。
 
-    凭据由 Claude 自己写入该账号的钥匙串条目或凭据文件，本工具不读写凭据。
+    凭据由 Claude 自己写入该账号的钥匙串条目或凭据文件，本命令不读写凭据。
     不带账号的固定参数：取多个值的选项会把 `auth login` 当成自己的值吞掉（同 mcp）。
     """
     process_env, code = _account_process_env(name)
@@ -1260,7 +1267,10 @@ def _checked_proxy(value: str) -> str:
         raise UsageError(str(exc))
 
 
-def cmd_list(verbose: bool = False, as_json: bool = False, names_only: bool = False) -> int:
+def cmd_list(verbose: bool = False, as_json: bool = False, names_only: bool = False, offline: bool = False,
+             refresh_tokens: bool = True) -> int:
+    """列出账号。除 --names 与 --offline 外，会读各账号的访问令牌并向服务端查询套餐（方案 feature-live-plan）；
+    访问令牌过期时先刷新并写回凭据，refresh_tokens 为假时不刷新（方案 feature-token-refresh）。"""
     config, exists = load_config()
     if names_only:
         # 给补全脚本用：只输出名称，不输出任何告警。
@@ -1271,9 +1281,13 @@ def cmd_list(verbose: bool = False, as_json: bool = False, names_only: bool = Fa
     for variable in _UNMANAGED_PROXY_VARS:
         if variable in os.environ:
             warn("{} is set; launchers do not change it, even with proxy off".format(variable))
+    # 套餐只查一次，表格与 JSON 共用；None 表示本次不查（--offline 或还没有配置）。
+    plans = None if offline or not exists else plan.query_all(config, os.environ, datetime.now(timezone.utc),
+                                                             allow_refresh=refresh_tokens)
     if as_json:
-        _print_json(_list_data(config, exists))
+        _print_json(_list_data(config, exists, plans))
         if exists:
+            _report_plan_problems(plans)
             accounts.warn_launch_settings(config, None, note_invalid=True)
         return accounts.EXIT_OK
     if not exists:
@@ -1281,7 +1295,7 @@ def cmd_list(verbose: bool = False, as_json: bool = False, names_only: bool = Fa
             os.path.join(platform.state_dir(), "config.json")))
         return accounts.EXIT_OK
     if not verbose:
-        return _print_brief_list(config)
+        return _print_brief_list(config, plans)
     print("root: {}".format(expand(config.root)))
     print("bin_dir: {}".format(expand(config.bin_dir)))
     print("shared.dir: {}".format(expand(config.shared_dir) if config.shared_dir else "(not set)"))
@@ -1290,15 +1304,15 @@ def cmd_list(verbose: bool = False, as_json: bool = False, names_only: bool = Fa
         return accounts.EXIT_OK
     if "CLAUDE_CODE_CUSTOM_OAUTH_URL" in os.environ:
         warn("CLAUDE_CODE_CUSTOM_OAUTH_URL is set; LOGIN assumes the production service and may be wrong")
-    rows = [("NAME", "IDENTITY", "DIR", "PROXY", "SHARED", "LAUNCHER", "LOGIN", "LINK")]
+    rows = [("NAME", "IDENTITY", "DIR", "PROXY", "SHARED", "LAUNCHER", "LOGIN") + _plan_header(plans) + ("LINK",)]
     details = []
     default_account = None
     for entry in _account_entries(config):
         if entry["identity"] == IDENTITY_DEFAULT:
             default_account = entry["name"]
         rows.append((entry["name"], entry["identity"], "ok" if entry["dir_exists"] else "missing-dir",
-                     entry["proxy"], _shared_cell(entry), entry["launcher"], entry["login"],
-                     entry["link"] or "-"))
+                     entry["proxy"], _shared_cell(entry), entry["launcher"], entry["login"])
+                    + _plan_cells(plans, entry["name"]) + (entry["link"] or "-",))
         if verbose:
             details.append("  {}: keychain service {!r}, credentials file {}".format(
                 entry["name"], entry["keychain_service"], entry["credentials_file"]))
@@ -1309,11 +1323,50 @@ def cmd_list(verbose: bool = False, as_json: bool = False, names_only: bool = Fa
             default_account, os.path.join(os.path.expanduser("~"), ".claude.json")))
     for line in details:
         print(line)
+    _report_plan_problems(plans)
     accounts.warn_launch_settings(config, None, note_invalid=True)
     return accounts.EXIT_OK
 
 
-def _print_brief_list(config: Config) -> int:
+_PLAN_HEADER = ("PLAN", "BILLING")
+
+
+def _plan_header(plans: Optional[dict]) -> tuple:
+    """--offline 时不加这两列，表格与改动前完全相同。"""
+    return () if plans is None else _PLAN_HEADER
+
+
+def _plan_cells(plans: Optional[dict], name: str) -> tuple:
+    if plans is None:
+        return ()
+    return (plan.plan_cell(plans[name]), plan.billing_cell(plans[name]))
+
+
+def _report_plan_problems(plans: Optional[dict]) -> None:
+    """套餐查询与令牌刷新的失败提示，打到 stderr；不影响表格、STATUS 列与退出码。"""
+    if plans is None:
+        return
+    expired = []
+    for name, result in plans.items():
+        if result.refresh == refresh.SAVE_FAILED:
+            # 新令牌只用了这一次、没存下来：旧的刷新令牌多半已作废，下次启动可能要重新登录。
+            error("the renewed login of {0} could not be saved; if claude-{0} asks you to log in, "
+                  "run multi-claude login {0}".format(name))
+        if result.status == plan.STATUS_ERROR:
+            warn(plan.failure_text(name, result))
+        elif result.status == plan.STATUS_EXPIRED:
+            expired.append(name)
+            if result.refresh is not None:
+                hint = "; run multi-claude login {}".format(name) if result.refresh in refresh.NEEDS_LOGIN else ""
+                warn("token refresh failed for {}: {}{}".format(name, result.refresh, hint))
+    if expired:
+        # 走 stderr 而不是 info()：info() 写 stdout，会混进 --json 的输出。
+        print("{} token expired: the access token ran out, the subscription is not affected; start {} once, "
+              "then run list again".format(LOG_PREFIX, ", ".join("claude-" + name for name in expired)),
+              file=sys.stderr)
+
+
+def _print_brief_list(config: Config, plans: Optional[dict] = None) -> int:
     """list 的默认输出：只放新用户关心的列（方案 feature-clearer-help §5.1.2）；完整信息见 --verbose。"""
     if not config.accounts:
         print("no accounts registered; run `multi-claude add NAME` to start")
@@ -1322,19 +1375,21 @@ def _print_brief_list(config: Config) -> int:
         # 与完整输出相同：LOGIN 与由它得出的 STATUS 都按正式服务探测，这时可能不准。
         warn("CLAUDE_CODE_CUSTOM_OAUTH_URL is set; LOGIN assumes the production service and may be wrong")
     now = datetime.now(timezone.utc)
-    rows = [("NAME", "LOGIN", "PROXY", "SHARED", "5H", "7D", "LAST USED", "STATUS")]
+    rows = [("NAME", "LOGIN") + _plan_header(plans) + ("PROXY", "SHARED", "5H", "7D", "LAST USED", "STATUS")]
     has_problem = False
     for entry in _account_entries(config):
         report = usage.read_account_usage(config, config.find(entry["name"]), now)
         status = _status_cell(entry)
         has_problem = has_problem or status != "ok"
-        rows.append((entry["name"], entry["login"], entry["proxy"], _shared_cell(entry),
-                     _window_cell(report.five_hour, now), _window_cell(report.seven_day, now),
-                     _last_used_cell(entry["last_used"], now), status))
+        rows.append((entry["name"], entry["login"]) + _plan_cells(plans, entry["name"])
+                    + (entry["proxy"], _shared_cell(entry),
+                       _window_cell(report.five_hour, now), _window_cell(report.seven_day, now),
+                       _last_used_cell(entry["last_used"], now), status))
     _print_table(rows)
     _print_routes(config)
     if has_problem:
         print("run multi-claude doctor for details")
+    _report_plan_problems(plans)
     accounts.warn_launch_settings(config, None, note_invalid=True)
     return accounts.EXIT_OK
 
@@ -1377,7 +1432,7 @@ def _shared_cell(entry: dict) -> str:
     return "yes"
 
 
-def _account_entries(config: Config, with_usage: bool = False) -> List[dict]:
+def _account_entries(config: Config, with_usage: bool = False, plans: Optional[dict] = None) -> List[dict]:
     """list 的表格与 JSON 共用的每账号数据；表格的列取自这里，保证两种输出口径一致。"""
     now = datetime.now(timezone.utc)
     entries = []
@@ -1402,11 +1457,14 @@ def _account_entries(config: Config, with_usage: bool = False) -> List[dict]:
         }
         if with_usage:
             entry["usage"] = usage.report_to_dict(usage.read_account_usage(config, account, now), now)
+        if plans is not None:
+            # 本次没查套餐（--offline）时不加这个键，JSON 与改动前相同
+            entry["plan"] = plan.to_dict(plans[name])
         entries.append(entry)
     return entries
 
 
-def _list_data(config: Config, exists: bool) -> dict:
+def _list_data(config: Config, exists: bool, plans: Optional[dict] = None) -> dict:
     if not exists:
         return {"schema_version": 1, "configured": False, "accounts": [],
                 "routes": {"default": None, "rules": []}}
@@ -1416,7 +1474,7 @@ def _list_data(config: Config, exists: bool) -> dict:
         "root": expand(config.root),
         "bin_dir": expand(config.bin_dir),
         "shared_dir": expand(config.shared_dir) if config.shared_dir else None,
-        "accounts": _account_entries(config, with_usage=True),
+        "accounts": _account_entries(config, with_usage=True, plans=plans),
         "routes": {"default": config.route_default,
                    "rules": [{"path": rule.path, "account": rule.account, "exists": os.path.isdir(expand(rule.path))}
                              for rule in config.route_rules]},
@@ -1463,7 +1521,7 @@ def cmd_usage(name: Optional[str], as_json: bool) -> int:
     for row in rows:
         print("  ".join(cell.ljust(width) for cell, width in zip(row, widths)).rstrip())
     print("Values come from Claude Code's own cache (.claude.json) or the statusline hook, and may be out of date; "
-          "multi-claude never reads credentials.")
+          "this command never reads credentials.")
     return accounts.EXIT_OK
 
 
@@ -1555,7 +1613,7 @@ def cmd_usage_history(name: Optional[str], days: Optional[int], by: str, as_json
     if len(per_account) > 1:
         _print_history_block("TOTAL (each reply counted once)", total, by, days)
     print("Counted from the session files on this machine (not other machines, not deleted sessions); "
-          "multi-claude reads only the token counts, never connects to the network and never reads credentials.")
+          "this command reads only the token counts, never connects to the network and never reads credentials.")
     return accounts.EXIT_OK