multi-claude-cli 0.9.0__tar.gz → 0.10.0__tar.gz

{multi_claude_cli-0.9.0 → multi_claude_cli-0.10.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: multi-claude-cli
-Version: 0.9.0
+Version: 0.10.0
 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 changes or copies 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; `list --offline` skips that.
+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
 
-- **Your login stays yours** — logins are never written, copied, exported or refreshed. One command reads one: `list` takes each account's access token (from the keychain, or `.credentials.json` on Linux) to ask Anthropic which plan the account is on. The token stays in memory and goes only to `api.anthropic.com`, through that account's proxy. `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.
-- **One kind of network request, nothing else** — the plan lookup of `list` (one request per account) 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.
+- **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.
@@ -78,7 +78,7 @@ The launchers are plain shell scripts. They keep working even if you uninstall m
 
 ## Prerequisites
 
-**Servers.** None. multi-claude runs only on your own computer; its only network requests are the plan lookups of `list`, sent to Anthropic.
+**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.**
 
@@ -319,15 +319,37 @@ work:
 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  expired   -            inherit                no      -          -        9d 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.
-- `expired` means the access token has run out. Tokens last a few hours and multi-claude never refreshes them (refreshing would compete with running sessions): start `claude-NAME` once and run `list` again. `-` means the account has no OAuth login, and `rejected` that the server refused the token.
+- 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; scripts should use it instead of parsing the table. The lookup adds about a second, at most 15.
+- `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.
+
+### Finding a session
+
+Forgot which account or which directory a session was started in? `sessions` lists the sessions of every account and every project directory, newest first, each followed by the command that resumes it:
+
+```sh
+multi-claude sessions
+# ACCOUNT  UPDATED           CREATED           SESSION ID                            TITLE
+# work     2026-10-11 17:42  2026-10-11 16:05  3c588340-1219-48df-a231-509866789487  Fix the importer
+#   cd /path/to/project && claude-work --resume 3c588340-1219-48df-a231-509866789487
+multi-claude sessions work            # one account
+multi-claude sessions --grep importer # title, directory or session id contains the text
+```
+
+- It shows the 30 most recent sessions; `--limit N` changes that and `--limit 0` shows all. `--json` prints every match with the full fields (`directory`, `created`, `updated`, `title_source`, `file`, `resume`). `conversations` is another name for the same command.
+- The title is the session's name in Claude Code; a session without one shows the beginning of its first prompt, and `-` if it has no prompt at all. Times are local. `UPDATED` is the time of the last message, or the file's modification time when the session has no timestamps.
+- A `~/.claude` that has not been turned into an account is listed as `default`.
+- A session copied with `handoff` appears once per account that has a copy.
+- The command is read-only and stays on this machine: it reads the start and the end of each session file, prints the title (a piece of your conversation) to the terminal, and saves or sends nothing. It does not list subagent transcripts.
+- If the directory a session was started in no longer exists, the `cd` in the resume command fails; `claude --resume` only finds a session from the directory it was started in.
 
 ### Handing a session over to another account
 
@@ -449,6 +471,10 @@ The one in `~/.claude`, as before: multi-claude does not change it. After [migra
 
 There is no command that switches which account plain `claude` uses. Besides `~/.claude`, plain `claude` reads the login in the keychain (macOS) and `~/.claude.json`, and neither would follow such a switch, so two accounts would get mixed up. Use the launchers (`claude-work`), or `multi-claude route --default work` and start `claude-auto`.
 
+### Which account or directory was that session in?
+
+`multi-claude sessions --grep TEXT` searches the titles, directories and ids of the sessions of all accounts and prints the command that resumes each match. See [Finding a session](#finding-a-session).
+
 ### How do I continue a conversation with another account?
 
 Inside the Claude session, run `! multi-claude handoff OTHER`, then run the command it prints in a new terminal. See [Handing a session over to another account](#handing-a-session-over-to-another-account).
@@ -463,7 +489,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 writes, copies, exports, uploads, refreshes or backs up a login. One command reads one: `list` takes each account's access token to ask Anthropic for the account's plan (see [Plan and billing](#plan-and-billing)); the token stays in memory and is sent only to `api.anthropic.com`. `list --offline` does not read it. 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.
+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
 
@@ -483,7 +509,7 @@ It never writes, copies, exports, uploads, refreshes or backs up a login. One co
 | `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] [--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; `--offline` skips the plan lookup (no token read, no network). |
+| `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. |
@@ -496,6 +522,7 @@ It never writes, copies, exports, uploads, refreshes or backs up a login. One co
 | `multi-claude path NAME` | Print the account's directory. |
 | `multi-claude code NAME [PATH] [-- ARGS ...]` | Open a separate VS Code instance with the account's environment (experimental). |
 | `multi-claude handoff TARGET [--from NAME] [--session ID] [--force]` | Copy a session to another account and print the command that resumes it there. |
+| `multi-claude sessions [NAME] [--grep TEXT] [--limit N] [--json]` | List the sessions of every account and directory, newest first, with the command that resumes each. Also `conversations`. |
 | `multi-claude statusline install\|uninstall FILE` | Wrap the statusLine command in a settings file so that `usage` gets fresh numbers, or restore it. |
 | `multi-claude completion bash\|zsh\|fish` | Print a shell completion script. |
 

{multi_claude_cli-0.9.0 → multi_claude_cli-0.10.0}/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 changes or copies 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; `list --offline` skips that.
+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
 
-- **Your login stays yours** — logins are never written, copied, exported or refreshed. One command reads one: `list` takes each account's access token (from the keychain, or `.credentials.json` on Linux) to ask Anthropic which plan the account is on. The token stays in memory and goes only to `api.anthropic.com`, through that account's proxy. `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.
-- **One kind of network request, nothing else** — the plan lookup of `list` (one request per account) 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.
+- **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.
@@ -51,7 +51,7 @@ The launchers are plain shell scripts. They keep working even if you uninstall m
 
 ## Prerequisites
 
-**Servers.** None. multi-claude runs only on your own computer; its only network requests are the plan lookups of `list`, sent to Anthropic.
+**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.**
 
@@ -292,15 +292,37 @@ work:
 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  expired   -            inherit                no      -          -        9d 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.
-- `expired` means the access token has run out. Tokens last a few hours and multi-claude never refreshes them (refreshing would compete with running sessions): start `claude-NAME` once and run `list` again. `-` means the account has no OAuth login, and `rejected` that the server refused the token.
+- 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; scripts should use it instead of parsing the table. The lookup adds about a second, at most 15.
+- `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.
+
+### Finding a session
+
+Forgot which account or which directory a session was started in? `sessions` lists the sessions of every account and every project directory, newest first, each followed by the command that resumes it:
+
+```sh
+multi-claude sessions
+# ACCOUNT  UPDATED           CREATED           SESSION ID                            TITLE
+# work     2026-10-11 17:42  2026-10-11 16:05  3c588340-1219-48df-a231-509866789487  Fix the importer
+#   cd /path/to/project && claude-work --resume 3c588340-1219-48df-a231-509866789487
+multi-claude sessions work            # one account
+multi-claude sessions --grep importer # title, directory or session id contains the text
+```
+
+- It shows the 30 most recent sessions; `--limit N` changes that and `--limit 0` shows all. `--json` prints every match with the full fields (`directory`, `created`, `updated`, `title_source`, `file`, `resume`). `conversations` is another name for the same command.
+- The title is the session's name in Claude Code; a session without one shows the beginning of its first prompt, and `-` if it has no prompt at all. Times are local. `UPDATED` is the time of the last message, or the file's modification time when the session has no timestamps.
+- A `~/.claude` that has not been turned into an account is listed as `default`.
+- A session copied with `handoff` appears once per account that has a copy.
+- The command is read-only and stays on this machine: it reads the start and the end of each session file, prints the title (a piece of your conversation) to the terminal, and saves or sends nothing. It does not list subagent transcripts.
+- If the directory a session was started in no longer exists, the `cd` in the resume command fails; `claude --resume` only finds a session from the directory it was started in.
 
 ### Handing a session over to another account
 
@@ -422,6 +444,10 @@ The one in `~/.claude`, as before: multi-claude does not change it. After [migra
 
 There is no command that switches which account plain `claude` uses. Besides `~/.claude`, plain `claude` reads the login in the keychain (macOS) and `~/.claude.json`, and neither would follow such a switch, so two accounts would get mixed up. Use the launchers (`claude-work`), or `multi-claude route --default work` and start `claude-auto`.
 
+### Which account or directory was that session in?
+
+`multi-claude sessions --grep TEXT` searches the titles, directories and ids of the sessions of all accounts and prints the command that resumes each match. See [Finding a session](#finding-a-session).
+
 ### How do I continue a conversation with another account?
 
 Inside the Claude session, run `! multi-claude handoff OTHER`, then run the command it prints in a new terminal. See [Handing a session over to another account](#handing-a-session-over-to-another-account).
@@ -436,7 +462,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 writes, copies, exports, uploads, refreshes or backs up a login. One command reads one: `list` takes each account's access token to ask Anthropic for the account's plan (see [Plan and billing](#plan-and-billing)); the token stays in memory and is sent only to `api.anthropic.com`. `list --offline` does not read it. 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.
+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
 
@@ -456,7 +482,7 @@ It never writes, copies, exports, uploads, refreshes or backs up a login. One co
 | `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] [--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; `--offline` skips the plan lookup (no token read, no network). |
+| `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. |
@@ -469,6 +495,7 @@ It never writes, copies, exports, uploads, refreshes or backs up a login. One co
 | `multi-claude path NAME` | Print the account's directory. |
 | `multi-claude code NAME [PATH] [-- ARGS ...]` | Open a separate VS Code instance with the account's environment (experimental). |
 | `multi-claude handoff TARGET [--from NAME] [--session ID] [--force]` | Copy a session to another account and print the command that resumes it there. |
+| `multi-claude sessions [NAME] [--grep TEXT] [--limit N] [--json]` | List the sessions of every account and directory, newest first, with the command that resumes each. Also `conversations`. |
 | `multi-claude statusline install\|uninstall FILE` | Wrap the statusLine command in a settings file so that `usage` gets fresh numbers, or restore it. |
 | `multi-claude completion bash\|zsh\|fish` | Print a shell completion script. |
 

{multi_claude_cli-0.9.0 → multi_claude_cli-0.10.0}/src/multi_claude/__init__.py

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

{multi_claude_cli-0.9.0 → multi_claude_cli-0.10.0}/src/multi_claude/cli.py

@@ -16,10 +16,10 @@ import stat
 import subprocess
 import sys
 from datetime import datetime, timedelta, timezone
-from typing import List, Optional, Tuple
+from typing import List, NamedTuple, Optional, Tuple
 
 from . import (__version__, accounts, bundle, completion, doctor, history, hook, identity, launcher, migrate,
-               plan, platform, restore, routes, sessions, shellpath, statusline, usage)
+               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,
@@ -55,6 +55,7 @@ COMMAND_GROUPS = [
         ("usage", "5-hour and 7-day usage of each account"),
         ("route, which", "choose an account by directory (launcher claude-auto)"),
         ("handoff", "copy a session to another account"),
+        ("sessions", "find a session across accounts and directories"),
         ("mcp", "run `claude mcp` as an account"),
         ("run, path", "run any command as an account; print its directory"),
         ("code", "open VS Code for an account (experimental)"),
@@ -173,6 +174,9 @@ def build_parser() -> argparse.ArgumentParser:
                            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")
 
@@ -273,6 +277,18 @@ def build_parser() -> argparse.ArgumentParser:
     p_handoff.add_argument("--force", action="store_true",
                            help="back up and replace a different copy of the session in TARGET")
     _add_dry_run(p_handoff)
+
+    p_sessions = sub.add_parser("sessions", description="list the Claude sessions of every account and every directory, "
+                                                 "newest first, each with the command that resumes it "
+                                                 "(read-only; also available as `conversations`): "
+                                                 "sessions [NAME] [--grep TEXT] [--limit N] [--json]")
+    p_sessions.add_argument("name", nargs="?", metavar="NAME",
+                            help="only this account (`default` is the unregistered ~/.claude)")
+    p_sessions.add_argument("--grep", metavar="TEXT",
+                            help="only sessions whose title, directory or id contains TEXT (case-insensitive)")
+    p_sessions.add_argument("--limit", type=int, metavar="N",
+                            help="show at most N sessions, 0 for all (default: 30, or all with --json)")
+    p_sessions.add_argument("--json", action="store_true", help="print machine-readable JSON")
     return parser
 
 
@@ -365,6 +381,7 @@ def main(argv: Optional[List[str]] = None) -> int:
     if not argv:
         # 不带参数：新用户先看到怎么上手，已有配置的用户看到账号表（方案 feature-easier-onboarding §5.1.1）。
         return cmd_overview()
+    argv = _resolve_command_alias(argv)
     parser = build_parser()
     unknown = _unknown_command(parser, argv) or _misplaced_account_name(argv)
     if unknown is not None:
@@ -400,13 +417,17 @@ 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, offline=args.offline)
+            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)
             if args.days is not None or args.by is not None:
                 raise UsageError("--days and --by need --history")
             return cmd_usage(args.name, args.json)
+        if args.command == "sessions":
+            # 只读：不加写锁，迁移未完成时也放行（与 list、usage 相同）。
+            return cmd_sessions(args.name, args.grep, args.limit, args.json)
         if args.command == "which":
             return cmd_which(args.path)
         if args.command == "statusline":
@@ -1022,6 +1043,23 @@ All commands: multi-claude --help
 """
 
 
+# 别名 -> 子命令。不用 argparse 的 aliases：别名进了解析器，分组帮助、补全和 args.command 都要跟着处理两个名字。
+_COMMAND_ALIASES = {"conversations": "sessions"}
+
+
+def _resolve_command_alias(argv: List[str]) -> List[str]:
+    """把子命令位置上的别名换成正式的子命令名；其它位置上的同名词（例如叫 conversations 的账号）不动。
+
+    子命令位置就是第一个不以 - 开头的词：顶层解析器没有带值的选项，_unknown_command 也按同一规则取词。
+    """
+    for index, token in enumerate(argv):
+        if not token.startswith("-"):
+            if token in _COMMAND_ALIASES:
+                return argv[:index] + [_COMMAND_ALIASES[token]] + argv[index + 1:]
+            break
+    return argv
+
+
 def _unknown_command(parser: argparse.ArgumentParser, argv: List[str]) -> Optional[str]:
     """第一个非选项参数不是子命令时，返回带建议的报错文字；否则返回 None 交给 argparse。"""
     word = next((token for token in argv if not token.startswith("-")), None)
@@ -1263,8 +1301,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, offline: bool = False) -> int:
-    """列出账号。除 --names 与 --offline 外，会读各账号的访问令牌并向服务端查询套餐（方案 feature-live-plan）。"""
+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:
         # 给补全脚本用：只输出名称，不输出任何告警。
@@ -1276,7 +1316,8 @@ def cmd_list(verbose: bool = False, as_json: bool = False, names_only: bool = Fa
         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))
+    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, plans))
         if exists:
@@ -1336,20 +1377,27 @@ def _plan_cells(plans: Optional[dict], name: str) -> tuple:
 
 
 def _report_plan_problems(plans: Optional[dict]) -> None:
-    """套餐查询的失败与过期提示，打到 stderr；不影响表格、STATUS 列与退出码。"""
+    """套餐查询与令牌刷新的失败提示，打到 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:
-        # multi-claude 不刷新令牌：让 Claude Code 自己续期，再查一次即可。
         # 走 stderr 而不是 info()：info() 写 stdout，会混进 --json 的输出。
-        print("{} expired: start {} once to renew the login, then run list again".format(
-            LOG_PREFIX, ", ".join("claude-" + name for name in expired)), file=sys.stderr)
+        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:
@@ -1688,6 +1736,129 @@ def cmd_handoff(target_name: str, source_name: Optional[str], session_id: Option
     return accounts.EXIT_OK
 
 
+class _SessionSource(NamedTuple):
+    # 账号列显示的名字；未登记的默认目录显示 default
+    name: str
+    directory: str
+    # 续聊命令里启动 Claude 的那一段
+    launcher: str
+    registered: bool
+
+
+_UNREGISTERED_DEFAULT = "default"
+# 未登记的默认目录没有启动命令，只能直接运行 claude；去掉这两个变量，在别的账号的 Claude 会话里
+# 运行也会落到默认目录（default 身份的启动命令同样先 unset 它们）。
+_DEFAULT_LAUNCHER = "env -u CLAUDE_CONFIG_DIR -u CLAUDE_SECURESTORAGE_CONFIG_DIR claude"
+_SESSIONS_TEXT_LIMIT = 30
+# 标题来自会话内容，可能是整段粘贴的提问：表格里只留开头，JSON 里也设上限
+_TITLE_TEXT_CHARS = 60
+_TITLE_JSON_CHARS = 200
+
+
+def _session_sources(config: Config, exists: bool) -> List[_SessionSource]:
+    """要列会话的目录：登记的每个账号，加上还没迁移成账号的默认目录 ~/.claude。"""
+    sources = [_SessionSource(account.name, accounts.account_dir(config, account.name), "claude-" + account.name, True)
+               for account in (config.accounts.values() if exists else [])]
+    default = accounts.default_dir()
+    # 做过 migrate-default 后 ~/.claude 是指向账号目录的软链，按真实路径比较才不会把同一批会话列两遍
+    known = {os.path.realpath(source.directory) for source in sources}
+    if os.path.isdir(os.path.join(default, "projects")) and os.path.realpath(default) not in known:
+        sources.append(_SessionSource(_UNREGISTERED_DEFAULT, default, _DEFAULT_LAUNCHER, False))
+    return sources
+
+
+def cmd_sessions(name: Optional[str], grep: Optional[str], limit: Optional[int], as_json: bool) -> int:
+    """只读列出各账号、各目录的会话，最近更新的在前，每条附续聊命令（方案 feature-session-list）。
+
+    会把会话标题或首条提问的开头打印出来（这是对话内容的片段），不保存、不联网、不读凭据。
+    同一会话 ID 在多个账号里各有一份时（handoff 复制过）各列一行，不合并。
+    """
+    if limit is not None and limit < 0:
+        raise UsageError("--limit must be 0 or more")
+    config, exists = load_config()
+    sources = _session_sources(config, exists)
+    if name is not None:
+        # 名字先校验，没有配置文件时也一样：不合法的名字是用法错误（退出 2），不是“未登记”
+        _checked_name(name)
+        account = config.find(name) if exists else None
+        if account is not None:
+            # 登记账号优先：账号本身叫 default 时，`sessions default` 指的是它，不是未登记的默认目录
+            sources = [source for source in sources if source.registered and source.name == account.name]
+        elif name.casefold() == _UNREGISTERED_DEFAULT and any(not source.registered for source in sources):
+            sources = [source for source in sources if not source.registered]
+        else:
+            error("account {!r} is not registered".format(name))
+            return accounts.EXIT_ERROR
+    entries = []
+    skipped = 0
+    needle = grep.casefold() if grep else None
+    for source in sources:
+        found, unreadable = sessions.list_sessions(source.directory)
+        skipped += unreadable
+        for session in found:
+            full_title = sessions.clean_title(session.title, len(session.title))
+            if needle is not None and not any(needle in text.casefold() for text in (
+                    full_title, session.directory or session.project, session.session_id)):
+                continue
+            entries.append((source, session, full_title))
+    entries.sort(key=lambda entry: (-entry[1].updated.timestamp(), entry[0].name, entry[1].session_id))
+    total = len(entries)
+    if limit is None:
+        limit = 0 if as_json else _SESSIONS_TEXT_LIMIT
+    if limit:
+        entries = entries[:limit]
+    if skipped:
+        warn("skipped {} session file(s) that could not be read".format(skipped))
+    if as_json:
+        _print_json({"schema_version": 1, "sessions": [{
+            "account": source.name, "registered": source.registered, "directory": session.directory,
+            "project": session.project, "session_id": session.session_id,
+            "title": sessions.clean_title(full_title, _TITLE_JSON_CHARS), "title_source": session.title_source,
+            "created": _iso(session.created), "updated": _iso(session.updated), "file": session.path,
+            "resume": _resume_command(source, session)} for source, session, full_title in entries],
+            "total": total, "skipped": skipped})
+        return accounts.EXIT_OK
+    if not entries:
+        print("no sessions found")
+        return accounts.EXIT_OK
+    # 不用 _print_table：每条会话下面要插一行续聊命令。标题放最后一列，中文标题的显示宽度不影响前面各列对齐。
+    rows = [("ACCOUNT", "UPDATED", "CREATED", "SESSION ID", "TITLE", None)]
+    for source, session, full_title in entries:
+        resume = _resume_command(source, session)
+        if session.directory is None:
+            resume += "  (start directory unknown; project {})".format(
+                sessions.clean_title(session.project, len(session.project)))
+        rows.append((source.name, _local_minute(session.updated), _local_minute(session.created), session.session_id,
+                     sessions.clean_title(full_title, _TITLE_TEXT_CHARS) or "-", resume))
+    widths = [max(len(row[index]) for row in rows) for index in range(4)]
+    for row in rows:
+        print("  ".join([cell.ljust(width) for cell, width in zip(row[:4], widths)] + [row[4]]).rstrip())
+        if row[5] is not None:
+            print("  " + row[5])
+    if total > len(entries):
+        print("showing {} of {} sessions; use --limit 0 for all, or --grep TEXT to narrow".format(len(entries), total))
+    return accounts.EXIT_OK
+
+
+def _resume_command(source: _SessionSource, session: sessions.SessionInfo) -> str:
+    """续聊命令。Claude 按当前目录找会话，所以先 cd 到会话启动时的目录；目录未知时只给后半段。"""
+    resume = "{} --resume {}".format(source.launcher, session.session_id)
+    if session.directory is None:
+        return resume
+    return "cd {} && {}".format(shlex.quote(session.directory), resume)
+
+
+def _local_minute(moment: Optional[datetime]) -> str:
+    if moment is None:
+        return "-"
+    try:
+        return moment.astimezone().strftime("%Y-%m-%d %H:%M")
+    except (OverflowError, OSError, ValueError):
+        # 会话文件里的时间戳可以是任何合法的 ISO 时间；公元 1 年、9999 年这类值换算成本地时间会越界。
+        # 当作没有时间显示，不让一条坏记录中断整张表
+        return "-"
+
+
 def cmd_statusline(action: str, path: str, dry_run: bool) -> int:
     """包装或还原设置文件中的 statusLine 命令。文件不合法时退出 1 且不改动；其它写入错误由 main 统一处理。"""
     try:

{multi_claude_cli-0.9.0 → multi_claude_cli-0.10.0}/src/multi_claude/completion.py

@@ -20,7 +20,7 @@ POSITIONAL_KINDS = {
     "route": ["dir", "name"], "which": ["dir"], "rename": ["name"], "mcp": ["name"],
     "statusline": ["statusline", "file"], "handoff": ["name"], "login": ["name"], "set": ["name"],
     "run": ["name"], "path": ["name"], "restore": ["name"], "code": ["name", "file"],
-    "export": ["name", "file"], "import": ["file", "name"],
+    "export": ["name", "file"], "import": ["file", "name"], "sessions": ["name"],
 }
 # 选项值是路径、应按文件补全的选项。
 PATH_OPTIONS = ("-f", "--file", "--root", "--bin-dir", "--shared-dir")