sideby 0.10.0 → 0.12.0

package/README.md

@@ -16,31 +16,20 @@
 
 <p align="center">English | <a href="README.zh-CN.md">中文</a></p>
 
-## Why not just an alias?
-
-`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)
-
-| | At the same time | Skills, hooks, settings | Quota and usage | Setup |
-|---|---|---|---|---|
-| `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 |
-| [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 |
-| 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 |
-
-cc-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.
-
 ## Quick start
 
 Requires 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.
 
 ```sh
 npm i -g sideby
-sideby new claude work        # create ~/.claude-work, sharing ~/.claude's skills and hooks
-sideby login claude:work      # sign in once
-sideby run work               # Claude Code on the work account
-sideby ui                     # every account's quota at http://127.0.0.1:17420
+sideby new claude work           # create ~/.claude-work, sharing ~/.claude's skills and hooks
+sideby login claude:work         # sign in once
+sideby run work                  # Claude Code on the work account
+sideby quota setup claude --yes  # Claude quota in the panel; undo: sideby quota teardown claude
+sideby ui                        # every account's quota at http://127.0.0.1:17420
 ```
 
-`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`.
+`sideby update` installs a newer sideby when there is one; sideby says so after a command and in the panel. `sideby run claude:main` keeps using `~/.claude` in another terminal at the same time. Arguments after `--` go to the Host: `sideby run work -- --resume`. To try it without installing, run `npx sideby`.
 
 ## Set up with your AI agent
 
@@ -55,6 +44,10 @@ The agent checks Node and your Host CLIs, installs sideby and the skill, creates
 
 ## What it looks like
 
+The 25-second story: one account buried in tasks, then accounts side by side sharing one setup, and a task moving on when one runs out.
+
+https://github.com/user-attachments/assets/3a470c03-9009-4f1d-b7f6-8b4625d74958
+
 <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">
 
 <picture>
@@ -63,6 +56,18 @@ The agent checks Node and your Host CLIs, installs sideby and the skill, creates
   <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">
 </picture>
 
+## Why not just an alias?
+
+`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)
+
+| | At the same time | Skills, hooks, settings | Quota and usage | Setup |
+|---|---|---|---|---|
+| `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 |
+| [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 |
+| 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 |
+
+cc-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.
+
 ## What else it does
 
 | You want to | Run | Guide |
@@ -78,6 +83,7 @@ The agent checks Node and your Host CLIs, installs sideby and the skill, creates
 | Short commands such as `ccw` | `sideby alias add ccw claude:work` | [Shell functions](docs/guide/configuration.md#shell-functions) |
 | 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) |
 | 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) |
+| Keep several Grok Bot windows open, each signed in to its own account (macOS) | `sideby desktop grok-bot:002` (or the panel) | [Grok Bot windows](docs/guide/usage.md#grok-bot-windows) |
 | Open the panel from the Dock or app menu | `sideby app install` | [Panel app](docs/guide/panel.md#panel-app) |
 | Show the panel inside your own local page | `createPanelHandler()` | [Embed the panel](docs/guide/panel.md#embed-the-panel) |
 | Add a Host or a pre-launch check | a local plugin | [Plugins](docs/guide/plugins.md) |
@@ -104,7 +110,7 @@ macOS and Linux. CI runs the suite on `ubuntu-latest` and `macos-latest`, Node 2
 ## Safe by design
 
 - 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.
-- It never reads, prints or sends a credential value. Nothing leaves your machine: sideby calls no remote service.
+- It never reads, prints or sends a credential value. Nothing about your accounts leaves your machine: the only request sideby makes on its own is a daily check of the npm registry for its newest version (off with `NO_UPDATE_NOTIFIER=1`; see [Updates](docs/guide/configuration.md#updates)).
 - `doctor --fix` never replaces a real file and never changes where a link points.
 
 Details and the terms-of-service question are in the [FAQ](docs/guide/faq.md).

package/dist/build.json

@@ -1 +1 @@
-{"id":"20261015T150956-8c8f4c"}
+{"id":"20261016T071613-e5f0f1"}

package/dist/src/cli/commands.d.ts

@@ -61,8 +61,18 @@ export declare function cmdHandoff(a: ParsedArgs, io: Io): Promise<number>;
 export declare function cmdPlugins(a: ParsedArgs, io: Io): Promise<number>;
 export declare function cmdShellInit(a: ParsedArgs, io: Io): Promise<number>;
 export declare function cmdUi(a: ParsedArgs, io: Io): Promise<number>;
+/**
+ * `sideby update [--yes] [--json]` (spec §3.23): asks the registry now, shows what an Update runs, and runs it with
+ * `--yes` (exit 10 before). An install sideby cannot update gets the command to run and exit 1.
+ */
+export declare function cmdUpdate(a: ParsedArgs, io: Io): Promise<number>;
+/** The internal `sideby update-check` the CLI starts detached: one Update Check, then Auto Update if it is on. */
+export declare function cmdUpdateCheck(_a: ParsedArgs, _io: Io): Promise<number>;
 export declare function cmdApp(a: ParsedArgs, io: Io): Promise<number>;
-/** `sideby desktop <account>`: the Family's Desktop App as that Account (spec §3.20). */
+/**
+ * `sideby desktop <account>`: the Family's Desktop App as that Account (spec §3.20); `sideby desktop grok-bot:<name>`:
+ * a Grok Bot window, new or open, and with `--remove` its removal (ADR-0019).
+ */
 export declare function cmdDesktop(a: ParsedArgs, io: Io): Promise<number>;
 export declare function cmdAlias(a: ParsedArgs, io: Io): Promise<number>;
 /** `sideby families [family]`: each Family's layout, sign-in and Shared Items, from its FamilyDef (spec §3.16). */

package/dist/src/cli/commands.js

@@ -1,5 +1,6 @@
 import { fileURLToPath } from 'node:url';
 import { aliasesByAccount } from '../core/accounts.js';
+import { listAppProfiles, openAppProfile, parseProfileRef, removeAppProfile } from '../core/app-profiles.js';
 import { aliasRefs } from '../core/config.js';
 import { openDesktopApp, withDesktopApps } from '../core/desktop-app.js';
 import { UserError } from '../core/errors.js';
@@ -16,8 +17,22 @@ import { suggestAlias, suggestName } from '../panel/page-logic.js';
 import { createRuntime, UnknownFamilyError } from '../runtime.js';
 import { UsageError } from './args.js';
 import { c, clock, compactNumber, quotaText, table, tuningLines, usageText } from './format.js';
+/** Runs `fn` while a record under the state directory says a Host runs (also for `login`), so an Auto Update waits (spec §3.23). */
+async function whileRunning(rt, fn) {
+    const { markRunning } = await import('../core/update.js');
+    const done = await markRunning(rt.paths);
+    try {
+        return await fn();
+    }
+    finally {
+        await done().catch(() => { });
+    }
+}
 /** Runs the Account with Auto Handoff when it applies (spec §3.17), else the Host as usual. */
 async function runAccount(rt, ref, args, io) {
+    return whileRunning(rt, () => runAccountNow(rt, ref, args, io));
+}
+async function runAccountNow(rt, ref, args, io) {
     const handed = await runWithHandoff(rt, ref, args, {
         err: (l) => io.err(c.dim(l)),
         stdin: io.stdin ?? process.stdin,
@@ -55,11 +70,14 @@ function tilde(text, home) {
 export async function cmdList(a, io) {
     const rt = await createRuntime();
     const accounts = await rt.accounts();
-    const statuses = await withDesktopApps(rt, accounts, Promise.all(accounts.map((x) => rt.status(x))));
+    const [statuses, appProfiles] = await Promise.all([
+        withDesktopApps(rt, accounts, Promise.all(accounts.map((x) => rt.status(x)))),
+        listAppProfiles(rt),
+    ]);
     const hasDesktop = statuses.some((s) => s.desktopApp);
     const families = await rt.familyInfo();
     if (a.flags.has('json')) {
-        json(io, { families, accounts: statuses, pluginErrors: [...rt.pluginErrors] });
+        json(io, { families, accounts: statuses, appProfiles, pluginErrors: [...rt.pluginErrors] });
         return 0;
     }
     const home = rt.paths.home;
@@ -94,6 +112,25 @@ export async function cmdList(a, io) {
             io.out(c.dim('\n= <account>: signed in as the same login as that account, so they share one quota.'));
         io.out(c.dim('\nsideby run <account>  ·  sideby new <family> <name>  ·  sideby quota  ·  sideby ui'));
     }
+    // App Profiles (ADR-0019): windows of an app that signs in apart from the Accounts above.
+    for (const app of new Set(appProfiles.map((p) => p.app))) {
+        const list = appProfiles.filter((p) => p.app === app);
+        io.out(`\n${c.bold(app)} ${c.dim('(signs in on its own, not with the accounts above)')}`);
+        io.out(table(list.map((p) => [
+            c.bold(p.ref),
+            p.running ? c.green('open') : c.dim('—'),
+            p.signedIn === true
+                ? c.green('signed in')
+                : p.signedIn === false
+                    ? c.yellow('not signed in')
+                    : c.dim('?'),
+            p.appData ? tildify(p.appData, home) : c.dim('default'),
+        ]), ['WINDOW', 'STATE', 'SIGN-IN', 'DATA']));
+        if (!list[0]?.installed)
+            io.out(c.yellow(`${app} is not installed; these windows open again once it is`));
+        const id = list[0]?.ref.slice(0, list[0].ref.indexOf(':'));
+        io.out(c.dim(`sideby desktop ${id}:<name> opens one (a new name makes a new window)`));
+    }
     for (const s of statuses)
         for (const p of s.problems ?? [])
             io.err(c.yellow(`${s.ref}: ${p}`));
@@ -185,7 +222,7 @@ export async function cmdRun(a, io, command) {
     const prepared = await rt.prepareLaunch(ref, [...extra, ...a.rest], command);
     if (prepared.notice)
         io.err(c.cyan(prepared.notice));
-    return runHost(prepared);
+    return whileRunning(rt, () => runHost(prepared));
 }
 /**
  * `sideby resume <family>`: what the Host-named shell function calls (spec §3.15). Starts the Account that holds the
@@ -201,7 +238,7 @@ export async function cmdResume(a, io) {
         io.err(c.dim(`sideby: session ${route.sessionId} was never saved; starting a new session in ${route.account.ref}`));
     else if (route.account)
         io.err(c.dim(`sideby: session ${route.sessionId} is in ${route.account.ref}; starting it there`));
-    return runHost(route.launch);
+    return whileRunning(rt, () => runHost(route.launch));
 }
 /** Quotes a Host argument for a command line the user may paste; plain words stay as they are. */
 function shellQuote(arg) {
@@ -860,7 +897,10 @@ export async function cmdHandoff(a, io) {
             requested: true,
             ...(next ? { next } : {}),
             ...(request.brief ? { brief: request.brief } : {}),
+            ...(request.now ? { now: true } : {}),
         });
+    else if (request.now)
+        io.out(`This session was waiting for its quota; ${next ?? 'the next account'} takes over now.`);
     else
         io.out(`${next ? `${next} takes over` : 'The next account starts'} when this turn ends; finish the turn now.`);
     return 0;
@@ -977,6 +1017,84 @@ export async function cmdUi(a, io) {
     });
     return 0;
 }
+/**
+ * `sideby update [--yes] [--json]` (spec §3.23): asks the registry now, shows what an Update runs, and runs it with
+ * `--yes` (exit 10 before). An install sideby cannot update gets the command to run and exit 1.
+ */
+export async function cmdUpdate(a, io) {
+    if (a.positionals.length)
+        throw new UsageError('usage: sideby update [--yes] [--json]');
+    const u = await import('../core/update.js');
+    const { SKILL_INSTALL } = await import('../core/skill-check.js');
+    const { backgroundPanelPort } = await import('../panel/background.js');
+    const paths = resolvePaths(process.env);
+    const asJson = a.flags.has('json');
+    const plan = await u.planUpdate(paths, process.env);
+    const shown = u.shownPlan(plan);
+    if (!plan.available) {
+        if (asJson)
+            json(io, { ...shown, updated: false });
+        else
+            io.out(`${c.green('✓')} sideby ${plan.current} is the latest version.`);
+        return 0;
+    }
+    if (!plan.canRun) {
+        if (asJson)
+            json(io, { ...shown, updated: false });
+        else {
+            io.out(`sideby ${c.bold(plan.latest)} is available (you have ${plan.current}). What changed: ${plan.releaseNotes}`);
+            io.err(c.yellow(`sideby cannot update itself: ${plan.method.reason}. Run it yourself:\n  ${plan.command}`));
+        }
+        return 1;
+    }
+    if (!a.flags.has('yes')) {
+        if (asJson)
+            json(io, { ...shown, updated: false });
+        else {
+            io.out(`sideby ${c.bold(plan.latest)} is available (you have ${plan.current}). What changed: ${plan.releaseNotes}`);
+            io.out(`\nUpdating runs:\n  ${plan.command}`);
+            io.out(c.cyan('\nRun it with `sideby update --yes`.'));
+        }
+        return 10;
+    }
+    if (!asJson)
+        io.out(c.dim(`$ ${plan.command}`));
+    const r = await u.applyUpdate(paths, plan, process.env, {
+        ...(asJson ? {} : { onOutput: (text) => process.stderr.write(text) }),
+        panelPort: () => backgroundPanelPort(paths),
+    });
+    if (asJson) {
+        json(io, {
+            ...shown,
+            updated: r.ok,
+            message: r.message,
+            restartedPanel: r.restartedPanel,
+            skill: SKILL_INSTALL,
+            ...(r.ok ? {} : { output: r.output }),
+        });
+        return r.ok ? 0 : 1;
+    }
+    if (!r.ok) {
+        io.err(c.red(`✗ ${r.message}`));
+        return 1;
+    }
+    io.out(`${c.green('✓')} ${r.message}.`);
+    if (r.restartedPanel)
+        io.out('  The background panel is restarting with the new version; open pages reload by themselves.');
+    io.out('  A `sideby ui` running in a terminal and sessions already running keep the old version until you restart them.');
+    io.out(`  If you use the sideby skill, update it too: ${SKILL_INSTALL}`);
+    return 0;
+}
+/** The internal `sideby update-check` the CLI starts detached: one Update Check, then Auto Update if it is on. */
+export async function cmdUpdateCheck(_a, _io) {
+    const { backgroundCheck } = await import('../core/update.js');
+    const { loadConfig } = await import('../core/config.js');
+    const { backgroundPanelPort } = await import('../panel/background.js');
+    const paths = resolvePaths(process.env);
+    const config = await loadConfig(paths.configFile).catch(() => ({}));
+    await backgroundCheck(paths, process.env, config, () => backgroundPanelPort(paths));
+    return 0;
+}
 export async function cmdApp(a, io) {
     const sub = a.positionals[0];
     const usage = 'usage: sideby app install [--url <url>] | sideby app uninstall';
@@ -1019,13 +1137,32 @@ export async function cmdApp(a, io) {
     }
     return r.skipped.length ? 1 : 0;
 }
-/** `sideby desktop <account>`: the Family's Desktop App as that Account (spec §3.20). */
+/**
+ * `sideby desktop <account>`: the Family's Desktop App as that Account (spec §3.20); `sideby desktop grok-bot:<name>`:
+ * a Grok Bot window, new or open, and with `--remove` its removal (ADR-0019).
+ */
 export async function cmdDesktop(a, io) {
     const [ref, ...extra] = a.positionals;
     if (!ref || extra.length || a.rest.length)
-        throw new UsageError('usage: sideby desktop <account>');
+        throw new UsageError('usage: sideby desktop <account> | sideby desktop grok-bot:<name> [--remove [--yes]]');
     const rt = await createRuntime();
-    const r = await openDesktopApp(rt, ref);
+    const profile = parseProfileRef(ref) !== undefined;
+    if (a.flags.has('remove')) {
+        if (!profile)
+            throw new UsageError('--remove works on Grok Bot windows only: sideby desktop grok-bot:<name> --remove');
+        const r = await removeAppProfile(rt, ref, { yes: a.flags.has('yes') });
+        if (a.flags.has('json'))
+            json(io, r);
+        else if (r.removed)
+            io.out(`${c.green('✓')} removed the ${r.app} window ${c.bold(r.ref)} and its data`);
+        else {
+            io.out(`Remove the ${r.app} window ${c.bold(r.ref)}?`);
+            io.out(`  deletes ${tildify(r.appData, rt.paths.home)}: its sign-in, bots and local data on this Mac`);
+            io.out('Run again with --yes to remove it.');
+        }
+        return r.removed ? 0 : 10;
+    }
+    const r = profile ? await openAppProfile(rt, ref) : await openDesktopApp(rt, ref);
     if (a.flags.has('json')) {
         json(io, r);
         return 0;

package/dist/src/cli/json-schemas.js

@@ -194,11 +194,30 @@ const ShellInitFiles = Type.Array(Type.Object({
     action: Type.Optional(Type.Union([Type.Literal('written'), Type.Literal('unchanged')])),
     message: Type.Optional(Str),
 }), { description: 'One entry per config `shellInitFile`, rewritten after the change.' });
+const AppProfile = Type.Object({
+    ref: Type.String({ description: "`grok-bot:<name>`; `grok-bot:main` is the app's own default data." }),
+    app: Type.String({ description: 'The app, for example `Grok Bot`.' }),
+    name: Str,
+    isMain: Type.Boolean(),
+    appData: Type.Optional(Type.String({
+        description: "This window's data folder; absent for the main one, which uses the app's default.",
+    })),
+    installed: Type.Boolean(),
+    running: Type.Boolean({ description: "This window's own instance runs now." }),
+    signedIn: Type.Optional(Type.Boolean({
+        description: 'What the app last wrote about its sign-in (it keeps the last value after the app quits); absent when unknown. Which account is signed in is not known.',
+    })),
+}, {
+    description: 'A window of a desktop app that signs in apart from every account (Grok Bot, ADR-0019). Open or create one with `sideby desktop grok-bot:<name>`.',
+});
 export const OUTPUT_SCHEMAS = {
     list: Type.Object({
         schemaVersion: Version,
         families: Type.Array(FamilyInfo),
         accounts: Type.Array(AccountStatus),
+        appProfiles: Type.Optional(Type.Array(AppProfile, {
+            description: 'Grok Bot windows (macOS, when Grok Bot is installed or has windows), the main one first. Not accounts.',
+        })),
         pluginErrors: Type.Array(PluginError),
     }, { title: 'sideby list --json' }),
     doctor: Type.Object({
@@ -380,6 +399,8 @@ export const OUTPUT_SCHEMAS = {
         requested: Type.Literal(true),
         next: Type.Optional(Str),
         brief: Type.Optional(Str),
+        /** The session was waiting for its quota, so the handoff starts now instead of after a turn (ADR-0018). */
+        now: Type.Optional(Type.Literal(true)),
     }, { title: 'sideby handoff ready --json' }),
     'handoff-setup': Type.Object({ schemaVersion: Version, family: Str, applied: Type.Boolean(), plan: QuotaSetupPlan }, { title: 'sideby handoff setup --json' }),
     'handoff-teardown': Type.Object({ schemaVersion: Version, family: Str, ok: Type.Boolean(), message: Str, diff: Type.Optional(Str) }, { title: 'sideby handoff teardown --json' }),
@@ -445,7 +466,7 @@ export const OUTPUT_SCHEMAS = {
     desktop: Type.Object({
         schemaVersion: Version,
         ref: Str,
-        family: Str,
+        family: Type.String({ description: 'The family, or `grok-bot` for a Grok Bot window.' }),
         app: Type.String({ description: 'The desktop app, for example `Claude Desktop`.' }),
         appPath: Str,
         action: Type.Union([Type.Literal('started'), Type.Literal('focused'), Type.Literal('already-running')], {
@@ -461,6 +482,40 @@ export const OUTPUT_SCHEMAS = {
         command: Type.Optional(Type.Array(Str, { description: 'The `open` command sideby ran.' })),
         notices: Type.Array(Str),
     }, { title: 'sideby desktop --json' }),
+    'desktop-remove': Type.Object({
+        schemaVersion: Version,
+        ref: Str,
+        app: Str,
+        appData: Type.String({ description: 'The folder that is (or would be) deleted.' }),
+        removed: Type.Boolean({
+            description: 'False when only the plan was shown; run again with --yes (exit 10).',
+        }),
+    }, { title: 'sideby desktop grok-bot:<name> --remove --json' }),
+    update: Type.Object({
+        schemaVersion: Version,
+        current: Type.String({ description: 'The running sideby version.' }),
+        latest: Type.String({ description: 'The `latest` version on the npm registry.' }),
+        available: Type.Boolean({ description: '`latest` is newer than `current`.' }),
+        method: Type.Object({
+            kind: Type.Union(['npm', 'pnpm', 'bun', 'volta', 'npx', 'project', 'source'].map((k) => Type.Literal(k)), { description: 'How this copy was installed.' }),
+            canUpdate: Type.Boolean({ description: 'sideby can run the Update itself.' }),
+            reason: Type.Optional(Type.String({ description: 'Why it cannot.' })),
+        }),
+        command: Type.String({
+            description: 'What an Update runs, or what to run by hand when `canRun` is false.',
+        }),
+        canRun: Type.Boolean(),
+        releaseNotes: Type.String({ description: 'The release notes of `latest`.' }),
+        updated: Type.Boolean({
+            description: 'False when only the plan was shown (exit 10 with --yes still to add) or nothing to do.',
+        }),
+        message: Type.Optional(Type.String()),
+        restartedPanel: Type.Optional(Type.Boolean({
+            description: 'A background Panel was running and starts again with the new version.',
+        })),
+        skill: Type.Optional(Type.String({ description: 'The command that updates the sideby skill; sideby never runs it.' })),
+        output: Type.Optional(Type.String({ description: 'What the failed install command printed.' })),
+    }, { title: 'sideby update --json' }),
     error: Type.Object({
         schemaVersion: Version,
         error: Type.String({ description: 'What went wrong and what to do next.' }),

package/dist/src/cli/main.js

@@ -51,16 +51,18 @@ Usage:
   sideby ui --stop                    stop the background panel
   sideby desktop <account>            open the desktop app (Claude Desktop, the Codex app) as this
                                       account, next to the others (macOS)
+  sideby desktop grok-bot:<name>      open a Grok Bot window, a new one for a new name (macOS)
   sideby app install [--url <url>]    add a sideby app that opens the panel (macOS, Linux)
   sideby app uninstall                remove that app
   sideby shell-init zsh|bash          print shell functions, e.g. eval "$(sideby shell-init zsh)"
   sideby shell-init [zsh|bash] --write
                                       rewrite the config's shellInitFile with them
   sideby plugins                      list loaded plugins and load errors
+  sideby update [--yes]               update sideby to the newest version (shows the command first)
 
 Options:
   --json        machine-readable output (list, new, next, alias, doctor, quota, tune, model, remote-control, handoff,
-                families, plugins, app, desktop)
+                families, plugins, app, desktop, update)
   -h, --help    show this help; \`sideby <command> --help\` for new, alias, login, doctor, families, desktop
   -v, --version show the version
 
@@ -72,7 +74,10 @@ For AI agents:
   Setup steps and the full contract: https://github.com/Adonis0123/sideby/blob/main/llms.txt
   Run everything else yourself, but hand the user these as one line each: \`sideby login <account>\`
   (browser sign-in), filling in proxy.env, and \`sideby run\` or \`sideby next\` (interactive sessions).
-  Exit 10 means a change was shown: ask the user, then run it again with --yes.`;
+  Exit 10 means a change was shown: ask the user, then run it again with --yes.
+
+Updates: once a day sideby asks the npm registry for its newest version and says so after a command.
+  Turn it off with NO_UPDATE_NOTIFIER=1 or config "update": { "check": false }; "auto": true installs by itself.`;
 /** `sideby <command> --help` for the commands agents use to set up and repair accounts (spec §3.16). */
 const COMMAND_HELP = {
     new: `sideby new <family> <name> [--api] [--alias <short>] [--json]
@@ -133,6 +138,7 @@ Examples:
   sideby doctor claude:008 --fix
 Exit: 0 when nothing fails (warnings allowed); 1 when a check fails.`,
     desktop: `sideby desktop <account> [--json]
+       sideby desktop grok-bot:<name> [--remove [--yes]] [--json]
 
 Open the host's desktop app as one account: Claude Desktop for claude accounts, the Codex app (ChatGPT.app) for codex
 accounts. Each account gets its own window, side by side with the others; macOS only for now.
@@ -142,14 +148,22 @@ directory (CLAUDE_CONFIG_DIR, CODEX_HOME) and its own app data folder,
 ~/Library/Application Support/sideby/<family>/<name>/. When that account's window is already open, sideby brings it
 to the front instead of starting another one. API accounts are refused: the apps sign in with a subscription only.
 
-sideby never copies or changes the app, and never closes a window. The first time, sign in inside Claude Desktop;
-close other Claude Desktop windows while you do, because the sign-in may come back to one of them.
+Grok Bot signs in with a Cursor account, apart from every account above, so its windows have names of their own:
+grok-bot:<name> opens that window, and makes it first when the name is new (a new window, signed out). grok-bot or
+grok-bot:main is Grok Bot's own default window. --remove deletes a window you made, which signs it out and deletes
+its data on this Mac; it asks for --yes first (exit 10) and refuses while that window is open. \`sideby list\` shows
+the Grok Bot windows.
+
+sideby never copies or changes the app, and never closes a window. The first time, sign in inside the new window;
+close the app's other windows while you do, because the sign-in may come back to one of them.
 
 Examples:
   sideby desktop claude:work
   sideby desktop cc008 --json
-Exit: 0 opened or brought to the front; 1 not macOS, no desktop app for that host, API account, app not installed,
-or the app did not open; 2 malformed command line.`,
+  sideby desktop grok-bot:002
+  sideby desktop grok-bot:002 --remove --yes
+Exit: 0 opened, brought to the front or removed; 1 not macOS, no desktop app for that host, API account, app not
+installed, a bad window name, or the app did not open; 10 --remove without --yes; 2 malformed command line.`,
     families: `sideby families [family] [--json]
 
 For each host (built in or from a plugin): where its accounts live, the variable that selects one, how to sign
@@ -189,11 +203,58 @@ const COMMANDS = {
     },
     ui: { flags: ['no-open', 'background', 'stop', 'serve-detached'], valued: ['port'] },
     app: { flags: ['json'], valued: ['url'] },
-    desktop: { flags: ['json'] },
+    desktop: { flags: ['json', 'remove', 'yes'] },
     'shell-init': { flags: ['write'] },
     plugins: { flags: ['json'] },
     families: { flags: ['json'] },
+    update: { flags: ['json', 'yes'] },
+    'update-check': { flags: [] },
 };
+/** Commands that never print an Update Notice: their output is read by a shell or an agent, or they are internal. */
+function noticeAllowed(cmd, parsed) {
+    if (cmd === 'shell-init' || cmd === 'update' || cmd === 'update-check')
+        return false;
+    if (cmd === 'ui' && parsed.flags.has('serve-detached'))
+        return false;
+    if (cmd === 'handoff' && parsed.positionals[0] === 'ready')
+        return false;
+    return true;
+}
+/**
+ * After a command (spec §3.23): print the Update Notice and the result of an Auto Update, each at most once, and
+ * start the next Update Check detached when the last one is a day old. Only on a terminal; never fails the command.
+ */
+async function afterCommand() {
+    if (!process.stderr.isTTY)
+        return;
+    try {
+        const u = await import('../core/update.js');
+        const { resolvePaths } = await import('../core/paths.js');
+        const { loadConfig } = await import('../core/config.js');
+        const { packageVersion } = await import('../core/version.js');
+        const paths = resolvePaths(process.env);
+        const config = await loadConfig(paths.configFile).catch(() => ({}));
+        const cache = await u.readUpdateCache(paths);
+        const plan = u.afterCommandPlan(cache, packageVersion(), config, process.env, new Date());
+        const dim = process.env.NO_COLOR ? (t) => t : (t) => `\x1b[2m${t}\x1b[22m`;
+        for (const l of plan.lines)
+            console.error(dim(l));
+        if (plan.record)
+            await u.updateUpdateCache(paths, plan.record);
+        if (plan.startCheck) {
+            const { spawn } = await import('node:child_process');
+            const child = spawn(process.execPath, [fileURLToPath(import.meta.url), 'update-check'], {
+                detached: true,
+                stdio: 'ignore',
+            });
+            child.on('error', () => { });
+            child.unref();
+        }
+    }
+    catch {
+        // an Update Notice is never worth failing a command
+    }
+}
 export async function main(argv) {
     const [first, ...rest] = argv;
     // Claude Code runs this on every status-line refresh. It must still launch the original command when Node is
@@ -264,47 +325,10 @@ export async function main(argv) {
             return 0;
         }
         const cmds = await import('./commands.js');
-        switch (cmd) {
-            case 'list':
-                return await cmds.cmdList(parsed, io);
-            case 'run':
-                return await cmds.cmdRun(parsed, io, 'run');
-            case 'login':
-                return await cmds.cmdRun(parsed, io, 'login');
-            case 'resume':
-                return await cmds.cmdResume(parsed, io);
-            case 'next':
-                return await cmds.cmdNext(parsed, io);
-            case 'new':
-                return await cmds.cmdNew(parsed, io);
-            case 'alias':
-                return await cmds.cmdAlias(parsed, io);
-            case 'doctor':
-                return await cmds.cmdDoctor(parsed, io);
-            case 'quota':
-                return await cmds.cmdQuota(parsed, io);
-            case 'tune':
-                return await cmds.cmdTune(parsed, io);
-            case 'model':
-                return await cmds.cmdModel(parsed, io);
-            case 'remote-control':
-                return await cmds.cmdRemoteControl(parsed, io);
-            case 'handoff':
-                return await cmds.cmdHandoff(parsed, io);
-            case 'ui':
-                return await cmds.cmdUi(parsed, io);
-            case 'app':
-                return await cmds.cmdApp(parsed, io);
-            case 'desktop':
-                return await cmds.cmdDesktop(parsed, io);
-            case 'shell-init':
-                return await cmds.cmdShellInit(parsed, io);
-            case 'plugins':
-                return await cmds.cmdPlugins(parsed, io);
-            case 'families':
-                return await cmds.cmdFamilies(parsed, io);
-        }
-        return 2;
+        const code = await dispatch(cmd, parsed, io, cmds);
+        if (!wantsJson && noticeAllowed(cmd, parsed))
+            await afterCommand();
+        return code;
     }
     catch (err) {
         const usage = err instanceof UsageError;
@@ -321,6 +345,53 @@ export async function main(argv) {
         return usage ? 2 : 1;
     }
 }
+async function dispatch(cmd, parsed, io, cmds) {
+    switch (cmd) {
+        case 'list':
+            return await cmds.cmdList(parsed, io);
+        case 'run':
+            return await cmds.cmdRun(parsed, io, 'run');
+        case 'login':
+            return await cmds.cmdRun(parsed, io, 'login');
+        case 'resume':
+            return await cmds.cmdResume(parsed, io);
+        case 'next':
+            return await cmds.cmdNext(parsed, io);
+        case 'new':
+            return await cmds.cmdNew(parsed, io);
+        case 'alias':
+            return await cmds.cmdAlias(parsed, io);
+        case 'doctor':
+            return await cmds.cmdDoctor(parsed, io);
+        case 'quota':
+            return await cmds.cmdQuota(parsed, io);
+        case 'tune':
+            return await cmds.cmdTune(parsed, io);
+        case 'model':
+            return await cmds.cmdModel(parsed, io);
+        case 'remote-control':
+            return await cmds.cmdRemoteControl(parsed, io);
+        case 'handoff':
+            return await cmds.cmdHandoff(parsed, io);
+        case 'ui':
+            return await cmds.cmdUi(parsed, io);
+        case 'app':
+            return await cmds.cmdApp(parsed, io);
+        case 'desktop':
+            return await cmds.cmdDesktop(parsed, io);
+        case 'shell-init':
+            return await cmds.cmdShellInit(parsed, io);
+        case 'plugins':
+            return await cmds.cmdPlugins(parsed, io);
+        case 'families':
+            return await cmds.cmdFamilies(parsed, io);
+        case 'update':
+            return await cmds.cmdUpdate(parsed, io);
+        case 'update-check':
+            return await cmds.cmdUpdateCheck(parsed, io);
+    }
+    return 2;
+}
 // Run when executed directly, also through symlinks (npm's bin shim, a user alias like `sb`).
 function isEntry() {
     const arg = process.argv[1];