feat: add stats, borrow and return

Every proxy keeps its figures in its workspace, but reading them meant
opening JSON files one proxy at a time, and the /stats page starts from
zero with each restart. `stats` reads all workspaces, jails included,
and shows how much of the saving is tool definitions rather than
compression, how many calls ran past the size where /clear pays more,
and when each weekly limit runs out at the current pace.

Switching accounts moves the whole profile, which is wrong when one
account is out of limit and the other lacks its plugins and settings.
`borrow` lends one account's login into another's profile for a while.
The old helper did this and failed twice: an abort left the swap half
done, and a token refreshed in one copy broke the other. Here the
profile's own login is written to a journal before anything changes,
the lent credentials file is a link to the lender's, and `return` puts
everything back from the journal, by hand or from a systemd timer.
Profiles that jails run in are refused unless asked for, since the
login decides whose account customer data goes out under, and status
reports a borrow whose timer was lost.
This commit is contained in:
nvrl committed 2026-09-23 17:59:45 +02:00
1 parent aea75fbf1c
commit 9ed50eab57
7 files changed
+1084 -1

No files matched your search

+66
View File
@@ -23,6 +23,10 @@ swap half-done. Here nothing moves: an account is a directory, and switching
means pointing `CLAUDE_CONFIG_DIR` at another one. There is nothing to restore,
and the plugins of an account come with it.
Lending a login is still useful when one account runs out of limit and its
profile is the one with everything set up, so `borrow` brings it back, built
against both ways the old helper failed -- see [Borrowing a login](#borrowing-a-login).
## How the switch reaches `claude`
`~/.local/bin/claude` is a small wrapper that asks this tool which profile is
@@ -87,6 +91,9 @@ workspaces over unchanged.
| `switch <account>` | make an account the one `claude` runs as |
| `add <name>` | register an account: profile, port, workspace, proxy, all at once |
| `remove <account>` | forget one; its profile directory stays |
| `stats [--json]` | what every proxy recorded since it was set up, side by side |
| `borrow <lender> [--into <account>] [--for 4h]` | run a profile on another account's login for a while |
| `return [account]` | give a borrowed login back |
| `completions [shell]` | print a completion script, or `--install` it |
| `setup` | wrapper, proxies, router and completions in one go |
| `adopt` | take over services that were written by hand |
@@ -113,6 +120,65 @@ directory and the proxy workspace stay where they are -- they hold a login,
projects and memories -- so a profile that still has credentials keeps showing
up in `list`, found rather than configured.
## What the proxies recorded
```sh
claude-account stats
```
Every account's proxy, and every jail's, keeps its figures in its workspace.
`stats` reads them all and puts them side by side: calls, input, how much the
proxy saved and how much of that is compression rather than tool definitions
held back, the cache-read share, and how many calls ran above 150k tokens of
context -- the size at which a `/clear` pays more than any proxy. Below the
table it says what the totals mean, and lists each account's weekly limit with
the pace of the last three hours and when that pace would use it up. `--json`
prints the same figures for scripts.
The figures are the proxy's own, counted since its workspace was created; the
counters on its `/stats` page start again with every restart.
## Borrowing a login
```sh
claude-account borrow personal --into work --for 4h
claude # a new session, on the personal login
claude-account return work # or wait for the four hours
```
The profile stays -- its plugins, settings, projects and memories -- and only
the login and the `oauthAccount` entry of `.claude.json` are lent. `--into`
defaults to the active account; without `--for` the borrow lasts until
`return`. Sessions that are already open keep the login they started with, so
the borrow is felt from the next session on.
What makes it safe where the old helper was not:
* **A journal before anything moves.** The profile's own credentials and
`oauthAccount` are written to `~/.local/share/claude-account/borrows/`
(mode 0600) first. `return` restores from it, whether it is run by hand, by
the timer `--for` sets, or after a crash or an interrupted borrow.
* **One login, not two copies.** The profile's `.credentials.json` becomes a
link to the lender's, so a token refreshed in either profile is the one both
use. If Claude Code replaces the link with a file, `return` gives whichever
copy expires later back to the lender.
* **Jails are refused.** A jail keeps customer data in a sandbox, and the
login decides whose account that data goes out under. Borrowing into a
profile a jail runs in needs `--with-jails`.
* **A lost timer is reported.** `--for` sets a transient user timer, which a
reboot drops; `status` and `doctor` then show the borrow as overdue with the
command that returns it.
The profile's proxy polls the lender's limits while the borrow lasts, and
counts the lender's calls in its figures. The `enqs-info` status line shows
`⇄ <lender>` next to the account name for as long as it does.
A borrow is for one person's own accounts. A login shared between people is
against Anthropic's terms, however it is passed around -- a Team plan with a
seat each is the way to pool limits. And a private account is covered by the
consumer terms, not the company's agreement: work and customer data belong in
the work login.
## Completions
```sh