sideby 0.0.0-stage → 0.1.0

package/schemas/next.json

@@ -0,0 +1,127 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "sideby/next.json",
+  "type": "object",
+  "required": [
+    "schemaVersion",
+    "family",
+    "pick",
+    "accounts",
+    "hasQuota"
+  ],
+  "properties": {
+    "schemaVersion": {
+      "type": "number",
+      "const": 1
+    },
+    "family": {
+      "type": "string"
+    },
+    "pick": {
+      "anyOf": [
+        {
+          "type": "string"
+        },
+        {
+          "type": "null"
+        }
+      ],
+      "description": "The recommended account; null when none can be used now (exit code 1)."
+    },
+    "accounts": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": [
+          "ref",
+          "kind",
+          "state",
+          "pressure"
+        ],
+        "properties": {
+          "ref": {
+            "type": "string"
+          },
+          "kind": {
+            "anyOf": [
+              {
+                "type": "string",
+                "const": "subscription"
+              },
+              {
+                "type": "string",
+                "const": "api"
+              }
+            ]
+          },
+          "state": {
+            "anyOf": [
+              {
+                "type": "string",
+                "const": "ready"
+              },
+              {
+                "type": "string",
+                "const": "unknown"
+              },
+              {
+                "type": "string",
+                "const": "api"
+              },
+              {
+                "type": "string",
+                "const": "full"
+              },
+              {
+                "type": "string",
+                "const": "logged-out"
+              }
+            ],
+            "description": "ready and unknown can be picked; api only with --include-api; full and logged-out never."
+          },
+          "pressure": {
+            "anyOf": [
+              {
+                "type": "number"
+              },
+              {
+                "type": "null"
+              }
+            ],
+            "description": "Used percent of the fullest window not reset yet; null without quota."
+          },
+          "resetsAt": {
+            "type": "string",
+            "description": "For full: when its last full window resets."
+          },
+          "observedAt": {
+            "type": "string",
+            "description": "When the account's quota was recorded (its last session)."
+          }
+        }
+      },
+      "description": "Every account of the family, best first."
+    },
+    "hasQuota": {
+      "type": "boolean",
+      "description": "False when no account has quota data: the pick is then a guess, and `sideby next` does not start it (exit 1)."
+    },
+    "earliestReset": {
+      "type": "object",
+      "required": [
+        "ref",
+        "at"
+      ],
+      "properties": {
+        "ref": {
+          "type": "string"
+        },
+        "at": {
+          "type": "string"
+        }
+      },
+      "description": "Set when nothing can be picked and some accounts are full: the first to come back."
+    }
+  },
+  "title": "sideby next --json"
+}

package/schemas/plugins.json

@@ -0,0 +1,74 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "sideby/plugins.json",
+  "type": "object",
+  "required": [
+    "schemaVersion",
+    "plugins",
+    "errors"
+  ],
+  "properties": {
+    "schemaVersion": {
+      "type": "number",
+      "const": 1
+    },
+    "plugins": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": [
+          "name",
+          "version",
+          "source",
+          "families",
+          "configKeys"
+        ],
+        "properties": {
+          "name": {
+            "type": "string"
+          },
+          "version": {
+            "type": "string"
+          },
+          "source": {
+            "type": "string"
+          },
+          "description": {
+            "type": "string"
+          },
+          "families": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            }
+          },
+          "configKeys": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            }
+          }
+        }
+      }
+    },
+    "errors": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": [
+          "where",
+          "message"
+        ],
+        "properties": {
+          "where": {
+            "type": "string"
+          },
+          "message": {
+            "type": "string"
+          }
+        }
+      }
+    }
+  },
+  "title": "sideby plugins --json"
+}

package/schemas/quota-setup.json

@@ -0,0 +1,60 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "sideby/quota-setup.json",
+  "type": "object",
+  "required": [
+    "schemaVersion",
+    "family",
+    "applied",
+    "plan"
+  ],
+  "properties": {
+    "schemaVersion": {
+      "type": "number",
+      "const": 1
+    },
+    "family": {
+      "type": "string"
+    },
+    "applied": {
+      "type": "boolean"
+    },
+    "plan": {
+      "type": "object",
+      "required": [
+        "status",
+        "file",
+        "diff",
+        "message"
+      ],
+      "properties": {
+        "status": {
+          "anyOf": [
+            {
+              "type": "string",
+              "const": "enabled"
+            },
+            {
+              "type": "string",
+              "const": "ready"
+            },
+            {
+              "type": "string",
+              "const": "blocked"
+            }
+          ]
+        },
+        "file": {
+          "type": "string"
+        },
+        "diff": {
+          "type": "string"
+        },
+        "message": {
+          "type": "string"
+        }
+      }
+    }
+  },
+  "title": "sideby quota setup --json"
+}

