sideby 0.16.0 → 0.17.0

package/dist/src/plugins/scaffold.js

@@ -0,0 +1,123 @@
+// `sideby plugins new` (spec §3.28 "加一个新宿主"): writes a Family Plugin skeleton the loader accepts as it is, with a
+// TODO on every fact the author has to look up in the Host's own docs.
+import { chmod, mkdir, writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { UserError } from '../core/errors.js';
+/** Same rule the loader applies to a Family id: it becomes part of account refs and shell function names. */
+export const FAMILY_ID_RE = /^[a-z][a-z0-9-]{0,31}$/;
+/** Marks each line of the skeleton the author still has to fill in; `checkPlugin` reports any that are left. */
+export const TODO_MARK = 'TODO(sideby)';
+/** Why `id` cannot name a Family Plugin, or null when it can. */
+export function pluginIdProblem(id) {
+    return FAMILY_ID_RE.test(id)
+        ? null
+        : `"${id}" cannot name a plugin: use lowercase letters, digits or "-", starting with a letter, at most 32 characters (for example "mytool")`;
+}
+/**
+ * Creates `<dir>/<id>/` with `plugin.json`, `index.ts` (an `api.family(def)` skeleton that only imports types from
+ * sideby) and `index.test.ts` (a starter on `sideby/testing`). The directory is mode 700 and the files 600, owned by
+ * the current user, so the loader's trust checks pass. Refuses a bad id or an existing directory before writing.
+ */
+export async function scaffoldPlugin(opts) {
+    const problem = pluginIdProblem(opts.id);
+    if (problem)
+        throw new UserError(problem, { code: 'plugin-id-invalid' });
+    await mkdir(opts.dir, { recursive: true, mode: 0o700 });
+    const dir = join(opts.dir, opts.id);
+    try {
+        await mkdir(dir, { mode: 0o700 });
+    }
+    catch (err) {
+        if (err.code === 'EEXIST')
+            throw new UserError(`${dir} already exists; pick another id, or check the plugin there with \`sideby plugins check ${opts.id}\``, { code: 'plugin-exists' });
+        throw err;
+    }
+    // mkdir's mode is narrowed by the umask; set it exactly.
+    await chmod(dir, 0o700);
+    const files = [];
+    for (const [name, text] of [
+        ['plugin.json', manifestText(opts.id)],
+        ['index.ts', indexText(opts.id)],
+        ['index.test.ts', testText(opts.id)],
+    ]) {
+        const p = join(dir, name);
+        await writeFile(p, text, { mode: 0o600, flag: 'wx' });
+        await chmod(p, 0o600);
+        files.push(p);
+    }
+    return { dir, files };
+}
+function manifestText(id) {
+    return `${JSON.stringify({ name: id, version: '0.1.0', description: `${id} family for sideby`, main: 'index.ts' }, null, 2)}\n`;
+}
+function envPrefix(id) {
+    return id.toUpperCase().replace(/-/g, '_');
+}
+function indexText(id) {
+    const v = envPrefix(id);
+    return `// Family Plugin for ${id}. This file runs with your full permissions, like any local code.
+// Fill in every ${TODO_MARK} with a fact from the Host's own docs or \`--help\`, and write down where it came from as
+// "<tool> <version>, <date>", for example "${id} 1.2.0 --help, 2026-10-17". Then run \`sideby plugins check ${id}\`.
+// Only \`import type\` from sideby: the plugin gets everything else through \`api\`.
+import type { FamilyDef, Plugin } from 'sideby'
+
+const family: FamilyDef = {
+  id: '${id}',
+  // ${TODO_MARK}: the Host's name as its docs write it.
+  title: '${id}',
+  // ${TODO_MARK}: the executable the Host installs on PATH (its docs or install script).
+  bin: '${id}',
+  // ${TODO_MARK}: the Host's official install page.
+  installUrl: 'https://example.com/${id}',
+  // ${TODO_MARK}: the environment variable that moves the Host's whole config directory (its docs or \`--help\`).
+  // sideby sets it for every Account but the Main Account.
+  selectVar: '${v}_HOME',
+  // ${TODO_MARK}: where the Host keeps its config, relative to HOME; the other Accounts put <name> in the first segment.
+  layout: { main: '.${id}', account: '.${id}-<name>' },
+  // ${TODO_MARK}: variables that would send every Account to the same login or endpoint (API keys, base URLs);
+  // sideby clears them before each launch.
+  hijackVars: ['${v}_API_KEY'],
+  // ${TODO_MARK}: variables an API Account sets in its proxy.env.
+  apiVars: ['${v}_API_KEY'],
+  // ${TODO_MARK}: each file or folder the Accounts share, with its Share Mode (see \`sideby families claude\` for examples).
+  // Paths are relative to the Account directory. Mark a file that holds a login \`credential: true\`; sideby never reads it.
+  sharedItems: [{ path: 'settings.json', mode: 'link-or-copy' }],
+  // ${TODO_MARK}: the Host's sign-in arguments, or null when it signs in inside the app.
+  login: { args: ['login'], hint: 'run ${id} login' },
+  // Optional: loginState(account) tells signed in from signed out by whether a file exists, never by reading it.
+  // Optional: logo, one 24x24 SVG path with its source and license in a comment.
+}
+
+const plugin: Plugin = {
+  name: '${id}',
+  register(api) {
+    api.family(family)
+  },
+}
+
+export default plugin
+`;
+}
+function testText(id) {
+    return `// Starter test for the ${id} Family Plugin. Run it with \`node --test index.test.ts\` where sideby is installed
+// (\`npm i -D sideby\`). It only uses a throwaway HOME from sideby/testing, never your real one.
+import assert from 'node:assert/strict'
+import { it } from 'node:test'
+import type { FamilyDef, PluginApi } from 'sideby'
+import { withFakeHome } from 'sideby/testing'
+import plugin from './index.ts'
+
+it('registers the ${id} family', async () => {
+  await withFakeHome(async (h) => {
+    const families: FamilyDef[] = []
+    await plugin.register({ family: (def: FamilyDef) => families.push(def) } as unknown as PluginApi)
+    assert.equal(families.length, 1)
+    const def = families[0]!
+    assert.equal(def.id, '${id}')
+    assert.ok(def.selectVar)
+    // ${TODO_MARK}: write the files your Host keeps in a signed-in Account and assert what loginState reads.
+    await h.mkdir(def.layout.main)
+  })
+})
+`;
+}

package/dist/src/quota/statusline-tap.js

@@ -91,7 +91,7 @@ export async function runStatuslineTap(argv, env, stdin, stdout, stderr = proces
             // Several sessions of one Account share this cache; an idle one must not put back older numbers.
             const stateDir = cacheStateDir(env);
             const prev = await readQuotaCache(stateDir, name).catch(() => null);
-            const merged = prev?.status === 'ok' ? mergeQuotaCache(prev.windows, cache) : cache;
+            const merged = mergeQuotaCache(prev?.status === 'ok' ? prev : null, cache);
             if (!merged) {
                 // Older numbers: write nothing, and show what the cache already knows.
                 if (prev?.status === 'ok')

package/dist/src/runtime.d.ts

@@ -203,6 +203,16 @@ export interface Runtime {
     /** Rewrites the configured `shellInitFile` of each shell (all configured ones by default). */
     writeShellInitFiles(shells?: readonly Shell[]): Promise<ShellInitWrite[]>;
     prepareLaunch(ref: string, userArgs: readonly string[], command: 'run' | 'login'): Promise<PreparedLaunch>;
+    /**
+     * The Host and arguments `prepareLaunch` starts from, without reading the Secret File or running `launch.before`
+     * hooks: what a preview may show before the user agrees to start anything.
+     */
+    launchCommand(ref: string, userArgs: readonly string[], command: 'run' | 'login'): Promise<{
+        account: Account;
+        family: FamilyDef;
+        bin: string;
+        args: string[];
+    }>;
     /**
      * Starts the non-main Account that holds the session the Host arguments resume, or else the Host unchanged
      * (spec §3.15). Throws UnknownFamilyError, or a UserError when the Family cannot route sessions.

package/dist/src/runtime.js

@@ -10,7 +10,7 @@ import { handoffFindings } from './core/handoff-doctor.js';
 import { selectNext } from './core/handoff-select.js';
 import { identityOf } from './core/identity.js';
 import { mergeDoctorHistory, readDoctorHistory, writeDoctorHistory, } from './core/last-doctor.js';
-import { accountEnv, brokenOnPath, prepareLaunch, which, } from './core/launch.js';
+import { accountEnv, brokenOnPath, launchCommand, prepareLaunch, which, } from './core/launch.js';
 import { memoStore } from './core/memo-store.js';
 import { resolvePaths } from './core/paths.js';
 import { fetchedQuota, quotaCheckOff, shownQuota } from './core/quota-fetch.js';
@@ -23,6 +23,7 @@ import { groupSuggestion, MAX_COMPACT_WINDOW, MIN_COMPACT_WINDOW, } from './core
 import { applyTune, planTuneApply, readTuneSettings, settingsFileOf, tuneUndoInfo, undoTune, } from './core/tuning-apply.js';
 import { packageVersion } from './core/version.js';
 import { BUILTIN_PLUGINS } from './families/index.js';
+import { LOGIN_KEY_READERS } from './families/login-keys.js';
 import { HookBus } from './plugins/bus.js';
 import { loadPlugins } from './plugins/loader.js';
 export class UnknownFamilyError extends UserError {
@@ -42,6 +43,21 @@ async function readIdentity(f, account) {
         return undefined;
     }
 }
+/**
+ * An Account's Login Key (ADR-0028), only for grouping a Same Login: it stays inside `groupsOf` and never reaches an
+ * output, an error, a log or a cache. Undefined for a Family without a reader, or on any problem.
+ */
+async function readLoginKey(account) {
+    const read = LOGIN_KEY_READERS.get(account.family);
+    if (!read || account.kind === 'api')
+        return undefined;
+    try {
+        return await read(account);
+    }
+    catch {
+        return undefined;
+    }
+}
 export async function createRuntime(opts = {}) {
     const env = opts.env ?? process.env;
     const paths = resolvePaths(env);
@@ -92,8 +108,17 @@ export async function createRuntime(opts = {}) {
         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 } : {}) };
+            const [identity, loginKey] = await Promise.all([
+                readIdentity(familyOf(a.family), a),
+                readLoginKey(a),
+            ]);
+            return {
+                ref: a.ref,
+                family: a.family,
+                kind: a.kind,
+                ...(identity ? { identity } : {}),
+                ...(loginKey ? { loginKey } : {}),
+            };
         }));
         return sameLoginGroups(members);
     };
