sideby 0.5.0 → 0.7.0

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,10 +573,12 @@ 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,
       '-',
+      a.modelInfo && a.modelInfo.settable ? { icon: 'terminal', label: t('menu.model'), run: () => openModel(a) } : null,
       family(a.family).tuning ? { icon: 'check', label: t('menu.tune'), run: () => openTune(a) } : null,
       { icon: 'check', label: t('menu.check'), disabled: S.checking || S.fixing || Boolean(ui.checkingRef), run: () => checkAccount(a.ref) },
       BOOT.readOnly ? null : { icon: 'userPlus', label: t('menu.like'), run: () => openCreate({ family: a.family, api: a.kind === 'api' }) },
@@ -903,9 +905,36 @@ const MAIN = String.raw `
     return h('div', { class: 'ident-sub' }, dots([
       h('span', { class: 'mono' }, a.ref),
       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 = []
@@ -918,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) {
@@ -1979,6 +2008,117 @@ const MAIN = String.raw `
     if (ah.loading) loadHandoffStatus()
   }
 
+  // ---------- model and effort (spec §3.19) ----------
+  // Shown under the account name; the dialog changes what sideby starts this account with, never the Host's files.
+  let md = null
+  function modelFrom(a, from) { return t('md.from.' + from, { host: family(a.family).title }) }
+  function modelChip(a) {
+    const mi = a.modelInfo
+    if (!mi || (!mi.model && !mi.effort)) return null
+    const text = [mi.model && mi.model.value, mi.effort && mi.effort.value].filter(Boolean).join(' · ')
+    const title = [
+      mi.model ? t('md.model') + ': ' + mi.model.value + ' (' + modelFrom(a, mi.model.from) + ')' : null,
+      mi.effort ? t('md.effort') + ': ' + mi.effort.value + ' (' + modelFrom(a, mi.effort.from) + ')' : null,
+      mi.settable ? t('md.click') : null,
+    ].filter(Boolean).join('\n')
+    if (!mi.settable) return h('span', { class: 'mono', title }, text)
+    return h('button', { class: 'mono model-btn' + (mi.model && mi.model.from === 'sideby' ? ' model-set' : ''), type: 'button', title, 'aria-label': t('menu.model') + ' ' + a.ref + ': ' + text, onclick: (e) => { e.stopPropagation(); openModel(a) } }, text)
+  }
+  function mdAccount() { return S.state && S.state.accounts.find((x) => x.ref === md.ref) }
+  function openModel(a) {
+    md = { ref: a.ref, family: a.family, preview: null, busy: false, error: null, form: null }
+    showDialog('model')
+    renderModel()
+  }
+  // The inputs are built once per opening, so typing keeps focus; everything else re-renders around them.
+  function mdForm(a) {
+    if (md.form) return md.form
+    const mi = a.modelInfo
+    const host = family(a.family).title
+    const list = h('datalist', { id: 'md-models' }, mi.models.map((m) => h('option', { value: m })))
+    const model = h('input', { type: 'text', list: 'md-models', autocomplete: 'off', spellcheck: 'false', placeholder: t('md.default') + ' (' + t('md.decides', { host }) + ')', disabled: BOOT.readOnly })
+    model.value = mi.sideby.model || ''
+    const effort = h('select', { disabled: BOOT.readOnly }, h('option', { value: '' }, t('md.default') + ' (' + t('md.decides', { host }) + ')'), mi.efforts.map((e) => h('option', { value: e }, e)))
+    effort.value = mi.sideby.effort || ''
+    const changed = () => { md.preview = null; md.error = null; renderModel() }
+    model.addEventListener('input', () => { if (md.preview) changed() })
+    effort.addEventListener('change', changed)
+    md.form = { model, effort, list }
+    return md.form
+  }
+  function mdChange(a, reset) {
+    const mi = a.modelInfo
+    if (reset) return { model: mi.sideby.model ? null : undefined, effort: mi.sideby.effort ? null : undefined }
+    const f = md.form
+    const m = f.model.value.trim()
+    const ch = {}
+    if (m !== (mi.sideby.model || '')) ch.model = m || null
+    if (f.effort.value !== (mi.sideby.effort || '')) ch.effort = f.effort.value || null
+    return ch
+  }
+  async function mdReview(reset) {
+    const a = mdAccount()
+    if (!a) return
+    const change = mdChange(a, reset)
+    for (const k of Object.keys(change)) if (change[k] === undefined) delete change[k]
+    md.error = null
+    if (!Object.keys(change).length) { md.preview = { nothing: true }; renderModel(); return }
+    md.busy = true
+    renderModel()
+    try {
+      const r = await api('/api/account/model', Object.assign({ account: a.ref }, change))
+      md.preview = r.changed ? { change, diff: r.diff } : { nothing: true }
+    } catch (e) { md.error = e }
+    md.busy = false
+    renderModel()
+  }
+  async function mdApply() {
+    const a = mdAccount()
+    if (!a || !md.preview || !md.preview.change) return
+    md.busy = true
+    dlg.busy = true
+    renderModel()
+    try {
+      await api('/api/account/model', Object.assign({ account: a.ref, confirm: true }, md.preview.change))
+      dlg.busy = false
+      toast(t('md.saved', { ref: a.ref }))
+      dlg.el.close()
+      await load({ silent: true })
+      return
+    } catch (e) { md.error = e }
+    md.busy = false
+    dlg.busy = false
+    renderModel()
+  }
+  function renderModel() {
+    if (!md || dlg.kind !== 'model') return
+    const a = mdAccount()
+    if (!a || !a.modelInfo) { dlg.el.close(); return }
+    const mi = a.modelInfo
+    const host = family(a.family).title
+    const f = mdForm(a)
+    const now = (key) => mi[key] ? h('span', null, h('b', { class: 'mono' }, mi[key].value), ' ', h('span', { class: 'muted small' }, '(' + modelFrom(a, mi[key].from) + ')')) : h('span', { class: 'muted' }, t('md.none'))
+    const body = [h('p', { class: 'muted small' }, t('md.intro', { ref: a.ref, host }))]
+    if (BOOT.readOnly) body.push(h('p', { class: 'note' }, t('banner.readOnly')))
+    body.push(h('div', { class: 'md-now' },
+      h('div', null, h('span', { class: 'muted' }, t('md.model') + ': '), now('model')),
+      h('div', null, h('span', { class: 'muted' }, t('md.effort') + ': '), now('effort'))))
+    body.push(h('div', { class: 'ah-grid' },
+      h('label', { class: 'field' }, h('span', null, t('md.model')), f.model, f.list),
+      h('label', { class: 'field' }, h('span', null, t('md.effort')), f.effort)))
+    if (a.family === 'claude') body.push(h('p', { class: 'muted small' }, t('md.envNote')))
+    if (md.error) body.push(errorNote(md.error, null))
+    if (md.preview && md.preview.nothing) body.push(h('p', { class: 'muted small' }, t('md.nothing')))
+    if (md.preview && md.preview.diff) body.push(h('p', { class: 'small' }, t('md.changes')), diffView(md.preview.diff))
+    const foot = [h('button', { class: 'btn', type: 'button', disabled: md.busy, onclick: () => dlg.el.close() }, t('btn.close'))]
+    if (!BOOT.readOnly) {
+      if (mi.sideby.model || mi.sideby.effort) foot.push(h('button', { class: 'btn', type: 'button', disabled: md.busy, onclick: () => mdReview(true) }, t('md.reset')))
+      if (md.preview && md.preview.change) foot.push(h('button', { class: 'btn btn-primary', type: 'button', disabled: md.busy, 'aria-busy': md.busy ? 'true' : null, onclick: mdApply }, md.busy ? spinner() : null, t('md.apply')))
+      else foot.push(h('button', { class: 'btn btn-primary', type: 'button', disabled: md.busy, onclick: () => mdReview(false) }, md.busy ? spinner() : null, t('md.review')))
+    }
+    setKids(dlg.el, dialogFrame(t('md.title') + ' · ' + a.ref, a.family, body, foot))
+  }
+
   // ---------- the Auto Handoff page ----------
   // Off: one sentence and one button. On: where each account's work would go next, the last hand-overs and what is
   // still missing. Turning on is one plan shown first (hp.preview) and one confirmation; no commands to copy.