package/schemas/quota-teardown.json

@@ -0,0 +1,30 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "sideby/quota-teardown.json",
+  "type": "object",
+  "required": [
+    "schemaVersion",
+    "family",
+    "ok",
+    "message"
+  ],
+  "properties": {
+    "schemaVersion": {
+      "type": "number",
+      "const": 1
+    },
+    "family": {
+      "type": "string"
+    },
+    "ok": {
+      "type": "boolean"
+    },
+    "message": {
+      "type": "string"
+    },
+    "diff": {
+      "type": "string"
+    }
+  },
+  "title": "sideby quota teardown --json"
+}

package/schemas/quota.json

@@ -0,0 +1,203 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "sideby/quota.json",
+  "type": "object",
+  "required": [
+    "schemaVersion",
+    "accounts"
+  ],
+  "properties": {
+    "schemaVersion": {
+      "type": "number",
+      "const": 1
+    },
+    "accounts": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": [
+          "ref",
+          "kind",
+          "quota",
+          "usage"
+        ],
+        "properties": {
+          "ref": {
+            "type": "string"
+          },
+          "kind": {
+            "anyOf": [
+              {
+                "type": "string",
+                "const": "subscription"
+              },
+              {
+                "type": "string",
+                "const": "api"
+              }
+            ]
+          },
+          "quota": {
+            "anyOf": [
+              {
+                "type": "object",
+                "required": [
+                  "status",
+                  "windows",
+                  "observedAt",
+                  "source"
+                ],
+                "properties": {
+                  "status": {
+                    "type": "string",
+                    "const": "ok"
+                  },
+                  "windows": {
+                    "type": "array",
+                    "items": {
+                      "type": "object",
+                      "required": [
+                        "label",
+                        "windowMinutes",
+                        "usedPercent",
+                        "resetsAt"
+                      ],
+                      "properties": {
+                        "label": {
+                          "type": "string"
+                        },
+                        "windowMinutes": {
+                          "type": "number"
+                        },
+                        "usedPercent": {
+                          "type": "number"
+                        },
+                        "resetsAt": {
+                          "type": "string"
+                        }
+                      }
+                    }
+                  },
+                  "observedAt": {
+                    "type": "string"
+                  },
+                  "source": {
+                    "type": "string"
+                  },
+                  "plan": {
+                    "type": "string"
+                  }
+                }
+              },
+              {
+                "type": "object",
+                "required": [
+                  "status",
+                  "reason"
+                ],
+                "properties": {
+                  "status": {
+                    "type": "string",
+                    "const": "unavailable"
+                  },
+                  "reason": {
+                    "type": "string"
+                  },
+                  "detail": {
+                    "type": "string"
+                  }
+                }
+              }
+            ]
+          },
+          "usage": {
+            "anyOf": [
+              {
+                "type": "object",
+                "required": [
+                  "status",
+                  "days",
+                  "sessions",
+                  "inputTokens",
+                  "outputTokens",
+                  "cacheReadTokens",
+                  "cacheWriteTokens",
+                  "totalTokens"
+                ],
+                "properties": {
+                  "status": {
+                    "type": "string",
+                    "const": "ok"
+                  },
+                  "days": {
+                    "type": "number"
+                  },
+                  "sessions": {
+                    "type": "number"
+                  },
+                  "inputTokens": {
+                    "type": "number"
+                  },
+                  "outputTokens": {
+                    "type": "number"
+                  },
+                  "cacheReadTokens": {
+                    "type": "number"
+                  },
+                  "cacheWriteTokens": {
+                    "type": "number"
+                  },
+                  "totalTokens": {
+                    "type": "number"
+                  },
+                  "daily": {
+                    "type": "array",
+                    "items": {
+                      "type": "object",
+                      "required": [
+                        "date",
+                        "totalTokens"
+                      ],
+                      "properties": {
+                        "date": {
+                          "type": "string"
+                        },
+                        "totalTokens": {
+                          "type": "number"
+                        }
+                      }
+                    },
+                    "description": "Tokens per local day (YYYY-MM-DD), oldest first, days without records as 0."
+                  },
+                  "lastActivityAt": {
+                    "type": "string"
+                  }
+                }
+              },
+              {
+                "type": "object",
+                "required": [
+                  "status",
+                  "reason"
+                ],
+                "properties": {
+                  "status": {
+                    "type": "string",
+                    "const": "unavailable"
+                  },
+                  "reason": {
+                    "type": "string"
+                  },
+                  "detail": {
+                    "type": "string"
+                  }
+                }
+              }
+            ]
+          }
+        }
+      }
+    }
+  },
+  "title": "sideby quota --json"
+}