@@ -198,6 +223,19 @@ export async function createRuntime(opts = {}) {
     const ownAlias = (name) => config.aliases && Object.hasOwn(config.aliases, name) ? config.aliases[name] : undefined;
     /** The config value of `ref` when it names an alias (no colon), as `resolveRef` reads it. */
     const aliasValue = (ref) => (ref.includes(':') ? undefined : ownAlias(ref));
+    /** What `prepareLaunch` and `launchCommand` both start from, so a preview cannot differ from the Launch. */
+    const launchInputs = (ref, all, userArgs, command) => {
+        const account = resolveRef(ref, all, aliasRefs(config.aliases));
+        return {
+            title: config.accountTitle === true,
+            account,
+            family: familyOf(account.family),
+            accountArgs: config.accounts?.[account.ref]?.args ?? [],
+            // An alias's arguments come before the user's; the Family sees both as the user's choice (ADR-0005).
+            userArgs: command === 'run' ? [...aliasArgs(aliasValue(ref)), ...userArgs] : userArgs,
+            command,
+        };
+    };
     const aliasEdit = async (alias, status, value) => {
         const args = aliasArgs(value);
         const files = await rt.writeShellInitFiles();
@@ -471,19 +509,12 @@ export async function createRuntime(opts = {}) {
         },
         async prepareLaunch(ref, userArgs, command) {
             const all = await accounts();
-            const account = resolveRef(ref, all, aliasRefs(config.aliases));
-            return prepareLaunch({
-                label: launchLabel(ref, account, all),
-                title: config.accountTitle === true,
-                account,
-                family: familyOf(account.family),
-                baseEnv: env,
-                accountArgs: config.accounts?.[account.ref]?.args ?? [],
-                // An alias's arguments come before the user's; the Family sees both as the user's choice (ADR-0005).
-                userArgs: command === 'run' ? [...aliasArgs(aliasValue(ref)), ...userArgs] : userArgs,
-                command,
-                bus,
-            });
+            const inputs = launchInputs(ref, all, userArgs, command);
+            return prepareLaunch({ ...inputs, label: launchLabel(ref, inputs.account, all), baseEnv: env, bus });
+        },
+        async launchCommand(ref, userArgs, command) {
+            const inputs = launchInputs(ref, await accounts(), userArgs, command);
+            return { account: inputs.account, family: inputs.family, ...launchCommand(inputs) };
         },
         async resumeLaunch(familyId, userArgs) {
             const family = familyOf(familyId);

package/dist/src/types.d.ts

@@ -61,6 +61,25 @@ export interface FamilyDef {
     hijackVars: string[];
     /** Variables written, commented out, into a new API Account's Secret File. */
     apiVars: string[];
+    /**
+     * Secret File variable `sideby key` writes when the user does not name one (spec §3.28).
+     * The API key, not a base URL or a model. Public contract, additive only.
+     */
+    secretVar?: string;
+    /**
+     * Arguments for one short non-interactive check of an Account (`sideby try`, spec §3.28).
+     * sideby runs `bin` with these arguments and no others. Public contract, additive only:
+     * leaving it out means this tool cannot be tried.
+     */
+    probe?: {
+        args: string[];
+    };
+    /**
+     * The Host option that attaches an image to the first prompt, such as Codex's `--image` (spec §3.28 "附件").
+     * An AI Task with attached images adds `<imageArg>=<path>` once per image before the prompt; Families without
+     * it read the images from the paths the prompt lists. Public contract, additive only.
+     */
+    imageArg?: string;
     sharedItems: SharedItemDef[];
     /** Arguments for the Host's sign-in command, or null when sign-in happens inside the Host. */
     login: {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sideby",
-  "version": "0.16.0",
+  "version": "0.17.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)",
@@ -80,5 +80,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## 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 quota setup claude --yes  # Claude quota in the panel; undo: sideby quota teardown claude\nsideby ui                        # every account's quota at http://127.0.0.1:17420\n```\n\n`sideby update` installs a newer sideby when there is one; sideby says so after a command and in the panel. `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\nThe 25-second story: one account buried in tasks, then accounts side by side sharing one setup, and a task moving on when one runs out.\n\nhttps://github.com/user-attachments/assets/3a470c03-9009-4f1d-b7f6-8b4625d74958\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## 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## 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| Choose whether Claude sessions connect to claude.ai by themselves (Remote Control), for every account at once | `sideby remote-control off` or `on` (or the panel's Settings) | [Remote Control](docs/guide/usage.md#remote-control) |\n| Pin the accounts you use most and put tools and accounts in your own order | `sideby pin claude:work`, `sideby order` (or the panel's Settings) | [Your own order](docs/guide/usage.md#your-own-order) |\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| Keep several Grok Bot windows open, each signed in to its own account (macOS) | `sideby desktop grok-bot:002` (or the panel) | [Grok Bot windows](docs/guide/usage.md#grok-bot-windows) |\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` | weekly, asked from the `grok` CLI | 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 about your accounts leaves your machine: the only request sideby makes on its own is a daily check of the npm registry for its newest version (off with `NO_UPDATE_NOTIFIER=1`; see [Updates](docs/guide/configuration.md#updates)).\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"
+  "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## 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 quota setup claude --yes  # Claude quota in the panel; undo: sideby quota teardown claude\nsideby ui --background           # every account's quota at http://127.0.0.1:17420, still there after you close the terminal\n```\n\n`sideby app install` adds a Dock icon that opens the panel, and `sideby autostart on` has it ready each time you log in. `sideby update` installs a newer sideby when there is one; sideby says so after a command and in the panel. `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\nThe 25-second story: one account buried in tasks, then accounts side by side sharing one setup, and a task moving on when one runs out.\n\nhttps://github.com/user-attachments/assets/fd6138ae-499d-4055-b94f-25ef9ce74035\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## 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## What else it does\n\n| You want to | Run | Guide |\n|---|---|---|\n| Hand a task to your own AI from the panel: set up an account, fix a problem, support a new tool | **Let AI do it** in the panel, or `sideby ask` | [Let AI do it](docs/guide/panel.md#let-ai-do-it) |\n| Have the panel ready in the background whenever you log in | **Settings › Startup** in the panel, or `sideby autostart on` | [Start at login](docs/guide/usage.md#start-at-login) |\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| Choose whether Claude sessions connect to claude.ai by themselves (Remote Control), for every account at once | `sideby remote-control off` or `on` (or the panel's Settings) | [Remote Control](docs/guide/usage.md#remote-control) |\n| Pin the accounts you use most and put tools and accounts in your own order | `sideby pin claude:work`, `sideby order` (or the panel's Settings) | [Your own order](docs/guide/usage.md#your-own-order) |\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| Keep several Grok Bot windows open, each signed in to its own account (macOS) | `sideby desktop grok-bot:002` (or the panel) | [Grok Bot windows](docs/guide/usage.md#grok-bot-windows) |\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` | weekly, asked from the `grok` CLI | 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 about your accounts leaves your machine: the only request sideby makes on its own is a daily check of the npm registry for its newest version (off with `NO_UPDATE_NOTIFIER=1`; see [Updates](docs/guide/configuration.md#updates)).\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/ask.json

@@ -0,0 +1,180 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "sideby/ask.json",
+  "type": "object",
+  "required": [
+    "schemaVersion",
+    "task",
+    "account",
+    "terminal",
+    "opened",
+    "command",
+    "removedSecrets",
+    "attachments"
+  ],
+  "properties": {
+    "schemaVersion": {
+      "type": "number",
+      "const": 1
+    },
+    "task": {
+      "anyOf": [
+        {
+          "type": "string"
+        },
+        {
+          "type": "null"
+        }
+      ]
+    },
+    "account": {
+      "anyOf": [
+        {
+          "type": "string"
+        },
+        {
+          "type": "null"
+        }
+      ]
+    },
+    "terminal": {
+      "anyOf": [
+        {
+          "type": "string"
+        },
+        {
+          "type": "null"
+        }
+      ]
+    },
+    "opened": {
+      "type": "boolean"
+    },
+    "command": {
+      "anyOf": [
+        {
+          "type": "string"
+        },
+        {
+          "type": "null"
+        }
+      ]
+    },
+    "removedSecrets": {
+      "type": "boolean"
+    },
+    "reason": {
+      "type": "string",
+      "enum": [
+        "no-accounts",
+        "none-signed-in",
+        "all-full",
+        "not-installed",
+        "automation-denied",
+        "npx-cache",
+        "unsafe-path",
+        "failed",
+        "unsupported-platform"
+      ],
+      "description": "Why nothing opened (only when `opened` is false); `detail` says what to do next."
+    },
+    "detail": {
+      "type": "string",
+      "description": "What to do next, for a person."
+    },
+    "prompt": {
+      "type": "string"
+    },
+    "attachments": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": [
+          "path",
+          "kind",
+          "bytes"
+        ],
+        "properties": {
+          "path": {
+            "type": "string",
+            "description": "Absolute path of the copy saved for the task."
+          },
+          "kind": {
+            "type": "string",
+            "enum": [
+              "image",
+              "video"
+            ]
+          },
+          "bytes": {
+            "type": "integer",
+            "minimum": 0
+          }
+        }
+      },
+      "description": "Files given with `--attach`, in order; empty without any."
+    },
+    "_notice": {
+      "type": "object",
+      "properties": {
+        "update": {
+          "type": "object",
+          "required": [
+            "current",
+            "latest",
+            "command",
+            "message"
+          ],
+          "properties": {
+            "current": {
+              "type": "string"
+            },
+            "latest": {
+              "type": "string"
+            },
+            "command": {
+              "type": "string",
+              "description": "Run it after the user agrees: it shows the plan and exits 10; then --yes."
+            },
+            "message": {
+              "type": "string"
+            }
+          }
+        },
+        "skill": {
+          "type": "object",
+          "required": [
+            "installed",
+            "current",
+            "command",
+            "message"
+          ],
+          "properties": {
+            "installed": {
+              "anyOf": [
+                {
+                  "type": "string"
+                },
+                {
+                  "type": "null"
+                }
+              ],
+              "description": "The skill's version; null when it has none."
+            },
+            "current": {
+              "type": "string"
+            },
+            "command": {
+              "type": "string",
+              "description": "`sideby update`, which updates the skill with sideby: run it after the user agrees; it shows the plan and exits 10, then --yes."
+            },
+            "message": {
+              "type": "string"
+            }
+          }
+        }
+      },
+      "description": "Not the answer to the task: mention it briefly afterwards and offer to update."
+    }
+  }
+}