sideby 0.6.0 → 0.8.0

package/dist/src/runtime.js

@@ -2,6 +2,7 @@
 import { aliasesByAccount, discoverAccounts, resolveRef } from './core/accounts.js';
 import { addConfigAlias, aliasAccount, aliasArgs, aliasProblem, aliasRefs, handoffSettings, loadConfig, removeConfigAlias, } from './core/config.js';
 import { createAccount } from './core/create.js';
+import { bindDesktopDeps, checkAppData } from './core/desktop-app.js';
 import { applyFixes, runDoctor } from './core/doctor.js';
 import { UserError } from './core/errors.js';
 import { planHandoff } from './core/handoff.js';
@@ -13,6 +14,7 @@ import { prepareLaunch, which } from './core/launch.js';
 import { memoStore } from './core/memo-store.js';
 import { resolvePaths } from './core/paths.js';
 import { findResumeRoute } from './core/resume.js';
+import { SAME_LOGIN_FAMILIES, sameLoginGroups, sharedQuota } from './core/same-login.js';
 import { shareMeaning } from './core/share-meaning.js';
 import { SHELLS, shellInitScript, writeShellInitFile, } from './core/shell-init.js';
 import { groupSuggestion, MAX_COMPACT_WINDOW, MIN_COMPACT_WINDOW, } from './core/tuning.js';
@@ -83,6 +85,56 @@ export async function createRuntime(opts = {}) {
             out.push(...(await discoverAccounts(f, paths.home, ignore)));
         return out;
     };
+    /** Same Login groups (spec §3.21) among `list`: ref → the other refs. Only Families that group take part. */
+    const groupsOf = async (list) => {
+        const members = await Promise.all(list
+            .filter((a) => a.kind === 'subscription' && SAME_LOGIN_FAMILIES.has(a.family) && families.has(a.family))
+            .map(async (a) => {
+            const identity = await readIdentity(familyOf(a.family), a);
+            return { ref: a.ref, family: a.family, kind: a.kind, ...(identity ? { identity } : {}) };
+        }));
+        return sameLoginGroups(members);
+    };
+    /** The Accounts of `account`'s Same Login, other than itself; reads only its own Family. */
+    const peersOf = async (account) => {
+        const f = families.get(account.family);
+        if (!f || account.kind === 'api' || !SAME_LOGIN_FAMILIES.has(f.id))
+            return [];
+        const list = await discoverAccounts(f, paths.home, ignore);
+        const peers = (await groupsOf(list)).get(account.ref) ?? [];
+        return list.filter((a) => peers.includes(a.ref));
+    };
+    /** Every Account's Quota as shown (shared within a Same Login), reading each Account's own cache once. */
+    const quotasOf = async (list) => {
+        const [own, groups] = await Promise.all([
+            Promise.all(list.map(async (a) => [a.ref, await ownQuota(a)])).then((e) => new Map(e)),
+            groupsOf(list),
+        ]);
+        return new Map(list.map((a) => [a.ref, sharedQuota(a.ref, own, groups.get(a.ref) ?? [])]));
+    };
+    const ownQuota = async (account) => {
+        if (account.kind === 'api')
+            return { status: 'unavailable', reason: 'api-account' };
+        const f = familyOf(account.family);
+        if (!f.readQuota)
+            return { status: 'unavailable', reason: 'no-source' };
+        await memos.ready();
+        try {
+            const q = await f.readQuota(account, readContext());
+            // Only sideby marks a reading as borrowed from another Account (spec §3.21); a reader's own `from` is dropped.
+            if (q.status === 'ok' && q.from !== undefined) {
+                const { from: _from, ...own } = q;
+                return own;
+            }
+            return q;
+        }
+        catch (err) {
+            return { status: 'unavailable', reason: 'unrecognized', detail: err.message };
+        }
+        finally {
+            memos.saveSoon();
+        }
+    };
     const loginOf = async (a) => {
         if (a.kind === 'api')
             return 'not-needed';
@@ -207,13 +259,14 @@ export async function createRuntime(opts = {}) {
                     return undefined;
                 }
             };
