sideby 0.6.0 → 0.7.0

package/dist/src/core/doctor.d.ts

@@ -1,5 +1,5 @@
 import type { HookBus } from '../plugins/bus.ts';
-import type { Account, FamilyDef, Finding } from '../types.ts';
+import type { Account, CheckResult, FamilyDef, Finding } from '../types.ts';
 export interface AccountReport {
     ref: string;
     family: string;
@@ -35,6 +35,11 @@ export interface DoctorInput {
     force?: boolean;
     /** This sideby's version: when set, installed sideby skills of the checked Families are compared with it. */
     skillVersion?: string;
+    /**
+     * More core checks for an Account that is not the Main Account, merged after its Shared Items. They are not
+     * counted in `shared`; a result's `fix` runs with the others under `--fix` and must stay within what it checked.
+     */
+    extraChecks?: (account: Account) => Promise<CheckResult[]>;
 }
 export declare function runDoctor(input: DoctorInput): Promise<DoctorReport>;
 /** Applies every fixable Finding once, in order; one failing fix never stops the others. */

package/dist/src/core/doctor.js

@@ -43,6 +43,25 @@ async function checkAccount(input, family, account) {
                 if (r.level !== 'ok')
                     findings.push(toFinding(r, account.ref, 'core'));
         }
+        // Extra checks (for example a Desktop App's data folder) add Findings but never count toward `shared`.
+        // A failing extra check costs only its own Findings, never the whole run.
+        try {
+            for (const r of (await input.extraChecks?.(account)) ?? [])
+                if (r.level !== 'ok')
+                    findings.push(toFinding(r, account.ref, 'core'));
+        }
+        catch (e) {
+            findings.push({
+                level: 'warn',
+                account: account.ref,
+                item: 'extra',
+                code: 'extra-check.error',
+                message: `could not finish an extra check of ${account.ref}: ${e instanceof Error ? e.message : String(e)}`,
+                hint: 'run sideby doctor again; if it keeps failing, check that the folder it names is readable',
+                fixable: false,
+                source: 'core',
+            });
+        }
         if (looksLikeBackup(account.name))
             findings.push({
                 level: 'warn',

package/dist/src/core/tuning-apply.js

@@ -32,7 +32,7 @@ function render(obj, original) {
 }
 async function readObject(file) {
     const st = await stat(file).catch(() => null);
-    if (!st || !st.isFile())
+    if (!st?.isFile())
         return { error: 'it is not a regular file' };
     if (st.size > MAX_BYTES)
         return { error: 'it is too large to be a settings file' };

package/dist/src/families/claude/desktop.d.ts

@@ -0,0 +1,6 @@
+import type { DesktopAppDef } from '../desktop.ts';
+/**
+ * Claude Desktop (spec §3.20). Its Code tab honours CLAUDE_CONFIG_DIR; the data folder moves only with
+ * `--user-data-dir` (signed builds ignore CLAUDE_USER_DATA_DIR).
+ */
+export declare const claudeDesktop: DesktopAppDef;

package/dist/src/families/claude/desktop.js

@@ -0,0 +1,28 @@
+/**
+ * Claude Desktop (spec §3.20). Its Code tab honours CLAUDE_CONFIG_DIR; the data folder moves only with
+ * `--user-data-dir` (signed builds ignore CLAUDE_USER_DATA_DIR).
+ */
+export const claudeDesktop = {
+    family: 'claude',
+    title: 'Claude Desktop',
+    bundleId: 'com.anthropic.claudefordesktop',
+    bundleNames: ['Claude.app'],
+    installUrl: 'https://claude.ai/download',
+    openArgs: (app, dir, appData) => [
+        '-n',
+        '-a',
+        app,
+        '--env',
+        `CLAUDE_CONFIG_DIR=${dir}`,
+        '--args',
+        `--user-data-dir=${appData}`,
+    ],
+    clearVars: ['CLAUDE_USER_DATA_DIR'],
+    signInInApp: true,
+    sharedFiles: [
+        {
+            path: 'claude_desktop_config.json',
+            mainPath: 'Library/Application Support/Claude/claude_desktop_config.json',
+        },
+    ],
+};

package/dist/src/families/codex/desktop.d.ts

@@ -0,0 +1,7 @@
+import type { DesktopAppDef } from '../desktop.ts';
+/**
+ * The Codex app (`ChatGPT.app`, spec §3.20). It shares the Account's terminal sign-in through CODEX_HOME. Its own
+ * code replaces the path `--user-data-dir` sets, so CODEX_ELECTRON_USER_DATA_PATH goes along (the app's "Codex Demo"
+ * recipe); both are internal to the app and may change.
+ */
+export declare const codexDesktop: DesktopAppDef;

package/dist/src/families/codex/desktop.js

@@ -0,0 +1,25 @@
+/**
+ * The Codex app (`ChatGPT.app`, spec §3.20). It shares the Account's terminal sign-in through CODEX_HOME. Its own
+ * code replaces the path `--user-data-dir` sets, so CODEX_ELECTRON_USER_DATA_PATH goes along (the app's "Codex Demo"
+ * recipe); both are internal to the app and may change.
+ */
+export const codexDesktop = {
+    family: 'codex',
+    title: 'Codex app',
+    bundleId: 'com.openai.codex',
+    bundleNames: ['ChatGPT.app', 'Codex.app'],
+    installUrl: 'https://openai.com/codex/',
+    openArgs: (app, dir, appData) => [
+        '-n',
+        '--env',
+        `CODEX_HOME=${dir}`,
+        '--env',
+        `CODEX_ELECTRON_USER_DATA_PATH=${appData}`,
+        app,
+        '--args',
+        `--user-data-dir=${appData}`,
+    ],
+    clearVars: ['CODEX_ELECTRON_USER_DATA_PATH'],
+    signInInApp: false,
+    sharedFiles: [],
+};

package/dist/src/families/desktop.d.ts

@@ -0,0 +1,27 @@
+export interface DesktopAppDef {
+    /** The Family id. */
+    family: string;
+    /** How messages name the app, for example `Claude Desktop`. */
+    title: string;
+    /** `CFBundleIdentifier` in the app's Info.plist. */
+    bundleId: string;
+    /** Bundle names to look for first in /Applications and ~/Applications. */
+    bundleNames: readonly string[];
+    installUrl: string;
+    /**
+     * `open` arguments for a non-main Account: a new instance (`-n`) with the Account's selecting variable and
+     * App Data. `app` is the bundle path, `dir` the Account directory.
+     */
+    openArgs(app: string, dir: string, appData: string): string[];
+    /** Inherited variables cleared before `open`, besides the Family's Hijack Variables and selecting variable. */
+    clearVars: readonly string[];
+    /** The first sign-in happens inside the app, through a URL callback another running instance may catch. */
+    signInInApp: boolean;
+    /** Files of the App Data shared from the Main Account's default App Data as links (`mainPath` relative to HOME). */
+    sharedFiles: readonly {
+        path: string;
+        mainPath: string;
+    }[];
+}
+/** The Desktop App of a built-in Family id, if it has one. */
+export declare function desktopDef(familyId: string): DesktopAppDef | undefined;

package/dist/src/families/desktop.js

@@ -0,0 +1,9 @@
+// Desktop Apps of the built-in Families (spec §3.20, ADR-0015). Internal on purpose: not part of the public
+// FamilyDef, so plugin Families cannot declare one in v1.
+import { claudeDesktop } from './claude/desktop.js';
+import { codexDesktop } from './codex/desktop.js';
+const DESKTOP_APPS = new Map([claudeDesktop, codexDesktop].map((d) => [d.family, d]));
+/** The Desktop App of a built-in Family id, if it has one. */
+export function desktopDef(familyId) {
+    return DESKTOP_APPS.get(familyId);
+}

package/dist/src/panel/handler.js

@@ -2,6 +2,7 @@
 import { randomBytes, timingSafeEqual } from 'node:crypto';
 import { aliasesByAccount } from '../core/accounts.js';
 import { aliasArgs, aliasRefs } from '../core/config.js';
+import { openDesktopApp, withDesktopApps } from '../core/desktop-app.js';
 import { UserError } from '../core/errors.js';
 import { planHandoff } from '../core/handoff.js';
 import { applyHandoffEnable, planHandoffEnable } from '../core/handoff-enable.js';
@@ -203,10 +204,11 @@ async function buildState(rt, opts) {
     ]);
     const health = healthByAccount(history);
     const aliases = aliasesByAccount(aliasRefs(rt.config.aliases), accounts);
-    const list = await Promise.all(accounts.map(async (a) => {
-        const st = await accountState(rt, a, families);
-        const h = health.get(a.ref);
-        const names = aliases.get(a.ref);
+    // Desktop Apps (spec §3.20): one process listing for every Account, run alongside the per-Account reads.
+    const states = await withDesktopApps(rt, accounts, Promise.all(accounts.map((a) => accountState(rt, a, families))));
+    const list = states.map((st) => {
+        const h = health.get(st.ref);
+        const names = aliases.get(st.ref);
         const withArgs = (names ?? [])
             .map((n) => [n, aliasArgs(rt.config.aliases?.[n])])
             .filter(([, args]) => args.length);
@@ -216,7 +218,7 @@ async function buildState(rt, opts) {
             ...(names ? { aliases: names } : {}),
             ...(withArgs.length ? { aliasArgs: Object.fromEntries(withArgs) } : {}),
         };
-    }));
+    });
     const handoff = handoffByFamily(rt, list, ctx.now);
     return {
         schemaVersion: 1,
@@ -434,6 +436,23 @@ export function createPanelHandler(opts) {
                 return { ref: found.ref, ...r, file: tildify(r.file, rt.paths.home) };
             },
         },
+        // Opens the Account's Desktop App, or brings its window to the front (spec §3.20). It creates the Account's
+        // app data folder and starts a program, so a read-only Panel refuses it (writes defaults to true).
+        '/api/account/desktop': {
+            async run(body) {
+                const account = optString(body, 'account');
+                if (!account)
+                    throw new HttpError(400, '"account" is required');
+                const rt = await getRuntime();
+                const r = await openDesktopApp(rt, account);
+                const home = rt.paths.home;
+                return {
+                    ...r,
+                    appPath: tildify(r.appPath, home),
+                    ...(r.appData ? { appData: tildify(r.appData, home) } : {}),
+                };
+            },
+        },
         // The Auto Handoff page (spec §3.17): where work would go next and the last hand-overs. Reads only.
         '/api/handoff/overview': {
             writes: () => false,

package/dist/src/panel/i18n.d.ts

@@ -234,6 +234,14 @@ declare const en: {
     'menu.like': string;
     'menu.tune': string;
     'menu.model': string;
+    'desk.open': string;
+    'desk.show': string;
+    'desk.opening': string;
+    'desk.openHint': string;
+    'desk.showHint': string;
+    'desk.started': string;
+    'desk.focused': string;
+    'desk.failed': string;
     'md.title': string;
     'md.intro': string;
     'md.model': string;

package/dist/src/panel/i18n.js

@@ -236,6 +236,14 @@ const en = {
     'menu.like': 'New account like this',
     'menu.tune': 'Context tuning',
     'menu.model': 'Model and effort…',
+    'desk.open': 'Open desktop app',
+    'desk.show': 'Desktop app open',
+    'desk.opening': 'Opening {app}…',
+    'desk.openHint': 'Open {app} as {ref}, in its own window next to your other accounts',
+    'desk.showHint': '{app} is open as {ref}; click to bring it to the front',
+    'desk.started': 'Opened {app} as {ref}.',
+    'desk.focused': '{app} for {ref} is in front.',
+    'desk.failed': 'Could not open the desktop app for {ref}: {msg}',
     'md.title': 'Model and effort',
     'md.intro': 'Applies to new sessions of {ref} that you start with sideby (a short command or sideby run). It is saved in sideby’s config; {host}’s own settings stay as they are.',
     'md.model': 'Model',
@@ -685,6 +693,14 @@ const zh = {
     'menu.like': '照此新建账号',
     'menu.tune': '上下文调优',
     'menu.model': '模型和 effort…',
+    'desk.open': '打开桌面应用',
+    'desk.show': '桌面应用已打开',
+    'desk.opening': '正在打开 {app}…',
+    'desk.openHint': '以 {ref} 打开 {app}，和其他账号的窗口同时开着',
+    'desk.showHint': '{app} 已经以 {ref} 打开，点一下切到前台',
+    'desk.started': '已以 {ref} 打开 {app}。',
+    'desk.focused': '{ref} 的 {app} 已切到前台。',
+    'desk.failed': '没能打开 {ref} 的桌面应用：{msg}',
     'md.title': '模型和 effort',
     'md.intro': '只影响之后用 sideby 启动的 {ref} 新会话（短命令或 sideby run）。保存在 sideby 的配置里，不改 {host} 自己的设置。',
     'md.model': '模型',

package/dist/src/panel/page-logic.js

@@ -257,8 +257,8 @@ export function suggestName(names) {
     if (!taken.work)
         return 'work';
     for (let i = 2;; i++)
-        if (!taken['work' + i])
-            return 'work' + i;
+        if (!taken[`work${i}`])
+            return `work${i}`;
 }
 /**
  * A Finding's hint as the Panel shows it: for a fixable Finding, "run `sideby doctor --fix`" becomes the

package/dist/src/panel/page-script.js

@@ -53,7 +53,7 @@ const MAIN = String.raw `
     silent: false, lastTry: 0, pending: false, fastUntil: 0, fastFamily: null,
   }
   // View state that is not saved: the search text, the attention filter, the Health check filter.
-  const ui = { query: '', attention: false, allFindings: false, healthRef: null, checkingRef: null, highlight: null, fade: true }
+  const ui = { query: '', attention: false, allFindings: false, healthRef: null, checkingRef: null, desktopRef: null, highlight: null, fade: true }
   const $ = (id) => document.getElementById(id)
 
   // ---------- preferences ----------
@@ -573,6 +573,7 @@ const MAIN = String.raw `
     const items = [
       { icon: 'terminal', label: t('menu.copyRun'), hint: run, run: () => copyText(run) },
       ...(a.aliases || []).slice(0, 2).map((x) => ({ icon: 'terminal', label: t('menu.copyAlias'), hint: x, run: () => copyText(x) })),
+      a.desktopApp && a.desktopApp.installed && a.kind !== 'api' && !BOOT.readOnly ? { icon: 'terminal', label: t(a.desktopApp.running ? 'desk.show' : 'desk.open', { app: a.desktopApp.app }), disabled: Boolean(ui.desktopRef), run: () => openDesktop(a) } : null,
       a.kind !== 'api' ? { icon: 'key', label: t('menu.copyLogin'), hint: 'sideby login ' + a.ref, run: () => copyText('sideby login ' + a.ref) } : null,
       a.dir ? { icon: 'folder', label: t('menu.copyDir'), hint: a.dir, run: () => copyText(a.dir) } : null,
       a.identity && a.identity.email ? { icon: 'mail', label: t('menu.copyEmail'), hint: emailText(a.identity.email), run: () => copyText(a.identity.email) } : null,
@@ -906,8 +907,34 @@ const MAIN = String.raw `
       a.kind === 'api' && a.model ? h('span', { class: 'mono', title: t('acct.model') }, a.model) : null,
       a.kind !== 'api' ? modelChip(a) : null,
       a.kind !== 'api' && plan ? h('span', { class: 'plan' }, plan) : null,
+      desktopButton(a),
     ]))
   }
+  // The family's desktop app as this account (spec §3.20): only where it is installed, never for API accounts or a
+  // read-only panel. A running window shows as "open"; the click brings it to the front instead of a second one.
+  function desktopButton(a) {
+    const d = a.desktopApp
+    if (!d || !d.installed || a.kind === 'api' || BOOT.readOnly) return null
+    const busy = ui.desktopRef === a.ref
+    const label = busy ? t('desk.opening', { app: d.app }) : t(d.running ? 'desk.show' : 'desk.open', { app: d.app })
+    return h('button', { class: 'tag tag-btn' + (d.running ? ' tag-ok' : ''), type: 'button', disabled: busy, title: t(d.running ? 'desk.showHint' : 'desk.openHint', { app: d.app, ref: a.ref }), 'aria-label': label + ' (' + a.ref + ')', onclick: (e) => { e.stopPropagation(); openDesktop(a) } },
+      d.running ? h('span', { class: 'dot dot-ok', 'aria-hidden': 'true' }) : null, label)
+  }
+  async function openDesktop(a) {
+    if (ui.desktopRef) return
+    ui.desktopRef = a.ref
+    renderAccounts()
+    try {
+      const r = await api('/api/account/desktop', { account: a.ref })
+      const text = r.action === 'started' ? t('desk.started', { app: r.app, ref: r.ref }) : r.action === 'focused' ? t('desk.focused', { app: r.app, ref: r.ref }) : ''
+      if (text) toast(text)
+      // Notices say what to do next (sign in, close other windows while signing in); they stay a little longer.
+      for (const n of r.notices || []) toast(n, { kind: 'info', duration: 12000 })
+    } catch (e) { toast(t('desk.failed', { ref: a.ref, msg: e.message }), { kind: 'fail' }) }
+    ui.desktopRef = null
+    renderAccounts()
+    load({ silent: true })
+  }
   function notes(a) {
     const fam = family(a.family)
     const out = []
@@ -920,7 +947,7 @@ const MAIN = String.raw `
   }
   // What a row or card shows depends on more than the account (health, view preferences, language); the
   // fingerprint covers what its click handlers use.
-  function rowSig(a) { return sig([a, healthOf(a.ref), isNext(a)]) }
+  function rowSig(a) { return sig([a, healthOf(a.ref), isNext(a), ui.desktopRef === a.ref]) }
   // The Account 'sideby next <family>' would pick; the server ranks it with the CLI's rule (spec §3.13).
   function isNext(a) { return Boolean(S.state && S.state.handoff && S.state.handoff[a.family] === a.ref) }
   function row(a, now, cols) {

package/dist/src/runtime.d.ts

@@ -1,6 +1,7 @@
 import { type AccountRefError } from './core/accounts.ts';
 import { type Config, type HandoffSettings } from './core/config.ts';
 import { type CreateResult } from './core/create.ts';
+import { type DesktopDeps } from './core/desktop-app.ts';
 import { type DoctorReport } from './core/doctor.ts';
 import { UserError } from './core/errors.ts';
 import { type HandoffPlan } from './core/handoff.ts';
@@ -104,6 +105,15 @@ export interface AccountStatus extends Account {
     identity?: AccountIdentity;
     /** Plugin errors met while reading this Account (for example an unreadable settings file). */
     problems?: string[];
+    /**
+     * The Family's Desktop App for this Account (spec §3.20): macOS only, Subscription Accounts of claude and codex.
+     * Filled by `sideby list` and the Panel, which list processes once for all Accounts; `status()` leaves it out.
+     */
+    desktopApp?: {
+        app: string;
+        installed: boolean;
+        running: boolean;
+    };
 }
 export interface DoctorOptions {
     /** Family id or Account ref; all Accounts when omitted. */
@@ -232,4 +242,10 @@ export declare function createRuntime(opts?: {
     env?: Env;
     builtins?: BuiltinPlugin[];
     now?: () => Date;
+    /**
+     * Internal, for tests: replaces the machine the Desktop App calls use (platform, app folders and the programs
+     * `open`, `ps`, `osascript`, `plutil`, `mdfind`; spec §3.20). Omitted, the real machine is used. Not part of
+     * the plugin or Portal contract; it may change without notice.
+     */
+    desktop?: Partial<DesktopDeps>;
 }): Promise<Runtime>;

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';
@@ -254,6 +255,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();
@@ -606,5 +609,7 @@ export async function createRuntime(opts = {}) {
         },
         readContext,
     };
+    if (opts.desktop)
+        bindDesktopDeps(rt, opts.desktop);
     return rt;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sideby",
-  "version": "0.6.0",
+  "version": "0.7.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

@@ -152,6 +152,26 @@
                 "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/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.7.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