sideby 0.1.0 → 0.2.2

package/skills/sideby/SKILL.md

@@ -1,22 +1,27 @@
 ---
 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.
+description: Use when the user runs, or wants to run, several AI coding accounts (Claude Code, Codex, Grok Build, pi) side by side. Covers installing sideby and setting up a new account ("install sideby", "set up another Claude account", "add cc008", "配置一个 cc00x", "再加一个 Codex 账号"), explaining what accounts share and what stays separate ("what do my accounts share?", "这些账号共享了什么"), seeing accounts, quota and usage, moving on when one hits its 5-hour or weekly limit, adding a short command (alias), and repairing drifted account directories (skills, hooks, rules or settings not shared, wrong symlinks, credential file permissions). Drives the `sideby` CLI with `--json`; the agent does every step except browser sign-in, filling in secrets and starting interactive sessions, which it hands to the user as one command.
 metadata:
-  version: "0.1.0"
+  version: "0.2.2"
+  requires:
+    bins: [sideby, node]
+  cliHelp: sideby --help
 ---
 
 # 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+.
+`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`). Requires Node 22.18+. If `sideby` is not installed, follow `references/setup.md`; `sideby <command> --help` shows examples for `new`, `alias`, `login`, `doctor` and `families`.
+
+Do every step you can yourself. Only browser sign-in, secrets and interactive sessions belong to the user: hand each to them as exactly one line to run (in Claude Code they can type `! <command>`), then continue once they say it is done.
 
 ## 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 sign in for the user.** Give them `sideby login <ref>` as one line to run in their own terminal (Claude Code: `! sideby login <ref>`). 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.
+- **Say what you change.** Read-only commands first. What the user asked for (the account they asked to create, its short command, the shell line that makes it work) you do, saying what you do. Changes they did not ask for (`doctor --fix` on other accounts, `quota setup`, `app install`) wait until they have seen the change and agreed.
 - 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
@@ -31,10 +36,12 @@ Account refs are `<family>:<name>`; a bare `<name>` works only when it is unique
 
 | The user wants to | Run | Then read |
 |---|---|---|