package/skills/sideby/SKILL.md

@@ -0,0 +1,52 @@
+---
+name: sideby
+description: Use when the user runs several AI coding accounts (Claude Code, Codex, Grok Build, pi) and wants to see them, check how much quota or usage each has left, move on to another account because one hit its 5-hour or weekly limit, create an account or API account, add a short command (alias) for one, or repair a broken or drifted account directory (skills, hooks, rules or settings not shared, wrong symlinks, credential file permissions). Drives the `sideby` CLI with `--json` and leaves sign-in, credentials and starting sessions to the user.
+metadata:
+  version: "0.1.0"
+---
+
+# sideby
+
+`sideby` runs each AI coding account from its own directory (`~/.claude-work`, `~/.codex-api`, ...) and keeps skills, hooks and rules shared with the Main Account (`~/.claude`, `~/.codex`, `~/.grok`, `~/.pi/agent`). Use `npx sideby` if the command is not installed. Requires Node 22.18+.
+
+## Hard rules
+
+- **Never read credential files**: `proxy.env`, `auth.json`, `.claude.json`, or anything under an account directory that may hold a token. Do not `cat`, `grep`, `head`, open or summarize them. `sideby list --json` gives the signed-in email as `identity.email`; that is all you need.
+- **Never sign in for the user.** Tell them to run `sideby login <ref>` in their own terminal. OAuth needs their browser and their decision.
+- **Never put a secret on the command line or in chat.** For API accounts, the user edits `proxy.env` themselves.
+- **Never start a Host session from your shell.** `sideby run`, `sideby next` (without `--dry-run`) and `sideby login` open an interactive session; give the user the command instead.
+- **Never switch, rotate or proxy accounts.** sideby does not do it, and you must not work around that by editing config, copying session files or moving credentials. Choosing the next account is the user's call; `sideby next` only recommends.
+- **Show before you change.** Read-only commands first; changes only after the user has seen what will change.
+- Do not edit Host config files (`settings.json`, `config.toml`, symlinks in account directories) by hand when a `sideby` command does the job.
+
+## Output and exit codes
+
+- Every `--json` output has `schemaVersion: 1`. On an error it is `{ "schemaVersion": 1, "error": "<what to do next>", "code": "<reason>" }`; `code` is `usage` for a malformed command line.
+- Exit codes: `0` done, `1` failed or found a `fail` problem, `2` malformed command line, `10` **needs the user's confirmation**. `run`, `next` and `login` return the Host's own exit code once it starts.
+- On `10`: show the user the change the command printed, ask, and only after a clear yes run the same command again with `--yes` added. Never add `--yes` on your own.
+
+## What do you want to do
+
+Account refs are `<family>:<name>`; a bare `<name>` works only when it is unique. Families: `claude`, `codex`, `grok`, `pi`.
+
+| The user wants to | Run | Then read |
+|---|---|---|
+| See accounts, health, quota and usage | `sideby list --json`, `sideby doctor --json`, `sideby quota --json` | `references/diagnose.md` |
+| Repair drift or permissions | `sideby doctor [ref] --json`, then `--fix` after they agree | `references/diagnose.md` |
+| Keep working because an account hit its limit | `sideby next <family> --json` | `references/handoff.md` |
+| Create an account, an API account or a short command | `sideby new`, `sideby alias add` | `references/accounts.md` |
+| See Claude quota (it shows `not-enabled`) | `sideby quota setup claude` (exits 10) | `references/quota.md` |
+| See everything at once | `sideby ui` (local panel on `127.0.0.1:17420`; `--no-open` prints the address) | — |
+| Start an account | give them `sideby run <ref> [-- host args]` | — |
+
+Read only the reference the task needs.
+
+## Launching and the panel
+
+`eval "$(sideby shell-init zsh)"` defines one function per account (`sideby-claude-work`) plus the config `aliases`. Users who source a file instead set config `shellInitFile` (for example `{ "zsh": "~/.config/sideby/shell-init.zsh" }`); `new` and `alias add|rm` keep it current, and `sideby shell-init zsh --write` rewrites it. New functions work in a new shell.
+
+For someone who would rather double-click than use a terminal, `sideby app install` adds a desktop app (macOS `~/Applications/sideby.app`, Linux app menu) that runs `sideby ui --background`; `sideby ui --stop` stops it and `sideby app uninstall` removes the app. Ask before `app install`: it writes outside sideby's own directories.
+
+## Keeping this skill current
+
+If `sideby doctor --json` reports `skill.outdated`, this skill was written for another sideby version. Tell the user to update it with `npx skills add Adonis0123/sideby -g`.

