multi-claude-cli 0.5.0__tar.gz → 0.7.0__tar.gz

{multi_claude_cli-0.5.0/src/multi_claude_cli.egg-info → multi_claude_cli-0.7.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: multi-claude-cli
-Version: 0.5.0
+Version: 0.7.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,6 +37,8 @@ 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.
+
 ```sh
 claude-work        # Claude Code with your work account
 claude-personal    # Claude Code with your personal account, in another terminal
@@ -62,6 +64,10 @@ 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.
+- **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.
 - **Add accounts** — create an account directory and a `claude-<name>` launcher, or adopt a directory you already have.
 - **Per-account proxy** — a local port, an HTTP(S) proxy URL, `off`, or `inherit`.
@@ -69,7 +75,6 @@ The launchers are plain shell scripts. They keep working even if you uninstall m
 - **One-step deployment** — `install.sh --config accounts.json` installs the tool and creates every account in the file.
 - **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.
-- **Hands off your credentials** — multi-claude never reads, copies or deletes logins. Its only keychain call checks whether an item exists.
 
 ## Requirements
 
@@ -245,6 +250,23 @@ The command becomes `<path of multi-claude> statusline-hook '<original command>'
 - If several settings files define `statusLine`, wrap the one that wins (for example a file passed with `--settings` in the launcher arguments).
 - Run `multi-claude statusline uninstall FILE` before uninstalling multi-claude; otherwise the status line stays empty because the wrapped command cannot be found. Running `install` again after multi-claude moves updates the path.
 
+#### Token history
+
+```sh
+multi-claude usage --history                   # tokens per day, last 7 days, every account
+multi-claude usage --history work --days 30 --by model
+```
+
+```text
+work:
+  DATE        INPUT   OUTPUT  CACHE READ  CACHE WRITE  REPLIES
+  2026-10-01  1,246  499,681  273,254,361   5,926,527      612
+```
+
+`--history` counts the replies in the account's session files on this machine (`projects/**/*.jsonl`, including subagents): input, output, cache-read and cache-write tokens per day (local time) or per model. Only these counters are read; nothing else from the conversations is printed or stored, and nothing is sent anywhere. Sessions on other machines and deleted sessions are not counted. A session copied with `handoff` appears in both accounts; the `TOTAL` block counts each reply once. `--json` prints the same numbers for scripts.
+
+`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.
+
 ### 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:
@@ -286,6 +308,22 @@ multi-claude add client-b --config-from work # start client-b with a copy of wor
 
 `--config-from` copies `settings.json` once; afterwards the two files are independent. A different existing `settings.json` in the new account, or a `settings.json` that the account shares, is a conflict and nothing is changed. Use [shared resources](#shared-resources) for settings that should stay the same in every account.
 
+### Opening VS Code for an account (experimental)
+
+```sh
+multi-claude code work ~/projects/app             # a separate VS Code window for work
+multi-claude code personal . -- --disable-gpu     # arguments after -- go to VS Code
+```
+
+The Claude Code extension uses the `CLAUDE_CONFIG_DIR` of the environment VS Code was started with, so a VS Code opened from the Dock always uses `~/.claude`. `code` starts VS Code with the account's environment (the same as `run`) and a separate user data directory, `<root>/.apps/<account directory>/vscode`. A separate user data directory is required: otherwise VS Code hands the request to the instance that is already running, with its own environment. Each account's instance starts with default VS Code settings; extensions are shared because they live in `~/.vscode/extensions`.
+
+Notes:
+
+- If an instance for the account is already running, the request goes to it; changes to the proxy or environment variables apply after that instance quits.
+- Setting `CLAUDE_CONFIG_DIR` in the extension's `claudeCode.environmentVariables` inside that instance overrides the account.
+- On macOS the `code` command passes the whole environment to `open --env`, so the values are briefly visible in the process list.
+- Verified with VS Code 1.139.1 and Claude Code extension 2.1.286 on macOS; `code` prints a warning because it relies on undocumented behaviour. It needs the `code` command on `PATH` (in VS Code: "Shell Command: Install 'code' command in PATH").
+
 ### Diagnostics and completion
 
 `multi-claude doctor` checks, without changing anything: the configuration and any unfinished migration, whether `claude` and the launcher directory are on `PATH`, whether each launcher is up to date and not hidden by another file of the same name, whether each account directory exists and is private (`0700`), the default account's link, broken shared links, whether a login exists, and variables such as `ANTHROPIC_API_KEY` that override the accounts' logins. Every problem comes with the command that fixes it. It exits with 1 when there is an error; `--json` prints the results for scripts.
@@ -347,6 +385,8 @@ With pipx, run `pipx upgrade multi-claude-cli`; with Homebrew, `brew upgrade mul
 
 The one in `~/.claude`, as before: multi-claude does not change it. After [migrating `~/.claude`](#migrating-claude) it is the migrated account. `claude-auto` picks an account by directory instead; see [Choosing an account by directory](#choosing-an-account-by-directory).
 
+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`.
+
 ### 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).
@@ -361,7 +401,7 @@ By default the numbers come from the cache that Claude Code writes in `.claude.j
 
 ### Does multi-claude read or copy my login?
 
-No. It never reads, copies or deletes credentials; its only keychain call checks whether an item exists. On macOS a login is tied to the account directory's path, which is why `rename` keeps the directory.
+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.
 
 ## Reference
 
@@ -381,6 +421,7 @@ No. It never reads, copies or deletes credentials; its only keychain call checks
 | `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 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 route DIR NAME`, `route DIR --remove`, `route --default NAME`, `route --no-default` | Choose an account by directory for `claude-auto`. |
 | `multi-claude which [DIR]` | Show which account `claude-auto` would use in `DIR` (default: the current directory). |
@@ -389,6 +430,7 @@ No. It never reads, copies or deletes credentials; its only keychain call checks
 | `multi-claude mcp NAME [ARG ...]` | Run `claude mcp ARG ...` as that account. |
 | `multi-claude run [NAME] [-- COMMAND ...]` | Run a command (default: `claude` with the fixed arguments) with the environment of the account's launcher. Without NAME, the account `claude-auto` would use. |
 | `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 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. |
@@ -464,7 +506,7 @@ If you move an account directory yourself, its launcher reports that the directo
 ./install.sh --uninstall
 ```
 
-This removes the tool only. Your configuration, account directories, logins and `claude-<name>` launchers stay; the launchers keep working because they do not depend on multi-claude. Run `multi-claude statusline uninstall FILE` first if you wrapped a status line.
+This removes the tool only. Your configuration, account directories (including the VS Code data in `<root>/.apps` created by `code`), logins and `claude-<name>` launchers stay; the launchers keep working because they do not depend on multi-claude. Run `multi-claude statusline uninstall FILE` first if you wrapped a status line.
 
 ## Contributing
 

{multi_claude_cli-0.5.0 → multi_claude_cli-0.7.0}/README.md

@@ -10,6 +10,8 @@
 
 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.
+
 ```sh
 claude-work        # Claude Code with your work account
 claude-personal    # Claude Code with your personal account, in another terminal
@@ -35,6 +37,10 @@ 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.
+- **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.
 - **Add accounts** — create an account directory and a `claude-<name>` launcher, or adopt a directory you already have.
 - **Per-account proxy** — a local port, an HTTP(S) proxy URL, `off`, or `inherit`.
@@ -42,7 +48,6 @@ The launchers are plain shell scripts. They keep working even if you uninstall m
 - **One-step deployment** — `install.sh --config accounts.json` installs the tool and creates every account in the file.
 - **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.
-- **Hands off your credentials** — multi-claude never reads, copies or deletes logins. Its only keychain call checks whether an item exists.
 
 ## Requirements
 
@@ -218,6 +223,23 @@ The command becomes `<path of multi-claude> statusline-hook '<original command>'
 - If several settings files define `statusLine`, wrap the one that wins (for example a file passed with `--settings` in the launcher arguments).
 - Run `multi-claude statusline uninstall FILE` before uninstalling multi-claude; otherwise the status line stays empty because the wrapped command cannot be found. Running `install` again after multi-claude moves updates the path.
 
+#### Token history
+
+```sh
+multi-claude usage --history                   # tokens per day, last 7 days, every account
+multi-claude usage --history work --days 30 --by model
+```
+
+```text
+work:
+  DATE        INPUT   OUTPUT  CACHE READ  CACHE WRITE  REPLIES
+  2026-10-01  1,246  499,681  273,254,361   5,926,527      612
+```
+
+`--history` counts the replies in the account's session files on this machine (`projects/**/*.jsonl`, including subagents): input, output, cache-read and cache-write tokens per day (local time) or per model. Only these counters are read; nothing else from the conversations is printed or stored, and nothing is sent anywhere. Sessions on other machines and deleted sessions are not counted. A session copied with `handoff` appears in both accounts; the `TOTAL` block counts each reply once. `--json` prints the same numbers for scripts.
+
+`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.
+
 ### 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:
@@ -259,6 +281,22 @@ multi-claude add client-b --config-from work # start client-b with a copy of wor
 
 `--config-from` copies `settings.json` once; afterwards the two files are independent. A different existing `settings.json` in the new account, or a `settings.json` that the account shares, is a conflict and nothing is changed. Use [shared resources](#shared-resources) for settings that should stay the same in every account.
 
+### Opening VS Code for an account (experimental)
+
+```sh
+multi-claude code work ~/projects/app             # a separate VS Code window for work
+multi-claude code personal . -- --disable-gpu     # arguments after -- go to VS Code
+```
+
+The Claude Code extension uses the `CLAUDE_CONFIG_DIR` of the environment VS Code was started with, so a VS Code opened from the Dock always uses `~/.claude`. `code` starts VS Code with the account's environment (the same as `run`) and a separate user data directory, `<root>/.apps/<account directory>/vscode`. A separate user data directory is required: otherwise VS Code hands the request to the instance that is already running, with its own environment. Each account's instance starts with default VS Code settings; extensions are shared because they live in `~/.vscode/extensions`.
+
+Notes:
+
+- If an instance for the account is already running, the request goes to it; changes to the proxy or environment variables apply after that instance quits.
+- Setting `CLAUDE_CONFIG_DIR` in the extension's `claudeCode.environmentVariables` inside that instance overrides the account.
+- On macOS the `code` command passes the whole environment to `open --env`, so the values are briefly visible in the process list.
+- Verified with VS Code 1.139.1 and Claude Code extension 2.1.286 on macOS; `code` prints a warning because it relies on undocumented behaviour. It needs the `code` command on `PATH` (in VS Code: "Shell Command: Install 'code' command in PATH").
+
 ### Diagnostics and completion
 
 `multi-claude doctor` checks, without changing anything: the configuration and any unfinished migration, whether `claude` and the launcher directory are on `PATH`, whether each launcher is up to date and not hidden by another file of the same name, whether each account directory exists and is private (`0700`), the default account's link, broken shared links, whether a login exists, and variables such as `ANTHROPIC_API_KEY` that override the accounts' logins. Every problem comes with the command that fixes it. It exits with 1 when there is an error; `--json` prints the results for scripts.
@@ -320,6 +358,8 @@ With pipx, run `pipx upgrade multi-claude-cli`; with Homebrew, `brew upgrade mul
 
 The one in `~/.claude`, as before: multi-claude does not change it. After [migrating `~/.claude`](#migrating-claude) it is the migrated account. `claude-auto` picks an account by directory instead; see [Choosing an account by directory](#choosing-an-account-by-directory).
 
+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`.
+
 ### 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).
@@ -334,7 +374,7 @@ By default the numbers come from the cache that Claude Code writes in `.claude.j
 
 ### Does multi-claude read or copy my login?
 
-No. It never reads, copies or deletes credentials; its only keychain call checks whether an item exists. On macOS a login is tied to the account directory's path, which is why `rename` keeps the directory.
+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.
 
 ## Reference
 
@@ -354,6 +394,7 @@ No. It never reads, copies or deletes credentials; its only keychain call checks
 | `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 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 route DIR NAME`, `route DIR --remove`, `route --default NAME`, `route --no-default` | Choose an account by directory for `claude-auto`. |
 | `multi-claude which [DIR]` | Show which account `claude-auto` would use in `DIR` (default: the current directory). |
@@ -362,6 +403,7 @@ No. It never reads, copies or deletes credentials; its only keychain call checks
 | `multi-claude mcp NAME [ARG ...]` | Run `claude mcp ARG ...` as that account. |
 | `multi-claude run [NAME] [-- COMMAND ...]` | Run a command (default: `claude` with the fixed arguments) with the environment of the account's launcher. Without NAME, the account `claude-auto` would use. |
 | `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 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. |
@@ -437,7 +479,7 @@ If you move an account directory yourself, its launcher reports that the directo
 ./install.sh --uninstall
 ```
 
-This removes the tool only. Your configuration, account directories, logins and `claude-<name>` launchers stay; the launchers keep working because they do not depend on multi-claude. Run `multi-claude statusline uninstall FILE` first if you wrapped a status line.
+This removes the tool only. Your configuration, account directories (including the VS Code data in `<root>/.apps` created by `code`), logins and `claude-<name>` launchers stay; the launchers keep working because they do not depend on multi-claude. Run `multi-claude statusline uninstall FILE` first if you wrapped a status line.
 
 ## Contributing
 

{multi_claude_cli-0.5.0 → multi_claude_cli-0.7.0}/src/multi_claude/__init__.py

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

{multi_claude_cli-0.5.0 → multi_claude_cli-0.7.0}/src/multi_claude/cli.py

@@ -18,8 +18,8 @@ import sys
 from datetime import datetime, timedelta, timezone
 from typing import List, Optional, Tuple
 
-from . import (__version__, accounts, completion, doctor, hook, identity, launcher, migrate, platform, restore,
-               routes, sessions, shellpath, statusline, usage)
+from . import (__version__, accounts, completion, doctor, history, hook, identity, launcher, migrate, platform,
+               restore, routes, sessions, shellpath, statusline, usage)
 from .actions import 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,
@@ -56,6 +56,7 @@ COMMAND_GROUPS = [
         ("handoff", "copy a session to another account"),
         ("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)"),
     ]),
     ("Setup and checks", [
         ("init, apply", "global settings; converge everything to config.json"),
@@ -175,6 +176,10 @@ def build_parser() -> argparse.ArgumentParser:
                                            "(from Claude Code's own cache; never reads credentials)")
     p_usage.add_argument("name", nargs="?")
     p_usage.add_argument("--json", action="store_true", help="print machine-readable JSON")
+    p_usage.add_argument("--history", action="store_true",
+                         help="show token usage counted from the session files on this machine instead")
+    p_usage.add_argument("--days", type=int, metavar="N", help="with --history: the last N days (default 7)")
+    p_usage.add_argument("--by", choices=("day", "model"), help="with --history: group by day (default) or model")
 
     p_doctor = sub.add_parser("doctor", description="check the accounts, launchers and environment (read-only)")
     p_doctor.add_argument("--json", action="store_true", help="print machine-readable JSON")
@@ -217,6 +222,12 @@ def build_parser() -> argparse.ArgumentParser:
     p_path = sub.add_parser("path", description="print the directory of an account")
     p_path.add_argument("name")
 
+    # code 的 VS Code 参数与 run 一样，在 argparse 之前从第一个 `--` 处切走。
+    p_code = sub.add_parser("code", description="open a separate VS Code instance with the environment of an "
+                                                "account (experimental): code NAME [PATH] [-- CODE_ARGS ...]")
+    p_code.add_argument("name")
+    p_code.add_argument("path", nargs="?", metavar="PATH")
+
     p_restore = sub.add_parser("restore", description="undo migrate-default: move the account directory back to "
                                                       "~/.claude and unregister the account; the login is kept")
     p_restore.add_argument("name")
@@ -285,7 +296,7 @@ def _add_write_options(parser: argparse.ArgumentParser) -> None:
 def _split_args_command(argv: List[str]) -> Tuple[List[str], Optional[List[str]]]:
     """子命令是 `args` 时，把第一个 `--` 之后的全部内容取出来作为参数列表；
     子命令是 `mcp` 或 `login` 时，账号名之后的全部内容原样作为 `claude mcp` / `claude auth login` 的参数（不经 argparse）；
-    子命令是 `run` 时，第一个 `--` 之后的内容是要运行的命令。
+    子命令是 `run` / `code` 时，第一个 `--` 之后的内容是要运行的命令 / 传给 VS Code 的参数。
 
     不能用 argparse.REMAINDER：可选位置参数加 --defaults 加 REMAINDER 时，
     `args --defaults -- --settings s` 会被解析成账号名 `--settings`（方案 §5.1.2，实测 3.10/3.11/3.13）。
@@ -307,8 +318,8 @@ def _split_args_command(argv: List[str]) -> Tuple[List[str], Optional[List[str]]
             example = "multi-claude mcp NAME list" if command == "mcp" else "multi-claude login NAME"
             raise UsageError("{} needs an account name first, e.g. `{}`".format(command, example))
         return argv[:command_index + 2], rest[1:]
-    if command_index is not None and argv[command_index] == "run":
-        # run 的命令从第一个 `--` 之后原样取出；没有 `--` 与 `--` 后为空都表示“没有命令”（运行 claude）。
+    if command_index is not None and argv[command_index] in ("run", "code"):
+        # run 的命令（code 的 VS Code 参数）从第一个 `--` 之后原样取出；没有 `--` 与 `--` 后为空都表示“没有”。
         if "--" not in argv[command_index + 1:]:
             return argv, None
         separator = argv.index("--", command_index + 1)
@@ -374,6 +385,10 @@ def main(argv: Optional[List[str]] = None) -> int:
         if args.command == "list":
             return cmd_list(verbose=args.verbose, as_json=args.json, names_only=args.names)
         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 == "which":
             return cmd_which(args.path)
@@ -394,7 +409,7 @@ def main(argv: Optional[List[str]] = None) -> int:
                 return accounts.EXIT_ERROR
             # 不加写锁：凭据由 Claude 自己写入，登录过程需要浏览器交互，可能持续很久。
             return cmd_login(args.name, args.launch_args or [])
-        if args.command in ("run", "path"):
+        if args.command in ("run", "path", "code"):
             if notice:
                 # 与 mcp 相同：迁移进行到一半时账号目录可能正在搬动。
                 error("finish the unfinished migration before running `{}`".format(args.command))
@@ -402,6 +417,8 @@ def main(argv: Optional[List[str]] = None) -> int:
             # 只读配置、不加写锁：run 会把进程换成目标命令，可能运行很久。
             if args.command == "path":
                 return cmd_path(args.name)
+            if args.command == "code":
+                return cmd_code(args.name, args.path, args.launch_args or [])
             return cmd_run(args.name, args.launch_args or [])
         if args.command == "mcp":
             if notice:
@@ -788,7 +805,7 @@ def _account_process_env(name: str) -> Tuple[Optional[dict], int]:
     if process_env is None:
         return None, code
     if shutil.which("claude", path=process_env.get("PATH")) is None:
-        error("claude not found in PATH")
+        error("claude not found in PATH" + _CLAUDE_NOT_FOUND_HINT)
         return None, 127
     return process_env, accounts.EXIT_OK
 
@@ -831,14 +848,29 @@ def cmd_run(name: Optional[str], command: List[str]) -> int:
         # 提示写 stderr：stdout 留给目标命令，`run -- cmd | …` 才不会混进这一行。
         print("[multi-claude] run: using account {} ({})".format(
             account.name, "route " + rule.path if rule is not None else "default"), file=sys.stderr)
-    process_env, code = _usable_account_env(config, account)
-    if process_env is None:
-        return code
     if not command:
         # 固定参数按启动命令的规则展开 `~`（launcher.render），两种启动方式收到的参数才逐项相同。
         command = ["claude"] + [launcher.expand_value(arg) for arg in config.effective_args(account)]
+    return _exec_as(config, account, command,
+                    not_found_hint=_CLAUDE_NOT_FOUND_HINT if command[0] == "claude" else "")
+
+
+# 找不到 claude 时附上的官方安装方法（https://code.claude.com/docs/en/setup，2026-10-03 核对）。
+# 只用于 multi-claude 自己的报错：启动命令里的文字不改，改了所有启动命令都会变成过期。
+_CLAUDE_NOT_FOUND_HINT = ("; install Claude Code: curl -fsSL https://claude.ai/install.sh | bash "
+                          "(other ways: https://code.claude.com/docs/en/setup)")
+
+
+def _exec_as(config: Config, account: Account, command: List[str], not_found_hint: str = "") -> int:
+    """run 与 code 共用：账号可用时以它的启动命令环境 exec 目标命令，成功则不返回。
+
+    返回值只出现在失败时：账号不可用 1，PATH 中找不到命令 127。
+    """
+    process_env, code = _usable_account_env(config, account)
+    if process_env is None:
+        return code
     if shutil.which(command[0], path=process_env.get("PATH")) is None:
-        error("{} not found in PATH".format(command[0]))
+        error("{} not found in PATH{}".format(command[0], not_found_hint))
         return 127
     sys.stdout.flush()
     sys.stderr.flush()
@@ -847,6 +879,54 @@ def cmd_run(name: Optional[str], command: List[str]) -> int:
     return accounts.EXIT_ERROR  # 不会执行到这里：execvpe 成功后不返回
 
 
+# code 依赖的未公开行为由 2026-10-02 实测确认的版本（方案 feature-vscode-launch §1.1）。
+VSCODE_VERIFIED_WITH = "VS Code 1.139.1, extension 2.1.286"
+# macOS 的 unix 套接字路径上限是 104 字节，VS Code 在 macOS 上把主套接字放在用户数据目录下（形如 1.13-main.sock，
+# 约 15 字节，见 VS Code out/main.js 构造套接字路径的函数）；Linux 设了 XDG_RUNTIME_DIR 时不放在这里。
+_SOCKET_DIR_WARN_LENGTH = 80
+_CODE_NOT_FOUND_HINT = "; in VS Code run \"Shell Command: Install 'code' command in PATH\""
+
+
+def cmd_code(name: str, path: Optional[str], code_args: List[str]) -> int:
+    """以账号环境打开一个独立的 VS Code 实例（实验功能，方案 feature-vscode-launch §5.1）。
+
+    必须给每个账号单独的 --user-data-dir：VS Code 已在运行时，同一用户数据目录的请求会转给已运行的实例，
+    新窗口沿用那个实例的环境，账号就不生效了。目录按账号目录名存放，rename 后数据仍在原处。
+    """
+    warn("experimental: code relies on undocumented behaviour of VS Code and the Claude Code extension "
+         "(verified with {})".format(VSCODE_VERIFIED_WITH))
+    config, _ = load_config()
+    account = config.find(_checked_name(name))
+    if account is None:
+        error("account {!r} is not registered".format(name))
+        return accounts.EXIT_ERROR
+    # 先确认账号可用、找得到 code 命令，再建目录：任何失败都不留下空的用户数据目录。
+    process_env, code = _usable_account_env(config, account)
+    if process_env is None:
+        return code
+    if shutil.which("code", path=process_env.get("PATH")) is None:
+        error("code not found in PATH{}".format(_CODE_NOT_FOUND_HINT))
+        return 127
+    data_dir = _private_dirs(expand(config.root), [".apps", account.dir, "vscode"])
+    if sys.platform == "darwin":
+        if len(data_dir) > _SOCKET_DIR_WARN_LENGTH:
+            warn("{} is long; VS Code's socket path inside it may exceed the 104-byte limit".format(data_dir))
+        warn("on macOS, code passes the whole environment (including this account's variables) to "
+             "`open --env`, so the values are briefly visible in the process list")
+    command = ["code", "--user-data-dir", data_dir] + ([path] if path else []) + list(code_args)
+    return _exec_as(config, account, command, not_found_hint=_CODE_NOT_FOUND_HINT)
+
+
+def _private_dirs(root: str, parts: List[str]) -> str:
+    """在 root 下逐级创建 parts，每一级都只允许本人访问（makedirs 的 mode 受 umask 影响，所以再 chmod）。"""
+    path = root
+    for part in parts:
+        path = os.path.join(path, part)
+        os.makedirs(path, mode=0o700, exist_ok=True)
+        os.chmod(path, 0o700)
+    return path
+
+
 def cmd_path(name: str) -> int:
     """打印账号目录；目录不存在时照样打印，但以 1 退出，脚本里 `cd "$(multi-claude path X)"` 不会静默进错目录。"""
     config, _ = load_config()
@@ -1220,14 +1300,15 @@ 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", "STATUS")]
+    rows = [("NAME", "LOGIN", "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), status))
+                     _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:
@@ -1294,6 +1375,8 @@ def _account_entries(config: Config, with_usage: bool = False) -> List[dict]:
             "link": accounts.default_link_status(config, account) if is_default else None,
             "keychain_service": identity.service_name(account.identity, directory),
             "credentials_file": identity.credentials_file(directory),
+            # history.jsonl 与会话文件的最大 mtime；只 stat 不读内容（方案 feature-usage-history §5.1.3）
+            "last_used": _iso(history.last_used(directory)),
         }
         if with_usage:
             entry["usage"] = usage.report_to_dict(usage.read_account_usage(config, account, now), now)
@@ -1388,6 +1471,86 @@ def _updated_cell(name: str, report: usage.UsageReport, now: datetime) -> str:
     return age + (" (statusline)" if report.source == usage.SOURCE_STATUSLINE else "")
 
 
+def _iso(moment: Optional[datetime]) -> Optional[str]:
+    return None if moment is None else moment.strftime("%Y-%m-%dT%H:%M:%SZ")
+
+
+def _last_used_cell(value: Optional[str], now: datetime) -> str:
+    if value is None:
+        return "-"
+    moment = datetime.strptime(value, "%Y-%m-%dT%H:%M:%SZ").replace(tzinfo=timezone.utc)
+    return _format_age(now - moment)
+
+
+_HISTORY_COLUMNS = ("INPUT", "OUTPUT", "CACHE READ", "CACHE WRITE", "REPLIES")
+
+
+def cmd_usage_history(name: Optional[str], days: Optional[int], by: str, as_json: bool) -> int:
+    """按天或按模型汇总本机会话记录里的 token 用量（方案 feature-usage-history §5.1.2）。
+
+    只读计数字段，不输出对话内容、不联网、不读凭据。各账号分别计数；TOTAL 跨账号按回复 ID 去重，
+    因为 handoff 复制过的会话在两个账号里都有同样的回复。
+    """
+    days = 7 if days is None else days
+    if not 1 <= days <= 366:
+        raise UsageError("--days must be between 1 and 366")
+    config, exists = load_config()
+    selected = list(config.accounts.values()) if exists else []
+    if name is not None:
+        account = config.find(_checked_name(name)) if exists else None
+        if account is None:
+            error("account {!r} is not registered".format(name))
+            return accounts.EXIT_ERROR
+        selected = [account]
+    local_now = datetime.now().astimezone()
+    start_local = (local_now - timedelta(days=days - 1)).replace(hour=0, minute=0, second=0, microsecond=0)
+    since = start_local.astimezone(timezone.utc)
+    per_account = []
+    combined: dict = {}
+    skipped = 0
+    for account in selected:
+        replies, unreadable = history.scan(accounts.account_dir(config, account.name), since)
+        skipped += unreadable
+        per_account.append((account.name, history.summarize(replies.values(), by)))
+        for reply_id, reply in replies.items():
+            # 同一回复出现在多个账号（handoff）时只算一次，计数仍按各项取最大值合并
+            combined[reply_id] = reply if reply_id not in combined else history.merge(combined[reply_id], reply)
+    if skipped:
+        warn("skipped {} session file(s) that could not be read".format(skipped))
+    total = history.summarize(combined.values(), by)
+    if as_json:
+        _print_json({"schema_version": 1, "days": days, "by": by,
+                     "accounts": [{"name": account_name, "rows": [row._asdict() for row in rows]}
+                                  for account_name, rows in per_account],
+                     "total": [row._asdict() for row in total]})
+        return accounts.EXIT_OK
+    if not exists:
+        info("no configuration yet at {}; run `multi-claude add NAME` to start".format(
+            os.path.join(platform.state_dir(), "config.json")))
+        return accounts.EXIT_OK
+    for account_name, rows in per_account:
+        _print_history_block(account_name, rows, by, days)
+    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.")
+    return accounts.EXIT_OK
+
+
+def _print_history_block(title: str, rows, by: str, days: int) -> None:
+    print("{}:".format(title))
+    if not rows:
+        print("  no replies in the last {} day{}".format(days, "" if days == 1 else "s"))
+        return
+    table = [("  " + ("DATE" if by == "day" else "MODEL"),) + _HISTORY_COLUMNS]
+    for row in rows:
+        table.append(("  " + row.key,) + tuple("{:,}".format(value) for value in row[1:]))
+    widths = [max(len(line[index]) for line in table) for index in range(len(table[0]))]
+    for line in table:
+        cells = [line[0].ljust(widths[0])] + [cell.rjust(width) for cell, width in zip(line[1:], widths[1:])]
+        print("  ".join(cells).rstrip())
+
+
 def _format_age(delta) -> str:
     minutes = max(0, int(delta.total_seconds() // 60))
     if minutes < 60:

{multi_claude_cli-0.5.0 → multi_claude_cli-0.7.0}/src/multi_claude/completion.py

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

{multi_claude_cli-0.5.0 → multi_claude_cli-0.7.0}/src/multi_claude/doctor.py

@@ -100,7 +100,8 @@ def _load() -> Tuple[Optional[Config], Check]:
 def _check_claude_on_path() -> Check:
     found = shutil.which("claude")
     if found is None:
-        return Check("claude-on-path", LEVEL_ERROR, "claude", "`claude` is not on PATH; install Claude Code")
+        return Check("claude-on-path", LEVEL_ERROR, "claude", "`claude` is not on PATH; install Claude Code: curl -fsSL https://claude.ai/install.sh "
+                     "| bash (other ways: https://code.claude.com/docs/en/setup)")
     return Check("claude-on-path", LEVEL_OK, "claude", found)