+| Install sideby, or set up a new account ("add cc008") | `sideby --version`, `sideby list --json`, `sideby new <family> --next --json` | `references/setup.md` |
+| Know what accounts share and what stays separate | `sideby families <family> --json` | `references/sharing.md` |
 | 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` |
+| Create an account with a given name, 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]` | — |
@@ -45,6 +52,8 @@ Read only the reference the task needs.
 
 `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.
 
+When a terminal manager such as Orca reopens a pane with a bare `claude --resume <id>` (or `codex resume <id>`, `grok --resume <id>`) and the Host says `No conversation found`, the session lives in another account. Suggest config `"resumeRouting": true` followed by `sideby shell-init --write` (or a new shell with `eval`): `shell-init` then defines Host-named functions that call `sideby resume <family>`, which starts the account holding that session. For a one-off, find it with `ls -d ~/.claude*/projects/*/<id>.jsonl` and run `sideby run <ref> -- --resume <id>`.
+
 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

package/skills/sideby/references/accounts.md

@@ -10,7 +10,7 @@ sideby new claude deepseek --api     # API account: ~/.claude-deepseek with a pr
 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.
+Only pass `--alias` when the user wants a short command. To continue their numbering (`cc001`…`cc007` for `claude:001`…`claude:007`), use `sideby new claude --next --json` instead of a name: it picks `008` and `cc008` the same way the panel does (see `setup.md`). 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:
 

package/skills/sideby/references/setup.md

@@ -0,0 +1,31 @@
+# Install sideby and set up an account
+
+For "install sideby", "set up another Claude account", "add cc008", "配置一个 cc00x". Do each step yourself unless it says **user**; give the user that step as exactly one line (in Claude Code: `! <command>`) and continue when they say it is done.
+
+1. **Node and sideby.** `node --version` must be 22.18 or newer; otherwise tell the user to upgrade Node and stop. `sideby --version`; when it is missing, run `npm i -g sideby` (Claude quota and shell functions need the global install, not `npx`).
+2. **This skill.** If it was not installed with `npx skills add Adonis0123/sideby -g`, install it that way so it stays current; `sideby doctor` warns when it is for another version.
+3. **Hosts and accounts.** `sideby list --json`. `families[].installed: false` means that Host CLI is not on PATH: give the user its `installUrl` and stop; never install a Host unasked. No `<family>:main` in `accounts` means the Host has never run: ask the user to start it once (for example `claude`), because `new` builds on the Main Account.
+4. **What it will share.** `sideby families <family> --json`, then tell the user in a sentence or two (see `sharing.md`): skills, hooks, rules and settings come from the Main Account; sign-in, sessions and history are the new account's own.
+5. **Create.**
+   - The user gave no name, or said "cc00x" / "the next one": `sideby new <family> --next --json`. It picks the next number (`008` after `001`…`007`) and, when existing short commands show a pattern (`cc007` for `claude:007`), adds the next one (`cc008`). Read `suggestion`: `aliasProblem` means that short command was taken and left out; tell the user.
+   - The user gave a name: `sideby new <family> <name> --json`; a short command they named: add `--alias <short>`.
+   - An API account (DeepSeek, a gateway, …): add `--api`.
+   - A short command the user did not ask for and no pattern suggests: none. Do not invent a prefix.
+6. **user: sign in or fill in the key.**
+   - Subscription account: `sideby login <ref>`. It opens the Host's sign-in in their browser. For pi it starts pi; they type `/login`.
+   - API account: they open the `proxy.env` path that `new` printed and fill in the values. Never read or write it, and never ask for the key in chat.
+7. **Short command in new terminals.** If `~/.config/sideby/config.json` has no `shellInitFile`, and `~/.zshrc` (bash: `~/.bashrc`) has no line containing `sideby shell-init`, say so and append `eval "$(sideby shell-init zsh)"` (or `bash`). It takes effect in new terminals. Skip this when the user wanted no short command.
+8. **Verify.** `sideby doctor <ref> --json` should report no `fail`; fix only the new account with `sideby doctor <ref> --fix`. After the user signed in, `sideby list --json` shows `login: "logged-in"` for it.
+9. **Optional, Claude Code:** for quota in `sideby quota` and the panel, follow `quota.md` (it needs the user's yes).
+
+Finish with how to start it: the short command in a new terminal (`cc008`), or `sideby run <ref>`; and `sideby ui` to see every account's quota.
+
+## When a step fails
+
+| Result | Do |
+|---|---|
+| `new` exit 1, `code: "alias-invalid"` | Nothing was created. Pick another short command with the user, or leave `--alias` out. |
+| `new` says the directory exists | The account is already there: `sideby list --json`, then continue from step 6. |
+| `new` says the Main Account is missing | Step 3: the user starts the Host once. |
+| `npm i -g` fails with `EACCES` | npm's global directory is not writable; tell the user to use a Node version manager (nvm, fnm) rather than `sudo`. |
+| `doctor` reports `link.real-file` | The account already had its own file there; show the hint, do not move it without the user. |

package/skills/sideby/references/sharing.md

@@ -0,0 +1,17 @@
+# What accounts share
+
+Answer from `sideby families [family] --json`, not from memory: it covers plugin families and the user's own `extraSharedItems`. Each `shared[]` entry has `path`, `mode` and `meaning`, a sentence you can quote.
+
+- **Shared** (one copy, from the Main Account): `link` items. A change in the Main Account reaches every account at once.
+- **Kept equal**: `copy` and `link-or-copy` items, a subscription account's `local-if-api` item, and the one key of a `json-key` item (Claude's MCP servers in `.claude.json`). `sideby doctor --fix` brings them back in line after the Main Account changes.
+- **The account's own**: `local` items (copied once, then theirs), an API account's `local-if-api` item (it starts as a copy, so its endpoint and model never change the Main Account's), and `info` items such as `auth.json` (sign-in; never shared, never read).
+- **Not in the list at all**: sessions, history and everything else in the account directory belong to that account. That is why two accounts can run at the same time.
+
+An item the Main Account does not have is skipped: nothing to share, no Finding.
+
+To share one more file or directory (a `scripts` folder, a status line script), add it to config `extraSharedItems`, for example `{ "extraSharedItems": { "claude": [{ "path": "scripts", "mode": "link" }] } }` in `~/.config/sideby/config.json`, then run `sideby doctor claude --fix` to link it into every account. Keep the user's other config keys; never add a path with `..` or an absolute path.
+
+Two answers people often need:
+
+- "Will my new account have my MCP servers?" Claude Code: yes, `new` copies the `mcpServers` entry and `doctor --fix` keeps it equal later; OAuth servers (GitHub, Figma) still need each account to authorize once. Codex: yes for subscription accounts, through the linked `config.toml`.
+- "Will it see my old sessions?" No. Sessions stay in the account that made them; `sideby run <old-account> -- --resume` reopens them there.