package/skills/sideby/references/accounts.md

@@ -0,0 +1,31 @@
+# Create accounts and short commands
+
+## Create an account
+
+Check the name first: `^[a-z0-9][a-z0-9-]{0,31}$`, and not already taken (`sideby list --json`).
+
+```sh
+sideby new claude work               # subscription account: ~/.claude-work
+sideby new claude deepseek --api     # API account: ~/.claude-deepseek with a proxy.env template (mode 600)
+sideby new claude 008 --alias cc008  # also adds the short command cc008 to config aliases
+```
+
+Only pass `--alias` when the user wants a short command; follow their existing pattern (`cc001`…`cc007` for `claude:001`…`claude:007` suggests `cc008`). An invalid, reserved or taken alias is refused before anything is created (error `code: "alias-invalid"`). If `alias.added` is false in `--json`, the account exists but the alias is missing: tell the user the message, do not edit the config by hand.
+
+Then:
+
+- **Subscription account**: tell the user to run `sideby login claude:work` in their own terminal (for pi, `sideby login pi:<name>` starts pi; then they type `/login`). Do not run it for them.
+- **API account**: tell the user to open the `proxy.env` path printed by `new` in their editor and fill in the values. Do not read or write it yourself. It then shows `login: "not-needed"`.
+- **pi**: a `proxy.env` in a pi account only loads provider keys; the account stays a subscription account and still needs `/login`.
+- Afterwards: `sideby doctor <ref> --json` to confirm the new account is healthy, then the user starts it with `sideby run <ref>`.
+
+## Short commands (aliases)
+
+For an account that already exists: `sideby alias add <short> <ref> --json`.
+
+To start one account with fixed Host arguments, such as another model, put them after `--`: `sideby alias add pi-kimi pi:main --json -- --model kimi-coding/k3`. It is the same account (same login, same sessions), not a new one; do not create an account per model. Only `sideby run <short>` adds the arguments.
+
+- `status: "exists"` means it was already there.
+- A refusal names the next step (`sideby alias rm <short>` first).
+- Entry points that need environment variables are not aliases: leave them in the user's shell rc.
+- Do not edit `aliases` in the config by hand.

package/skills/sideby/references/diagnose.md

@@ -0,0 +1,47 @@
+# Diagnose and repair
+
+## Diagnose
+
+Start read-only:
+
+```sh
+sideby list --json        # accounts: ref, family, kind (subscription|api), dir, login, identity.email, model, hostInstalled, problems
+sideby doctor --json      # findings: level ok|warn|fail, account, item, code, message, hint, fixable
+sideby quota --json       # per account: quota windows (5h, 7d, usedPercent, resetsAt, observedAt) and 7-day tokens
+sideby plugins --json     # loaded plugins (setting names only, never values) and load errors
+```
+
+Narrow with an account or family: `sideby doctor claude:work --json`, `sideby doctor codex --json`, `sideby quota work --json`. On an ambiguity error, use the full ref from the candidates listed.
+
+Shared Items the Main Account does not have are skipped: no Finding, not counted in `shared`. A directory such as `~/.claude-code-router` that holds neither `proxy.env` nor any Shared Item is not listed as an account.
+
+| Signal | Meaning | What to do |
+|---|---|---|
+| `fail` / `warn` with `fixable: true` | Safe repair exists | Offer `doctor --fix` (see Repair) |
+| `fixable: false` with a `hint` | sideby will not touch it on purpose (real file where a link belongs, API account item) | Show the hint; the user decides |
+| `warn` `link.other-target` | The link resolves, but not to the Main Account's item; often deliberate | Mention it; change nothing unless the user asks |
+| `fail` `link.dangling` | The link points at nothing | Show the hint (`ls -l <path>`); the user decides how to repair it |
+| `fail` `symlink-forbidden` without `fixable` | The Host needs a real file here, but the link points somewhere other than the Main Account | Show the hint; sideby will not replace a link it did not create |
+| credential item, mode not 600 | `proxy.env`, `auth.json`, `.claude.json` readable by others | `--fix` resets the mode to 600 |
+| `warn` `skill.outdated` (in `general`) | The installed sideby skill is for another sideby version | Tell the user to run `npx skills add Adonis0123/sideby -g` |
+| name looks like a backup (`bak`, `backup`, `old`, `tmp`) | A stray directory was picked up as an account | Suggest adding its ref to `ignore` in `${XDG_CONFIG_HOME:-~/.config}/sideby/config.json` |
+| `login: "not-needed"` (`key` in `sideby list`) | API account; it authenticates with `proxy.env` | Nothing to do |
+| `problems` on an account in `list --json` | A plugin failed while reading it (for example a settings file that is not valid JSON) | Show the message; the account itself still works |
+| quota `unavailable` / `not-enabled` | Claude quota source is off | Offer `sideby quota setup claude` |
+| quota `unavailable` / `no-session` | No session since the source was enabled | Ask the user to start one session with that account |
+| quota `unavailable` / `no-source` | Grok, pi: the Host has no public source | Nothing to fix |
+| quota `unavailable` / `api-account` | API accounts have no quota | Nothing to fix |
+| quota `unavailable` / `unrecognized` | Host changed its file format | Report it; suggest filing an issue with the Host version |
+| host not installed | Accounts exist but the CLI is missing | Point to the Host's install docs; do not install it unasked |
+
+Quota is only as fresh as each account's last session; `observedAt` says when it was recorded. A window whose `resetsAt` has passed has reset.
+
+## Repair
+
+1. Run `sideby doctor [ref] --json` and show the user every finding you plan to fix, grouped by account.
+2. After the user agrees, run `sideby doctor [ref] --fix`, then `sideby doctor [ref] --json` again and report what is still open.
+3. `--force` is only for `json-key` items (for example `.claude.json#mcpServers`) when a fix would remove entries the account already has. Never add `--force` without telling the user exactly which entries would disappear.
+
+`--fix` never replaces a real file with a link, never re-points an existing symlink (wrong or dangling links are only reported), never writes through a link into the Main Account, and never changes credential contents. Findings it skips need a human decision; explain the hint, do not work around it with `rm` or `ln`.
+
+`doctor` exits 1 only when a `fail` finding is left; warnings alone exit 0.

