sideby 0.0.0-stage → 0.2.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Adonis0123
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,112 @@
-# Temporary Holding Version
+<p align="center">
+  <img alt="sideby: one shared config, every account in its own terminal" src="https://raw.githubusercontent.com/Adonis0123/sideby/main/docs/assets/banner.jpg" width="880">
+</p>
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+<p align="center">
+  <b>Run every AI coding account side by side.</b><br>
+  Claude Code, Codex, Grok Build and pi: one directory per account, one shared set of skills, hooks and rules, one panel for every quota.
+</p>
+
+<p align="center">
+  <a href="https://www.npmjs.com/package/sideby"><img alt="npm" src="https://img.shields.io/npm/v/sideby"></a>
+  <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>
+  <img alt="Node 22.18+" src="https://img.shields.io/badge/node-%E2%89%A522.18-339933">
+  <a href="LICENSE"><img alt="MIT" src="https://img.shields.io/badge/license-MIT-blue"></a>
+</p>
+
+<p align="center">English | <a href="README.zh-CN.md">中文</a></p>
+
+## Why
+
+You have a work subscription, a personal one and maybe an API key. Switching tools rewrite the Host's global config, so only one account is live at a time, and your skills and hooks slowly drift apart between accounts.
+
+- **Side by side, not switching.** Each account lives in its own directory, and sideby starts the official CLI with that directory selected. Run three accounts in three terminals; your shell is never changed.
+- **One copy of skills, hooks and rules.** Your Main Account (for example `~/.claude`) is the source. Other accounts link or copy its Shared Items ([what is shared](docs/guide/usage.md#what-each-account-shares)), and `sideby doctor --fix` repairs drift without touching real files or credentials.
+- **Every quota on one screen.** 5-hour and 7-day quota, reset times and 7-day token usage for every account. Out of room? `sideby next` starts the account with the most left. All from local files: no network calls, no token reads.
+
+## 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 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
+
+Paste this into Claude Code, Codex or any coding agent:
+
+```text
+Install the sideby CLI (npm package `sideby`) and its agent skill, then set up a second Claude Code account for me.
+Follow "Set up sideby for a user" in https://raw.githubusercontent.com/Adonis0123/sideby/main/llms.txt
+```
+
+The 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?".
+
+## What it looks like
+
+<img alt="sideby in a terminal: list accounts, check quota, pick the next account, find and fix drift" src="https://raw.githubusercontent.com/Adonis0123/sideby/main/docs/assets/demo.gif" width="1320">
+
+<picture>
+  <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/Adonis0123/sideby/main/docs/assets/panel-dark.png">
+  <source media="(prefers-color-scheme: light)" srcset="https://raw.githubusercontent.com/Adonis0123/sideby/main/docs/assets/panel.png">
+  <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>
+
+## What else it does
+
+| You want to | Run | Guide |
+|---|---|---|
+| Add an API key account (DeepSeek, a gateway, …) | `sideby new claude deepseek --api` | [API accounts](docs/guide/usage.md#api-accounts) |
+| Find and fix config drift between accounts | `sideby doctor --fix` | [Doctor](docs/guide/usage.md#doctor) |
+| See Claude quota (Codex needs no setup) | `sideby quota setup claude --yes` | [Claude quota](docs/guide/usage.md#claude-quota) |
+| Move on when an account hits its limit | `sideby next claude` | [Handoff](docs/guide/usage.md#when-an-account-hits-its-limit) |
+| 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 the panel from the Dock or app menu | `sideby app install` | [Desktop app](docs/guide/panel.md#desktop-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) |
+
+## Supported hosts
+
+| Host | Account directories | Sign-in | Quota | Usage (7 days) |
+|---|---|---|---|---|
+| Claude Code | `~/.claude`, `~/.claude-<name>` | `claude auth login` | ✓ after `quota setup claude` | ✓ |
+| Codex CLI | `~/.codex`, `~/.codex-<name>` | `codex login` | ✓ | ✓ |
+| Grok Build | `~/.grok`, `~/.grok-<name>` | `grok login` | no public source | no public source |
+| pi | `~/.pi/agent`, `~/.pi-<name>/agent` | `/login` inside pi | no public source | no public source |
+
+sideby 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).
+
+## Safe by design
+
+- It never edits a Host's global config to switch accounts, and never rotates accounts by itself.
+- It never reads, prints or sends a credential value. Nothing leaves your machine: sideby calls no remote service.
+- `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).
+
+## Docs
+
+- [Using sideby](docs/guide/usage.md): accounts, API accounts, Doctor, quota, Handoff, Host notes
+- [Commands](docs/guide/commands.md): every command, exit codes and `--json`
+- [Configuration](docs/guide/configuration.md): `config.json`, aliases, shell functions
+- [Panel](docs/guide/panel.md): the panel, desktop app and embedding
+- [Plugins](docs/guide/plugins.md): write your own Family or launch hook
+- [FAQ](docs/guide/faq.md): terms of service, data locations, alternatives, uninstall
+
+## For AI agents
+
+- [`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.
+- [`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.
+- [`AGENTS.md`](AGENTS.md): rules for agents working on this repository.
+
+## License
+
+[MIT](LICENSE)

package/README.zh-CN.md

@@ -0,0 +1,112 @@
+<p align="center">
+  <img alt="sideby：一份共享配置，每个账号一个终端" src="https://raw.githubusercontent.com/Adonis0123/sideby/main/docs/assets/banner.jpg" width="880">
+</p>
+
+<p align="center">
+  <b>Run every AI coding account side by side.</b><br>
+  把 Claude Code、Codex、Grok Build、pi 的多个账号并排跑起来：每个账号一个目录，skills、hooks、规则共用一份，额度在一个面板里看完。
+</p>
+
+<p align="center">
+  <a href="https://www.npmjs.com/package/sideby"><img alt="npm" src="https://img.shields.io/npm/v/sideby"></a>
+  <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>
+  <img alt="Node 22.18+" src="https://img.shields.io/badge/node-%E2%89%A522.18-339933">
+  <a href="LICENSE"><img alt="MIT" src="https://img.shields.io/badge/license-MIT-blue"></a>
+</p>
+
+<p align="center"><a href="README.md">English</a> | 中文</p>
+
+## 为什么用 sideby
+
+你有一个工作订阅、一个个人订阅，可能还有一个 API key。切换类工具会改宿主的全局配置，同一时间只有一个账号生效；各账号的 skills 和 hooks 也会慢慢变得不一致。
+
+- **并排，不切换。** 每个账号一个独立目录，sideby 启动官方 CLI 时选中这个目录。三个账号可以同时开在三个终端里，你的 shell 环境不受影响。
+- **skills、hooks、规则只维护一份。** 主账号（例如 `~/.claude`）是唯一来源，其他账号链接或复制它的共享项（Shared Item，[共享了哪些](docs/guide/usage.zh-CN.md#每个账号共享什么)）。`sideby doctor --fix` 修复漂移，不碰真实文件，也不碰凭据。
+- **额度一屏看完。** 每个账号的 5 小时、7 天额度、重置时间和近 7 天 token 用量。额度用完了，`sideby next` 帮你启动剩余最多的账号。数据都来自本地文件：不联网，不读 token。
+
+## 快速上手
+
+需要 Node 22.18 或更高版本，并且至少装好一个宿主 CLI（Claude Code、Codex、Grok Build 或 pi）。AI agent 请改按 [`llms.txt`](llms.txt) 里 "Set up sideby for a user" 的步骤做。
+
+```sh
+npm i -g sideby
+sideby new claude work        # 新建 ~/.claude-work，共用 ~/.claude 的 skills 和 hooks
+sideby login claude:work      # 登录一次
+sideby run work               # 用 work 账号启动 Claude Code
+sideby ui                     # 在 http://127.0.0.1:17420 查看所有账号的额度
+```
+
+`sideby run claude:main` 可以同时在另一个终端里继续用 `~/.claude`。`--` 之后的参数原样交给宿主：`sideby run work -- --resume`。不想安装，可以先跑 `npx sideby` 试试。
+
+## 让 AI 帮你装
+
+把下面这段粘贴给 Claude Code、Codex 或其他 coding agent：
+
+```text
+帮我安装 sideby（npm 包 `sideby`）和它的 agent skill，再给我加一个 Claude Code 账号。
+按 https://raw.githubusercontent.com/Adonis0123/sideby/main/llms.txt 里 "Set up sideby for a user" 的步骤来。
+```
+
+agent 会检查 Node 和宿主 CLI，装好 sideby 和 skill，建账号，告诉你它和主账号共享什么，并让短命令生效。你只需要在浏览器里登录一次，agent 会把那一行命令给你。装好 skill 之后，简短的说法也行：「再加一个 Claude 账号，叫 cc008」「我的 Codex 账号共享了什么」「哪个账号还有额度」。
+
+## 长什么样
+
+<img alt="终端里的 sideby：列出账号、查看额度、推荐下一个账号、发现并修复漂移" src="https://raw.githubusercontent.com/Adonis0123/sideby/main/docs/assets/demo.gif" width="1320">
+
+<picture>
+  <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/Adonis0123/sideby/main/docs/assets/panel-dark.png">
+  <source media="(prefers-color-scheme: light)" srcset="https://raw.githubusercontent.com/Adonis0123/sideby/main/docs/assets/panel.png">
+  <img alt="sideby 面板：每个账号的 5h、7d 额度，近 7 天 token 用量和健康状态" src="https://raw.githubusercontent.com/Adonis0123/sideby/main/docs/assets/panel.png" width="1280">
+</picture>
+
+## 还能做什么
+
+| 你想 | 命令 | 说明 |
+|---|---|---|
+| 加一个 API key 账号（DeepSeek、网关等） | `sideby new claude deepseek --api` | [API 账号](docs/guide/usage.zh-CN.md#api-账号) |
+| 找出并修复账号之间的配置漂移 | `sideby doctor --fix` | [体检](docs/guide/usage.zh-CN.md#体检doctor) |
+| 看 Claude 额度（Codex 不用设置） | `sideby quota setup claude --yes` | [Claude 额度](docs/guide/usage.zh-CN.md#claude-额度) |
+| 账号撞上限额时换一个接着用 | `sideby next claude` | [接力](docs/guide/usage.zh-CN.md#账号撞上限额时) |
+| 用 `ccw` 这样的短命令 | `sideby alias add ccw claude:work` | [Shell 函数](docs/guide/configuration.zh-CN.md#shell-函数) |
+| 在 Orca 这类工具里重开会话时，自动进到存有它的账号 | config 里写 `"resumeRouting": true` | [从其他工具恢复会话](docs/guide/configuration.zh-CN.md#从其他工具恢复会话) |
+| 从 Dock 或应用菜单打开面板 | `sideby app install` | [桌面应用](docs/guide/panel.zh-CN.md#桌面应用) |
+| 把面板嵌进自己的本地页面 | `createPanelHandler()` | [嵌入面板](docs/guide/panel.zh-CN.md#嵌入面板) |
+| 新增一个宿主，或加启动前检查 | 本地插件 | [插件](docs/guide/plugins.zh-CN.md) |
+
+## 支持的宿主
+
+| 宿主 | 账号目录 | 登录 | 额度 | 用量（7 天） |
+|---|---|---|---|---|
+| Claude Code | `~/.claude`、`~/.claude-<name>` | `claude auth login` | ✓ 需先 `quota setup claude` | ✓ |
+| Codex CLI | `~/.codex`、`~/.codex-<name>` | `codex login` | ✓ | ✓ |
+| Grok Build | `~/.grok`、`~/.grok-<name>` | `grok login` | 无公开来源 | 无公开来源 |
+| pi | `~/.pi/agent`、`~/.pi-<name>/agent` | 在 pi 里输入 `/login` | 无公开来源 | 无公开来源 |
+
+sideby 启动 `PATH` 上的官方程序，从不修改它。测试过的版本和各宿主的注意事项见[使用指南](docs/guide/usage.zh-CN.md#宿主说明)。
+
+## 安全边界
+
+- 不改宿主的全局配置来切换账号，也不会自己轮换账号。
+- 不读取、不打印、不发送任何凭据的值。数据不出本机：sideby 不调用任何远程服务。
+- `doctor --fix` 不替换真实文件，也不改链接的指向。
+
+细节和服务条款的问题见[常见问题](docs/guide/faq.zh-CN.md)。
+
+## 文档
+
+- [使用指南](docs/guide/usage.zh-CN.md)：账号、API 账号、体检、额度、接力、宿主说明
+- [命令](docs/guide/commands.zh-CN.md)：所有命令、退出码和 `--json`
+- [配置](docs/guide/configuration.zh-CN.md)：`config.json`、短命令、Shell 函数
+- [面板](docs/guide/panel.zh-CN.md)：面板、桌面应用、嵌入
+- [插件](docs/guide/plugins.zh-CN.md)：自己写家族或启动 hook
+- [常见问题](docs/guide/faq.zh-CN.md)：服务条款、数据位置、同类工具对比、卸载
+
+## 给 AI agent
+
+- [`llms.txt`](llms.txt)：安装步骤、命令、JSON 契约和插件 API 的索引。`sideby families --json` 给出每个宿主的账号共享什么。
+- [`skills/sideby/SKILL.md`](skills/sideby/SKILL.md)：一个 Agent Skill，用来查看、修复、新建账号，以及在额度用完时换账号。用 `npx skills add Adonis0123/sideby -g` 安装；装的版本和 sideby 不一致时，`sideby doctor` 会提醒。
+- [`AGENTS.md`](AGENTS.md)：给维护本仓库的 agent 的规则。
+
+## 许可证
+
+[MIT](LICENSE)

package/dist/build.json

@@ -0,0 +1 @@
+{"id":"20261008T092033-baf95a"}

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

@@ -0,0 +1,13 @@
+export declare class UsageError extends Error {
+}
+export interface ParsedArgs {
+    positionals: string[];
+    flags: Map<string, string | true>;
+    /** Everything after the first `--`, untouched. */
+    rest: string[];
+}
+/**
+ * Parses `--flag`, `--flag=value` and `--flag value` (for flags listed in `valued`).
+ * Unknown flags are usage errors so typos never silently change behaviour.
+ */
+export declare function parseArgs(argv: readonly string[], known: readonly string[], valued?: readonly string[]): ParsedArgs;

package/dist/src/cli/args.js

@@ -0,0 +1,38 @@
+export class UsageError extends Error {
+}
+/**
+ * Parses `--flag`, `--flag=value` and `--flag value` (for flags listed in `valued`).
+ * Unknown flags are usage errors so typos never silently change behaviour.
+ */
+export function parseArgs(argv, known, valued = []) {
+    const positionals = [];
+    const flags = new Map();
+    for (let i = 0; i < argv.length; i++) {
+        const a = argv[i];
+        if (a === '--')
+            return { positionals, flags, rest: argv.slice(i + 1) };
+        if (a.startsWith('--') && a.length > 2) {
+            const [name, value] = a.slice(2).split(/=(.*)/s, 2);
+            if (!known.includes(name) && !valued.includes(name))
+                throw new UsageError(`unknown option --${name}`);
+            if (valued.includes(name)) {
+                const v = value ?? argv[++i];
+                if (v === undefined)
+                    throw new UsageError(`--${name} needs a value`);
+                flags.set(name, v);
+            }
+            else {
+                if (value !== undefined)
+                    throw new UsageError(`--${name} does not take a value`);
+                flags.set(name, true);
+            }
+            continue;
+        }
+        if (a === '-h') {
+            flags.set('help', true);
+            continue;
+        }
+        positionals.push(a);
+    }
+    return { positionals, flags, rest: [] };
+}

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

@@ -0,0 +1,50 @@
+import type { DoctorReport } from '../core/doctor.ts';
+import type { Finding } from '../types.ts';
+import { type ParsedArgs } from './args.ts';
+export interface Io {
+    out(s: string): void;
+    err(s: string): void;
+}
+export declare function serializeDoctor(r: DoctorReport): {
+    status: "issues" | "ok";
+    accounts: {
+        ref: string;
+        family: string;
+        name: string;
+        kind: import("../types.ts").Account['kind'];
+        dir: string;
+        shared: {
+            ok: number;
+            total: number;
+        };
+        backups: number;
+        findings: Omit<Finding, "fix">[];
+    }[];
+    general: Omit<Finding, "fix">[];
+    fixes: import("../core/doctor.ts").FixOutcome[];
+};
+export declare function cmdList(a: ParsedArgs, io: Io): Promise<number>;
+export interface NewSuggestion {
+    name: string;
+    alias?: string;
+    /** Why the alias the pattern suggests was left out (taken, reserved); the Account is created without it. */
+    aliasProblem?: string;
+}
+export declare function cmdNew(a: ParsedArgs, io: Io): Promise<number>;
+export declare function cmdRun(a: ParsedArgs, io: Io, command: 'run' | 'login'): Promise<number>;
+/**
+ * `sideby resume <family>`: what the Host-named shell function calls (spec §3.15). Starts the Account that holds the
+ * session the arguments resume by id, or runs the Host unchanged.
+ */
+export declare function cmdResume(a: ParsedArgs, io: Io): Promise<number>;
+/** `sideby next <family>`: recommend the Account with the most room, then start it (spec §3.13). */
+export declare function cmdNext(a: ParsedArgs, io: Io): Promise<number>;
+export declare function cmdDoctor(a: ParsedArgs, io: Io): Promise<number>;
+export declare function cmdQuota(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>;
+export declare function cmdApp(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). */
+export declare function cmdFamilies(a: ParsedArgs, io: Io): Promise<number>;