@@ -2274,6 +2414,7 @@ const MAIN = String.raw `
     if (dlg.kind === 'create' && nf && !nf.creating) renderCreate()
     else if (dlg.kind === 'setup' && qs) renderSetup()
     else if (dlg.kind === 'tune' && tuneState) renderTune()
+    else if (dlg.kind === 'model' && md) { md.form = null; renderModel() }
   })
   $('theme').addEventListener('click', () => {
     const order = CHOICES.theme

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

@@ -167,7 +167,11 @@ code, .mono { font-family: var(--mono); font-size: 0.92em; }
 .ident-name { display: flex; align-items: center; gap: 6px; min-width: 0; flex-wrap: wrap; row-gap: 3px; }
 .ident-name .name { font-weight: var(--strong-weight); font-size: var(--font-size); overflow: hidden; text-overflow: ellipsis; white-space: nowrap; max-width: 100%; }
 .ident-email { color: var(--muted); font-size: 12px; white-space: nowrap; overflow: hidden; text-overflow: ellipsis; margin-top: 1px; }
-.email-btn { all: unset; cursor: pointer; border-radius: 4px; }
+.email-btn, .model-btn { all: unset; cursor: pointer; border-radius: 4px; }
+.model-btn:hover { color: var(--text); text-decoration: underline dotted; }
+.model-btn:focus-visible { outline: var(--focus-outline); outline-offset: 2px; }
+.model-set { color: var(--accent); }
+.md-now { display: flex; flex-direction: column; gap: 4px; }
 .email-btn:hover { color: var(--text); text-decoration: underline dotted; }
 .email-btn:focus-visible { outline: var(--focus-outline); outline-offset: 2px; }
 .ident-email + .ident-sub { color: var(--faint); margin-top: 0; }

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/dist/src/types.d.ts

@@ -77,6 +77,8 @@ export interface FamilyDef {
     };
     loginState?(account: Account): Promise<LoginState>;
     model?(account: Account): Promise<string | undefined>;
+    /** Choosing the model and effort an Account starts with, as Host arguments (spec §3.19, ADR-0014). */
+    modelChoice?: FamilyModelChoice;
     /**
      * Who the Account is signed in as, from the Host's own login file: identity fields such as the email and the
      * organization only, never a token or any other credential value (ADR-0003). Return undefined when unknown; an
@@ -224,6 +226,30 @@ export interface TokenTotals {
     cacheWriteTokens: number;
     totalTokens: number;
 }
+/** A model and an effort level; a field left out means the Host's own default. */
+export interface ModelChoice {
+    model?: string;
+    effort?: string;
+}
+export interface FamilyModelChoice {
+    /** Effort levels the Host accepts at launch, lowest first. */
+    efforts: readonly string[];
+    /** Model names to offer; any other name may be typed. */
+    models: readonly string[];
+    /**
+     * What the Host's own config sets for new sessions of the Account. Reads only the model and effort keys. A
+     * per-model effort is looked up for `model` (the model sideby starts it with), else the config's own model, else
+     * `lastModel` (the model of the newest session).
+     */
+    configured(account: Account, model?: string, lastModel?: string): Promise<ModelChoice>;
+    /** Host arguments that start a session with `choice`. */
+    toArgs(choice: ModelChoice): string[];
+    /** The choice in `args`, and the other arguments in their order. */
+    fromArgs(args: readonly string[]): {
+        choice: ModelChoice;
+        rest: string[];
+    };
+}
 export type UsageResult = ({
     status: 'ok';
     days: number;
@@ -239,6 +265,9 @@ export type UsageResult = ({
     }[];
     /** ISO time of the newest record the reader saw, not later than now. */
     lastActivityAt?: string;
+    /** Model and effort of the newest turn the reader saw, when the logs record them (spec §3.19). */
+    lastModel?: string;
+    lastEffort?: string;
 } & TokenTotals) | {
     status: 'unavailable';
     reason: 'no-source' | 'no-session' | 'unrecognized';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sideby",
-  "version": "0.5.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)",
@@ -72,9 +72,10 @@
   "devDependencies": {
     "@biomejs/biome": "2.5.15",
     "@types/node": "^22.18.0",
+    "motion": "13.4.3",
     "typescript": "^7.0.2"
   },
   "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, then the local quota panel\" 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| 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/schemas/model.json

@@ -0,0 +1,169 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "sideby/model.json",
+  "type": "object",
+  "required": [
+    "schemaVersion",
+    "account",
+    "family",
+    "settable",
+    "efforts",
+    "models",
+    "sideby",
+    "host",
+    "last"
+  ],
+  "properties": {
+    "schemaVersion": {
+      "type": "number",
+      "const": 1
+    },
+    "account": {
+      "type": "string"
+    },
+    "family": {
+      "type": "string"
+    },
+    "settable": {
+      "type": "boolean",
+      "description": "Whether sideby can set the model and effort for this account."
+    },
+    "reason": {
+      "type": "string"
+    },
+    "efforts": {
+      "type": "array",
+      "items": {
+        "type": "string"
+      }
+    },
+    "models": {
+      "type": "array",
+      "items": {
+        "type": "string"
+      },
+      "description": "Model names to offer; any other name may be given."
+    },
+    "sideby": {
+      "type": "object",
+      "properties": {
+        "model": {
+          "type": "string"
+        },
+        "effort": {
+          "type": "string"
+        }
+      }
+    },
+    "host": {
+      "type": "object",
+      "properties": {
+        "model": {
+          "type": "string"
+        },
+        "effort": {
+          "type": "string"
+        }
+      }
+    },
+    "last": {
+      "type": "object",
+      "properties": {
+        "model": {
+          "type": "string"
+        },
+        "effort": {
+          "type": "string"
+        }
+      }
+    },
+    "model": {
+      "type": "object",
+      "required": [
+        "value",
+        "from"
+      ],
+      "properties": {
+        "value": {
+          "type": "string"
+        },
+        "from": {
+          "anyOf": [
+            {
+              "type": "string",
+              "const": "sideby"
+            },
+            {
+              "type": "string",
+              "const": "host"
+            },
+            {
+              "type": "string",
+              "const": "last"
+            }
+          ]
+        }
+      }
+    },
+    "effort": {
+      "type": "object",
+      "required": [
+        "value",
+        "from"
+      ],
+      "properties": {
+        "value": {
+          "type": "string"
+        },
+        "from": {
+          "anyOf": [
+            {
+              "type": "string",
+              "const": "sideby"
+            },
+            {
+              "type": "string",
+              "const": "host"
+            },
+            {
+              "type": "string",
+              "const": "last"
+            }
+          ]
+        }
+      }
+    },
+    "change": {
+      "type": "object",
+      "required": [
+        "changed",
+        "applied",
+        "file",
+        "diff",
+        "args"
+      ],
+      "properties": {
+        "changed": {
+          "type": "boolean"
+        },
+        "applied": {
+          "type": "boolean"
+        },
+        "file": {
+          "type": "string"
+        },
+        "diff": {
+          "type": "string"
+        },
+        "args": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          },
+          "description": "The account arguments in the config after the change."
+        }
+      }
+    }
+  },
+  "title": "sideby model --json"
+}