package/skills/sideby/references/handoff.md

@@ -0,0 +1,41 @@
+# Handoff: keep working on another account
+
+Use this when the user says an account hit its 5-hour or weekly limit ("usage limit reached", "rate limited", "resets at …") and wants to keep working, or asks which account has room. sideby recommends the account of the same family with the lowest Quota Pressure (the fullest window that has not reset yet). It never switches by itself; the user starts the next account.
+
+## Steps
+
+1. Run `sideby next <family> --json` (`claude` or `codex`). It only recommends; it starts nothing.
+2. Tell the user the pick and why, from `pick` and `accounts`:
+
+   | `state` | Meaning | Can be picked |
+   |---|---|---|
+   | `ready` | Subscription account with room; `pressure` is its fullest live window in percent | Yes, lowest `pressure` first |
+   | `unknown` | No quota data yet (no session since quota was turned on, or Claude quota is off) | Yes, after `ready` |
+   | `api` | API account, pay per use | Only with `--include-api` |
+   | `full` | A live window is at 85% or more; `resetsAt` is when it is usable again | No |
+   | `logged-out` | Needs `sideby login <ref>` | No |
+
+   Each entry's `observedAt` says when its quota was recorded. If `hasQuota` is `false`, no account has quota data: the pick is only a guess, so say so and suggest turning quota on (see the routing table in SKILL.md) or letting the user choose.
+3. Give the user the command to run in their own terminal: `sideby next <family>` (starts the pick) or `sideby run <pick>`. Host arguments go after `--`. Do not run it yourself.
+4. Offer a handoff note: the new session starts empty, because each account keeps its own sessions. Write a short note the user can paste into it: the goal, what is done, what is in progress, the files involved, and the next step.
+
+## When nothing can be picked
+
+`pick` is `null` and the exit code is 1:
+
+- Every account `full`: tell the user `earliestReset.ref` comes back at `earliestReset.at`.
+- Accounts `logged-out`: the user can sign in with `sideby login <ref>`.
+- Only `api` left: ask whether they want to pay per use before suggesting `sideby next <family> --include-api`.
+
+## Other answers
+
+- Error `code: "no-quota-source"` (Grok, pi): the Host publishes no quota. The message lists the family's accounts; let the user choose one for `sideby run <ref>`.
+- Error `code: "no-accounts"`: the family has no account yet; see creating accounts.
+- Many `unknown` Claude accounts: Claude quota may be off. `sideby quota --json` shows `not-enabled`; the one-time setup turns it on.
+- Host arguments the user wants (another model, say) go after `--`: `sideby next claude -- --model opus`.
+- Quota is only as fresh as each account's last session. Do not promise an account has room; say what the data shows and when it was recorded.
+
+## Never
+
+- Switch accounts by editing config or environment, copy session files between account directories, or read any credential.
+- Start a session for the user.