-            const [installed, login, model, identity] = await Promise.all([
+            const [installed, login, model, identity, peers] = await Promise.all([
                 which(f.bin, env),
                 account.kind === 'api'
                     ? undefined
                     : safe('login state', f.loginState && (() => f.loginState(account))),
                 safe('model', f.model && (() => f.model(account))),
                 readIdentity(f, account),
+                peersOf(account).catch(() => []),
             ]);
             return {
                 ...account,
@@ -222,6 +275,7 @@ export async function createRuntime(opts = {}) {
                 login: account.kind === 'api' ? 'not-needed' : (login ?? 'unknown'),
                 ...(model ? { model } : {}),
                 ...(identity ? { identity } : {}),
+                ...(peers.length ? { sameLogin: peers.map((p) => p.ref) } : {}),
                 ...(problems.length ? { problems } : {}),
             };
         },
@@ -254,6 +308,8 @@ export async function createRuntime(opts = {}) {
                 // Checked for every Family in the run, also when Doctor is aimed at one Account, so the saved result
                 // of that Family keeps its skill warning.
                 skillVersion: packageVersion(),
+                // Desktop App data folders sideby made for an Account (spec §3.20).
+                extraChecks: (a) => checkAppData(loaded.plugins, paths.home, a),
             };
             // Auto Handoff warnings (spec §3.17) join the general Findings; they never fail Doctor.
             const all = await accounts();
@@ -433,21 +489,13 @@ export async function createRuntime(opts = {}) {
             };
         },
         async quota(account) {
-            if (account.kind === 'api')
-                return { status: 'unavailable', reason: 'api-account' };
-            const f = familyOf(account.family);
-            if (!f.readQuota)
-                return { status: 'unavailable', reason: 'no-source' };
-            await memos.ready();
-            try {
-                return await f.readQuota(account, readContext());
-            }
-            catch (err) {
-                return { status: 'unavailable', reason: 'unrecognized', detail: err.message };
-            }
-            finally {
-                memos.saveSoon();
-            }
+            const peers = await peersOf(account);
+            if (!peers.length)
+                return ownQuota(account);
+            return (await quotasOf([account, ...peers])).get(account.ref);
+        },
+        async sameLogin(account) {
+            return (await peersOf(account)).map((a) => a.ref);
         },
         async usage(account) {
             const f = familyOf(account.family);
@@ -553,21 +601,36 @@ export async function createRuntime(opts = {}) {
                 throw new UserError(`no ${f.title} accounts yet; create one with \`sideby new ${f.id} <name>\``, {
                     code: 'no-accounts',
                 });
-            // Only the login state and Quota: no identity, model or Host lookups are needed to rank.
+            // Login state, Quota and Same Login (spec §3.21): no model or Host lookups are needed to rank.
+            const [quotas, groups] = await Promise.all([quotasOf(list), groupsOf(list)]);
             const candidates = await Promise.all(list.map(async (a) => {
-                const [login, quota] = await Promise.all([loginOf(a), rt.quota(a)]);
-                return { ref: a.ref, name: a.name, isMain: a.isMain, kind: a.kind, login, quota };
+                const peers = groups.get(a.ref);
+                return {
+                    ref: a.ref,
+                    name: a.name,
+                    isMain: a.isMain,
+                    kind: a.kind,
+                    login: await loginOf(a),
+                    quota: quotas.get(a.ref),
+                    ...(peers ? { sameLogin: peers } : {}),
+                };
             }));
-            return planHandoff(f.id, candidates, readContext().now, o);
+            // The current Account: the one sideby started this process from, when it belongs to this Family.
+            const current = env.SIDEBY_ACCOUNT;
+            const from = current && list.some((a) => a.ref === current) ? current : undefined;
+            return planHandoff(f.id, candidates, readContext().now, { ...o, ...(from ? { from } : {}) });
         },
         handoffSettings: () => handoffSettings(config),
         async handoffDecision(origin, used, opts = {}) {
-            const candidates = await Promise.all((await accounts()).map(async (a) => {
+            const all = await accounts();
+            const [quotas, groups] = await Promise.all([quotasOf(all), groupsOf(all)]);
+            const candidates = await Promise.all(all.map(async (a) => {
                 const f = familyOf(a.family);
-                const [installed, login, quota, identity] = await Promise.all([
+                const quota = quotas.get(a.ref);
+                const peers = groups.get(a.ref);
+                const [installed, login, identity] = await Promise.all([
                     which(f.bin, env),
                     loginOf(a),
-                    rt.quota(a),
                     readIdentity(f, a),
                 ]);
                 let receive = false;
@@ -587,6 +650,7 @@ export async function createRuntime(opts = {}) {
                     login,
                     quota,
                     ...(identity ? { identity } : {}),
+                    ...(peers ? { sameLogin: peers } : {}),
                     installed: installed !== null,
                     receive,
                 };
@@ -606,5 +670,7 @@ export async function createRuntime(opts = {}) {
         },
         readContext,
     };
+    if (opts.desktop)
+        bindDesktopDeps(rt, opts.desktop);
     return rt;
 }

package/dist/src/types.d.ts

@@ -214,6 +214,11 @@ export type QuotaResult = {
     observedAt: string;
     source: string;
     plan?: string;
+    /**
+     * Set by sideby, never by a Family's reader: the Account this reading was taken from, when it is another
+     * Account signed in as the same login (spec §3.21). `observedAt` is that Account's time.
+     */
+    from?: string;
 } | {
     status: 'unavailable';
     reason: QuotaUnavailableReason;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sideby",
-  "version": "0.6.0",
+  "version": "0.8.0",
   "description": "Run work, personal and API-key accounts at the same time, without their configs drifting apart.",
   "license": "MIT",
   "author": "Adonis0123 (https://github.com/Adonis0123)",
@@ -77,5 +77,5 @@
   },
   "packageManager": "pnpm@10.15.0",
   "readmeFilename": "README.md",
-  "readme": "<p align=\"center\">\n  <img alt=\"sideby: work, personal and API-key accounts, one terminal each, one shared config\" src=\"https://raw.githubusercontent.com/Adonis0123/sideby/main/docs/assets/banner.jpg\" width=\"880\">\n</p>\n\n<p align=\"center\">\n  <b>Run work, personal and API-key accounts at the same time, without their configs drifting apart.</b><br>\n  Each account is its own directory and its own terminal. Skills, hooks and settings stay linked to your main account. Claude Code, Codex, Grok Build and pi.\n</p>\n\n<p align=\"center\">\n  <a href=\"https://www.npmjs.com/package/sideby\"><img alt=\"npm\" src=\"https://img.shields.io/npm/v/sideby\"></a>\n  <a href=\"https://github.com/Adonis0123/sideby/actions/workflows/ci.yml\"><img alt=\"CI\" src=\"https://github.com/Adonis0123/sideby/actions/workflows/ci.yml/badge.svg\"></a>\n  <img alt=\"Node 22.18+\" src=\"https://img.shields.io/badge/node-%E2%89%A522.18-339933\">\n  <a href=\"LICENSE\"><img alt=\"MIT\" src=\"https://img.shields.io/badge/license-MIT-blue\"></a>\n</p>\n\n<p align=\"center\">English | <a href=\"README.zh-CN.md\">中文</a></p>\n\n## Why not just an alias?\n\n`CLAUDE_CONFIG_DIR` plus a shell alias already starts a second account. It does not keep skills and settings in one place, and it does not show quota for every account. [Does this break a provider's terms?](docs/guide/faq.md#terms)\n\n| | At the same time | Skills, hooks, settings | Quota and usage | Setup |\n|---|---|---|---|---|\n| `CLAUDE_CONFIG_DIR` and an alias | Yes. Each terminal exports the variable. | Each directory is its own copy. They drift unless you symlink by hand. | That session's status line | One alias per account |\n| [cc-switch](https://github.com/farion1231/cc-switch) | Enabling a provider writes the host's live config, so open sessions share that switch. | Plugin settings are copied across providers as a separate step. | The active provider, from its quota endpoint | Install the desktop app |\n| sideby | Yes. `sideby run` selects the directory for that process and leaves your shell alone. | Linked to the main account. `sideby doctor --fix` repairs copies. Sign-in and sessions stay separate. | Every account, from local files. Claude needs `quota setup`. | `npm i -g sideby`, then `sideby new` and sign in |\n\ncc-switch's docs describe that switch: it writes the live settings file ([README](https://github.com/farion1231/cc-switch#readme)). [#1105](https://github.com/farion1231/cc-switch/issues/1105) and [#2908](https://github.com/farion1231/cc-switch/issues/2908) ask for several sessions at once. [#1106](https://github.com/farion1231/cc-switch/issues/1106) is closed; the maintainer says Claude Code's \"open terminal\" can start one provider without changing the global config.\n\n## Quick start\n\nRequires Node 22.18+ and at least one Host CLI (Claude Code, Codex, Grok Build or pi) installed. AI agents: follow the setup steps in [`llms.txt`](llms.txt) (\"Set up sideby for a user\") instead.\n\n```sh\nnpm i -g sideby\nsideby new claude work        # create ~/.claude-work, sharing ~/.claude's skills and hooks\nsideby login claude:work      # sign in once\nsideby run work               # Claude Code on the work account\nsideby ui                     # every account's quota at http://127.0.0.1:17420\n```\n\n`sideby run claude:main` keeps using `~/.claude` in another terminal at the same time. Arguments after `--` go to the Host: `sideby run work -- --resume`. To try it without installing, run `npx sideby`.\n\n## Set up with your AI agent\n\nPaste this into Claude Code, Codex or any coding agent:\n\n```text\nInstall the sideby CLI (npm package `sideby`) and its agent skill, then set up a second Claude Code account for me.\nFollow \"Set up sideby for a user\" in https://raw.githubusercontent.com/Adonis0123/sideby/main/llms.txt\n```\n\nThe agent checks Node and your Host CLIs, installs sideby and the skill, creates the account, tells you what it shares with your main one and makes its short command work. You sign in once in your browser; the agent gives you that one command. Once the skill is installed, short requests work too: \"add another Claude account, cc008\", \"what do my Codex accounts share?\", \"which account still has quota?\".\n\n## What it looks like\n\n<img alt=\"Two terminals: the personal account and the work account running at the same time, both linked to the main account's skills and settings, then the local quota panel, and at 95% Auto Handoff moving work's session to the next account\" src=\"https://raw.githubusercontent.com/Adonis0123/sideby/main/docs/assets/demo.gif\" width=\"1280\">\n\n<picture>\n  <source media=\"(prefers-color-scheme: dark)\" srcset=\"https://raw.githubusercontent.com/Adonis0123/sideby/main/docs/assets/panel-dark.png\">\n  <source media=\"(prefers-color-scheme: light)\" srcset=\"https://raw.githubusercontent.com/Adonis0123/sideby/main/docs/assets/panel.png\">\n  <img alt=\"sideby panel: every account's 5h and 7d quota, 7-day token usage and health in one page\" src=\"https://raw.githubusercontent.com/Adonis0123/sideby/main/docs/assets/panel.png\" width=\"1280\">\n</picture>\n\n## What else it does\n\n| You want to | Run | Guide |\n|---|---|---|\n| Add an API key account (DeepSeek, a gateway, …) | `sideby new claude deepseek --api` | [API accounts](docs/guide/usage.md#api-accounts) |\n| Find and fix config drift between accounts | `sideby doctor --fix` | [Doctor](docs/guide/usage.md#doctor) |\n| See Claude quota (Codex needs no setup) | `sideby quota setup claude --yes` | [Claude quota](docs/guide/usage.md#claude-quota) |\n| Find the cheapest auto-compact size from your own sessions, and use it in one click | `sideby tune` (or the panel's Context tuning tab) | [Context tuning](docs/guide/usage.md#context-tuning) |\n| See each account's model and effort, and set them per account | `sideby model <account>` (or click the model in the panel) | [Model and effort](docs/guide/usage.md#model-and-effort) |\n| Move on when an account hits its limit | `sideby next claude` | [Handoff](docs/guide/usage.md#when-an-account-hits-its-limit) |\n| Let a running task move to the next account by itself when quota runs low (off by default; see the risk) | `sideby handoff enable` (or the panel) | [Auto Handoff](docs/guide/usage.md#auto-handoff) |\n| Short commands such as `ccw` | `sideby alias add ccw claude:work` | [Shell functions](docs/guide/configuration.md#shell-functions) |\n| Reopen a session from Orca and the like in the account that holds it | `\"resumeRouting\": true` in config | [Resuming from other tools](docs/guide/configuration.md#resuming-from-other-tools) |\n| Open the panel from the Dock or app menu | `sideby app install` | [Desktop app](docs/guide/panel.md#desktop-app) |\n| Show the panel inside your own local page | `createPanelHandler()` | [Embed the panel](docs/guide/panel.md#embed-the-panel) |\n| Add a Host or a pre-launch check | a local plugin | [Plugins](docs/guide/plugins.md) |\n\n## Supported hosts\n\n| Host | Account directories | Sign-in | Quota | Usage (7 days) |\n|---|---|---|---|---|\n| Claude Code | `~/.claude`, `~/.claude-<name>` | `claude auth login` | ✓ after `quota setup claude` | ✓ |\n| Codex CLI | `~/.codex`, `~/.codex-<name>` | `codex login` | ✓ | ✓ |\n| Grok Build | `~/.grok`, `~/.grok-<name>` | `grok login` | no public source | no public source |\n| pi | `~/.pi/agent`, `~/.pi-<name>/agent` | `/login` inside pi | no public source | no public source |\n\nsideby starts the official binary on your `PATH` and never patches it. Tested versions and per-Host notes are in the [guide](docs/guide/usage.md#host-notes).\n\n## Platforms\n\nmacOS and Linux. CI runs the suite on `ubuntu-latest` and `macos-latest`, Node 22 and 24. **Windows is untested.** `sideby app` only installs a launcher on macOS and Linux. Linked items are symlinks, `sideby shell-init` prints bash and zsh functions, and the Claude quota wrapper runs `/bin/sh`.\n\n## Roadmap\n\n**Gemini CLI.** Gemini can point at another config directory with `GEMINI_CONFIG_DIR`. Older docs use `GEMINI_CLI_HOME`; current builds treat that name as deprecated, and exit on startup if it is set together with an exact directory override. A sideby family still needs a tested Gemini version, a login check that does not read tokens, and a list of which files to link or copy. That is more than a small patch, so it is not in this version.\n\n## Safe by design\n\n- It never edits a Host's global config to switch accounts. It moves a task to another account only when you turn on Auto Handoff, and never proxies requests or pools logins.\n- It never reads, prints or sends a credential value. Nothing leaves your machine: sideby calls no remote service.\n- `doctor --fix` never replaces a real file and never changes where a link points.\n\nDetails and the terms-of-service question are in the [FAQ](docs/guide/faq.md).\n\nUsage questions and ideas go in [Discussions](https://github.com/Adonis0123/sideby/discussions).\n\n## Docs\n\n- [Using sideby](docs/guide/usage.md): accounts, API accounts, Doctor, quota, Handoff, Host notes\n- [Commands](docs/guide/commands.md): every command, exit codes and `--json`\n- [Configuration](docs/guide/configuration.md): `config.json`, aliases, shell functions\n- [Panel](docs/guide/panel.md): the panel, desktop app and embedding\n- [Plugins](docs/guide/plugins.md): write your own Family or launch hook\n- [FAQ](docs/guide/faq.md): terms of service, data locations, alternatives, uninstall\n- [Changelog](https://github.com/Adonis0123/sideby/releases)\n\n## For AI agents\n\n- [`llms.txt`](llms.txt): setup steps, commands, JSON contract and plugin API in one index. `sideby families --json` states what each Host's accounts share.\n- [`skills/sideby/SKILL.md`](skills/sideby/SKILL.md): one Agent Skill for seeing, repairing and creating accounts and for moving on when one hits its limit. Install with `npx skills add Adonis0123/sideby -g`; `sideby doctor` warns when the installed copy is for another sideby version.\n- [`AGENTS.md`](AGENTS.md): rules for agents working on this repository.\n\n## License\n\n[MIT](LICENSE)\n"
+  "readme": "<p align=\"center\">\n  <img alt=\"sideby: work, personal and API-key accounts, one terminal each, one shared config\" src=\"https://raw.githubusercontent.com/Adonis0123/sideby/main/docs/assets/banner.jpg\" width=\"880\">\n</p>\n\n<p align=\"center\">\n  <b>Run work, personal and API-key accounts at the same time, without their configs drifting apart.</b><br>\n  Each account is its own directory and its own terminal. Skills, hooks and settings stay linked to your main account. Claude Code, Codex, Grok Build and pi.\n</p>\n\n<p align=\"center\">\n  <a href=\"https://www.npmjs.com/package/sideby\"><img alt=\"npm\" src=\"https://img.shields.io/npm/v/sideby\"></a>\n  <a href=\"https://github.com/Adonis0123/sideby/actions/workflows/ci.yml\"><img alt=\"CI\" src=\"https://github.com/Adonis0123/sideby/actions/workflows/ci.yml/badge.svg\"></a>\n  <img alt=\"Node 22.18+\" src=\"https://img.shields.io/badge/node-%E2%89%A522.18-339933\">\n  <a href=\"LICENSE\"><img alt=\"MIT\" src=\"https://img.shields.io/badge/license-MIT-blue\"></a>\n</p>\n\n<p align=\"center\">English | <a href=\"README.zh-CN.md\">中文</a></p>\n\n## Why not just an alias?\n\n`CLAUDE_CONFIG_DIR` plus a shell alias already starts a second account. It does not keep skills and settings in one place, and it does not show quota for every account. [Does this break a provider's terms?](docs/guide/faq.md#terms)\n\n| | At the same time | Skills, hooks, settings | Quota and usage | Setup |\n|---|---|---|---|---|\n| `CLAUDE_CONFIG_DIR` and an alias | Yes. Each terminal exports the variable. | Each directory is its own copy. They drift unless you symlink by hand. | That session's status line | One alias per account |\n| [cc-switch](https://github.com/farion1231/cc-switch) | Enabling a provider writes the host's live config, so open sessions share that switch. | Plugin settings are copied across providers as a separate step. | The active provider, from its quota endpoint | Install the desktop app |\n| sideby | Yes. `sideby run` selects the directory for that process and leaves your shell alone. | Linked to the main account. `sideby doctor --fix` repairs copies. Sign-in and sessions stay separate. | Every account, from local files. Claude needs `quota setup`. | `npm i -g sideby`, then `sideby new` and sign in |\n\ncc-switch's docs describe that switch: it writes the live settings file ([README](https://github.com/farion1231/cc-switch#readme)). [#1105](https://github.com/farion1231/cc-switch/issues/1105) and [#2908](https://github.com/farion1231/cc-switch/issues/2908) ask for several sessions at once. [#1106](https://github.com/farion1231/cc-switch/issues/1106) is closed; the maintainer says Claude Code's \"open terminal\" can start one provider without changing the global config.\n\n## Quick start\n\nRequires Node 22.18+ and at least one Host CLI (Claude Code, Codex, Grok Build or pi) installed. AI agents: follow the setup steps in [`llms.txt`](llms.txt) (\"Set up sideby for a user\") instead.\n\n```sh\nnpm i -g sideby\nsideby new claude work        # create ~/.claude-work, sharing ~/.claude's skills and hooks\nsideby login claude:work      # sign in once\nsideby run work               # Claude Code on the work account\nsideby ui                     # every account's quota at http://127.0.0.1:17420\n```\n\n`sideby run claude:main` keeps using `~/.claude` in another terminal at the same time. Arguments after `--` go to the Host: `sideby run work -- --resume`. To try it without installing, run `npx sideby`.\n\n## Set up with your AI agent\n\nPaste this into Claude Code, Codex or any coding agent:\n\n```text\nInstall the sideby CLI (npm package `sideby`) and its agent skill, then set up a second Claude Code account for me.\nFollow \"Set up sideby for a user\" in https://raw.githubusercontent.com/Adonis0123/sideby/main/llms.txt\n```\n\nThe agent checks Node and your Host CLIs, installs sideby and the skill, creates the account, tells you what it shares with your main one and makes its short command work. You sign in once in your browser; the agent gives you that one command. Once the skill is installed, short requests work too: \"add another Claude account, cc008\", \"what do my Codex accounts share?\", \"which account still has quota?\".\n\n## What it looks like\n\n<img alt=\"Two terminals: the personal account and the work account running at the same time, both linked to the main account's skills and settings, then the local quota panel, and at 95% Auto Handoff moving work's session to the next account\" src=\"https://raw.githubusercontent.com/Adonis0123/sideby/main/docs/assets/demo.gif\" width=\"1280\">\n\n<picture>\n  <source media=\"(prefers-color-scheme: dark)\" srcset=\"https://raw.githubusercontent.com/Adonis0123/sideby/main/docs/assets/panel-dark.png\">\n  <source media=\"(prefers-color-scheme: light)\" srcset=\"https://raw.githubusercontent.com/Adonis0123/sideby/main/docs/assets/panel.png\">\n  <img alt=\"sideby panel: every account's 5h and 7d quota, 7-day token usage and health in one page\" src=\"https://raw.githubusercontent.com/Adonis0123/sideby/main/docs/assets/panel.png\" width=\"1280\">\n</picture>\n\n## What else it does\n\n| You want to | Run | Guide |\n|---|---|---|\n| Add an API key account (DeepSeek, a gateway, …) | `sideby new claude deepseek --api` | [API accounts](docs/guide/usage.md#api-accounts) |\n| Find and fix config drift between accounts | `sideby doctor --fix` | [Doctor](docs/guide/usage.md#doctor) |\n| See Claude quota (Codex needs no setup) | `sideby quota setup claude --yes` | [Claude quota](docs/guide/usage.md#claude-quota) |\n| Find the cheapest auto-compact size from your own sessions, and use it in one click | `sideby tune` (or the panel's Context tuning tab) | [Context tuning](docs/guide/usage.md#context-tuning) |\n| See each account's model and effort, and set them per account | `sideby model <account>` (or click the model in the panel) | [Model and effort](docs/guide/usage.md#model-and-effort) |\n| Move on when an account hits its limit | `sideby next claude` | [Handoff](docs/guide/usage.md#when-an-account-hits-its-limit) |\n| Let a running task move to the next account by itself when quota runs low (off by default; see the risk) | `sideby handoff enable` (or the panel) | [Auto Handoff](docs/guide/usage.md#auto-handoff) |\n| Short commands such as `ccw` | `sideby alias add ccw claude:work` | [Shell functions](docs/guide/configuration.md#shell-functions) |\n| Reopen a session from Orca and the like in the account that holds it | `\"resumeRouting\": true` in config | [Resuming from other tools](docs/guide/configuration.md#resuming-from-other-tools) |\n| Open Claude Desktop or the Codex app as one account, several side by side (macOS) | `sideby desktop claude:work` (or the panel) | [Desktop apps](docs/guide/usage.md#desktop-apps) |\n| Open the panel from the Dock or app menu | `sideby app install` | [Panel app](docs/guide/panel.md#panel-app) |\n| Show the panel inside your own local page | `createPanelHandler()` | [Embed the panel](docs/guide/panel.md#embed-the-panel) |\n| Add a Host or a pre-launch check | a local plugin | [Plugins](docs/guide/plugins.md) |\n\n## Supported hosts\n\n| Host | Account directories | Sign-in | Quota | Usage (7 days) |\n|---|---|---|---|---|\n| Claude Code | `~/.claude`, `~/.claude-<name>` | `claude auth login` | ✓ after `quota setup claude` | ✓ |\n| Codex CLI | `~/.codex`, `~/.codex-<name>` | `codex login` | ✓ | ✓ |\n| Grok Build | `~/.grok`, `~/.grok-<name>` | `grok login` | no public source | no public source |\n| pi | `~/.pi/agent`, `~/.pi-<name>/agent` | `/login` inside pi | no public source | no public source |\n\nsideby starts the official binary on your `PATH` and never patches it. Tested versions and per-Host notes are in the [guide](docs/guide/usage.md#host-notes).\n\n## Platforms\n\nmacOS and Linux. CI runs the suite on `ubuntu-latest` and `macos-latest`, Node 22 and 24. **Windows is untested.** `sideby app` only installs a launcher on macOS and Linux. Linked items are symlinks, `sideby shell-init` prints bash and zsh functions, and the Claude quota wrapper runs `/bin/sh`.\n\n## Roadmap\n\n**Gemini CLI.** Gemini can point at another config directory with `GEMINI_CONFIG_DIR`. Older docs use `GEMINI_CLI_HOME`; current builds treat that name as deprecated, and exit on startup if it is set together with an exact directory override. A sideby family still needs a tested Gemini version, a login check that does not read tokens, and a list of which files to link or copy. That is more than a small patch, so it is not in this version.\n\n## Safe by design\n\n- It never edits a Host's global config to switch accounts. It moves a task to another account only when you turn on Auto Handoff, and never proxies requests or pools logins.\n- It never reads, prints or sends a credential value. Nothing leaves your machine: sideby calls no remote service.\n- `doctor --fix` never replaces a real file and never changes where a link points.\n\nDetails and the terms-of-service question are in the [FAQ](docs/guide/faq.md).\n\nUsage questions and ideas go in [Discussions](https://github.com/Adonis0123/sideby/discussions).\n\n## Docs\n\n- [Using sideby](docs/guide/usage.md): accounts, API accounts, Doctor, quota, Handoff, Host notes\n- [Commands](docs/guide/commands.md): every command, exit codes and `--json`\n- [Configuration](docs/guide/configuration.md): `config.json`, aliases, shell functions\n- [Panel](docs/guide/panel.md): the panel, panel app and embedding\n- [Plugins](docs/guide/plugins.md): write your own Family or launch hook\n- [FAQ](docs/guide/faq.md): terms of service, data locations, alternatives, uninstall\n- [Changelog](https://github.com/Adonis0123/sideby/releases)\n\n## For AI agents\n\n- [`llms.txt`](llms.txt): setup steps, commands, JSON contract and plugin API in one index. `sideby families --json` states what each Host's accounts share.\n- [`skills/sideby/SKILL.md`](skills/sideby/SKILL.md): one Agent Skill for seeing, repairing and creating accounts and for moving on when one hits its limit. Install with `npx skills add Adonis0123/sideby -g`; `sideby doctor` warns when the installed copy is for another sideby version.\n- [`AGENTS.md`](AGENTS.md): rules for agents working on this repository.\n\n## License\n\n[MIT](LICENSE)\n"
 }

package/schemas/desktop.json

@@ -0,0 +1,80 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "sideby/desktop.json",
+  "type": "object",
+  "required": [
+    "schemaVersion",
+    "ref",
+    "family",
+    "app",
+    "appPath",
+    "action",
+    "createdAppData",
+    "linked",
+    "notices"
+  ],
+  "properties": {
+    "schemaVersion": {
+      "type": "number",
+      "const": 1
+    },
+    "ref": {
+      "type": "string"
+    },
+    "family": {
+      "type": "string"
+    },
+    "app": {
+      "type": "string",
+      "description": "The desktop app, for example `Claude Desktop`."
+    },
+    "appPath": {
+      "type": "string"
+    },
+    "action": {
+      "anyOf": [
+        {
+          "type": "string",
+          "const": "started"
+        },
+        {
+          "type": "string",
+          "const": "focused"
+        },
+        {
+          "type": "string",
+          "const": "already-running"
+        }
+      ],
+      "description": "`started`: a new window for this account; `focused`: its running window was brought to the front; `already-running`: it runs but could not be brought to the front."
+    },
+    "appData": {
+      "type": "string",
+      "description": "This account's app data folder; absent for the main account, which uses the app's default."
+    },
+    "createdAppData": {
+      "type": "boolean"
+    },
+    "linked": {
+      "type": "array",
+      "items": {
+        "type": "string"
+      },
+      "description": "Files linked into a new app data folder from the main account's (claude_desktop_config.json)."
+    },
+    "command": {
+      "type": "array",
+      "items": {
+        "type": "string"
+      },
+      "description": "The `open` command sideby ran."
+    },
+    "notices": {
+      "type": "array",
+      "items": {
+        "type": "string"
+      }
+    }
+  },
+  "title": "sideby desktop --json"
+}

package/schemas/list.json

@@ -147,11 +147,38 @@
                 },
                 "description": "Who the account is signed in as, from the host's login file: identity fields only, never a token (ADR-0003)."
               },
+              "sameLogin": {
+                "type": "array",
+                "items": {
+                  "type": "string"
+                },
+                "description": "The other accounts signed in as the same login (same family, email and organization), which share one quota (spec §3.21). Absent when there are none."
+              },
               "problems": {
                 "type": "array",
                 "items": {
                   "type": "string"
                 }
+              },
+              "desktopApp": {
+                "type": "object",
+                "required": [
+                  "app",
+                  "installed",
+                  "running"
+                ],
+                "properties": {
+                  "app": {
+                    "type": "string"
+                  },
+                  "installed": {
+                    "type": "boolean"
+                  },
+                  "running": {
+                    "type": "boolean"
+                  }
+                },
+                "description": "The family's desktop app for this account (macOS, subscription accounts of claude and codex): whether it is installed and whether this account's own window runs now. Open it with `sideby desktop <account>`."
               }
             }
           }

package/schemas/next.json

@@ -17,6 +17,10 @@
     "family": {
       "type": "string"
     },
+    "from": {
+      "type": "string",
+      "description": "The account `sideby next` runs in (SIDEBY_ACCOUNT, set by sideby for the sessions it starts), when it belongs to this family."
+    },
     "pick": {
       "anyOf": [
         {
@@ -97,6 +101,14 @@
           "observedAt": {
             "type": "string",
             "description": "When the account's quota was recorded (its last session)."
+          },
+          "quotaFrom": {
+            "type": "string",
+            "description": "The account the quota was read from, when it is another account of the same login."
+          },
+          "sameLoginAs": {
+            "type": "string",
+            "description": "The current account (`from`), when this one is signed in as the same login: it shares that quota and is never picked."
           }
         }
       },

package/schemas/quota.json

@@ -86,6 +86,10 @@
                   },
                   "plan": {
                     "type": "string"
+                  },
+                  "from": {
+                    "type": "string",
+                    "description": "The account this reading was taken from, when it is another account of the same login (spec §3.21); observedAt is its time."
                   }
                 }
               },

package/skills/sideby/SKILL.md

@@ -2,7 +2,7 @@
 name: sideby
 description: Use when the user runs, or wants to run, several AI coding accounts (Claude Code, Codex, Grok Build, pi) side by side. Covers installing sideby and setting up a new account ("install sideby", "set up another Claude account", "add cc008", "配置一个 cc00x", "再加一个 Codex 账号"), explaining what accounts share and what stays separate ("what do my accounts share?", "这些账号共享了什么"), showing which account a session is ("show [cc001] in the status line", "加上账号标识"), seeing accounts, quota and usage, moving on when one hits its 5-hour or weekly limit, adding a short command (alias), and repairing drifted account directories (skills, hooks, rules or settings not shared, wrong symlinks, credential file permissions). Drives the `sideby` CLI with `--json`; the agent does every step except browser sign-in, filling in secrets and starting interactive sessions, which it hands to the user as one command.
 metadata:
-  version: "0.6.0"
+  version: "0.8.0"
   requires:
     bins: [sideby, node]
   cliHelp: sideby --help
@@ -58,7 +58,9 @@ Read only the reference the task needs.
 
 When a terminal manager such as Orca reopens a pane with a bare `claude --resume <id>` (or `codex resume <id>`, `grok --resume <id>`) and the Host says `No conversation found`, the session lives in another account. Suggest config `"resumeRouting": true` followed by `sideby shell-init --write` (or a new shell with `eval`): `shell-init` then defines Host-named functions that call `sideby resume <family>`, which starts the account holding that session. For a one-off, find it with `ls -d ~/.claude*/projects/*/<id>.jsonl` and run `sideby run <ref> -- --resume <id>`. When no account has that file, the session was opened but never got a message, so there is nothing to resume: `ls -d ~/.claude*/session-env/<id>` names the account that started it, and with routing on `sideby resume` starts a new session there by itself.
 
-For someone who would rather double-click than use a terminal, `sideby app install` adds a desktop app (macOS `~/Applications/sideby.app`, Linux app menu) that runs `sideby ui --background`; `sideby ui --stop` stops it and `sideby app uninstall` removes the app. Ask before `app install`: it writes outside sideby's own directories.
+To open Claude Desktop or the Codex app as one account (macOS, subscription accounts), run `sideby desktop <ref> --json` yourself: it opens a new window for that account, or brings its open window to the front, and never closes anything. Relay its `notices`: the first Claude Desktop sign-in should happen while other Claude Desktop windows are closed, and a sign-in screen that suggests the main account ("Welcome back" in the Codex app) must not be used for another account.
+
+For someone who would rather double-click than use a terminal, `sideby app install` adds a panel app (macOS `~/Applications/sideby.app`, Linux app menu) that runs `sideby ui --background`; `sideby ui --stop` stops it and `sideby app uninstall` removes the app. Ask before `app install`: it writes outside sideby's own directories.
 
 ## Keeping this skill current
 

package/skills/sideby/references/handoff.md

@@ -15,7 +15,7 @@ Use this when the user says an account hit its 5-hour or weekly limit ("usage li
    | `full` | A live window is at 85% or more; `resetsAt` is when it is usable again | No |
    | `logged-out` | Needs `sideby login <ref>` | No |
 
-   Each entry's `observedAt` says when its quota was recorded. If `hasQuota` is `false`, no account has quota data: the pick is only a guess, so say so and suggest turning quota on (see the routing table in SKILL.md) or letting the user choose.
+   Each entry's `observedAt` says when its quota was recorded (`quotaFrom` when it was read from another account of the same login). An entry with `sameLoginAs` is signed in as the same login as the account you run in: it shares that quota and is never picked. If `hasQuota` is `false`, no account has quota data: the pick is only a guess, so say so and suggest turning quota on (see the routing table in SKILL.md) or letting the user choose.
 3. Give the user the command to run in their own terminal: `sideby next <family>` (starts the pick) or `sideby run <pick>`. Host arguments go after `--`. Do not run it yourself.
 4. Offer a handoff note: the new session starts empty, because each account keeps its own sessions. Write a short note the user can paste into it: the goal, what is done, what is in progress, the files involved, and the next step.
 

package/skills/sideby/references/quota.md

@@ -11,4 +11,6 @@ Accounts with their own (not linked) `settings.json` show quota `not-enabled` un
 
 After setup, each account shows quota once it has had one session with a reply. Codex quota needs no setup: sideby reads it from Codex's own session files.
 
+Two Claude accounts signed in as the same login (same email and organization; `sameLogin` in `sideby list --json`) share one quota: both show the freshest reading, and `quota.from` names the account it was read from. Explain that to the user rather than calling the numbers wrong; usage stays per account, and sideby never merges or deletes either directory.
+
 Usage (7-day tokens) is read by sideby itself from Claude Code and Codex local records; no ccusage is needed. Grok and pi have no quota or usage source.