starbridge 0.1.0-rc.1 → 0.1.1

package/README.md

@@ -3,7 +3,8 @@
 `starbridge` connects a machine that runs agents to your phone and browsers. Agents use it to ask
 you questions and report runs, and it uploads what each AI plan has left, read from CodexBar. It
 signs everything with this machine's key and encrypts it for your devices, so the server sees
-ciphertext only.
+ciphertext only. CodexBar is optional: setup asks before installing it, `--no-quota` skips it,
+and questions, runs and permission prompts work without it.
 
 ## Install
 
@@ -43,35 +44,48 @@ starbridge setup
 
 ### What setup does
 
-Setup asks before each step except pairing and the background service, and a rerun repairs only
-what is missing:
-
-1. It pairs the machine with your account (see [Pair](#pair)). It asks for the server only when
-   neither `--server` nor `STARBRIDGE_SERVER` names one.
-2. It finds CodexBar, or installs it (Linux and macOS; CodexBar has no Windows build, so a
-   Windows machine uploads no quotas): with Homebrew if you have it, else CodexBar's latest
-   release tarball from GitHub, checked against the `.sha256` that release publishes, into
-   `~/.local/opt/codexbar`. It installs nothing when the checksum is missing or does not match.
-   Then it asks which providers' quotas to upload.
-3. It installs the background service, `starbridge agent`, as a systemd user unit, a launchd
-   agent, or on Windows a Scheduled Task that starts at logon without administrator rights and
-   logs to `%LOCALAPPDATA%\starbridge\agent.log`.
-4. It installs Starbridge in each agent it finds: the Claude Code plugin at user scope, the
-   skill in Codex's skills folder, the Starbridge Pi package, and the skill and plugin in
-   opencode's config folder. A later setup updates the Codex and opencode files when the CLI
-   carries newer ones. The Claude Code plugin needs Claude Code 2.1.287 or later; setup says
-   when it is older. Claude Code, Codex and Pi may then run `starbridge ask`, `waiting`,
-   `working`, `wait` and `settle` without a permission prompt; `starbridge run` still asks, since
-   the command it wraps can be anything. For Pi, setup adds these rules only when
-   pi-permission-system is installed; `starbridge config permissions on` offers them later.
-5. It asks whether to send [permission prompts](#permission-prompts) to your devices. The
-   default is no.
-6. It uploads a first quota snapshot, then offers to send a test question to your phone and
+Setup asks only before installing CodexBar, which providers to send, whether the agent runs
+after you log out, whether to add the CLI to your PATH, and whether to send a test
+question; steps 1 and 3 say when it asks more. A rerun repairs only what is missing:
+
+1. It pairs the machine with your account (see [Pair](#pair)), with the first server named by
+   `--server`, `STARBRIDGE_SERVER`, the install script (each server's own names that server),
+   or the machine's pairing, else https://starbridge.run. It asks only when the machine is
+   already paired with another server, and Enter keeps that one.
+2. It installs Starbridge in each agent it finds and prints one line per agent: the Claude Code
+   plugin at user scope, the skill and sandbox rule in Codex's folders, the Starbridge Pi
+   package, and the skill and plugin in opencode's config folder. A failed install prints its
+   reason and the command that retries it, and setup goes on. A later setup updates the Codex
+   and opencode files when the CLI carries newer ones. The Claude Code plugin needs Claude Code
+   2.1.287 or later; setup says when it is older. Claude Code, Codex and Pi may then run
+   `starbridge ask`, `waiting`, `working`, `wait` and `settle` without a permission prompt;
+   `starbridge run` still asks, since the command it wraps can be anything. For Pi, setup adds
+   these rules only when pi-permission-system is installed.
+3. When another machine of your account sent quotas in the last day, it says which and asks
+   whether to send them from this one too; Enter says no. Otherwise it finds CodexBar, or asks
+   to install it (Linux and macOS; CodexBar has no Windows build, so a Windows machine uploads
+   no quotas): with Homebrew if you have it, else CodexBar's latest release tarball from
+   GitHub, checked against the `.sha256` that release publishes, into `~/.local/opt/codexbar`.
+   It installs nothing when the checksum is missing or does not match. Then it asks which
+   providers' quotas to upload.
+4. It installs and starts the background service, `starbridge agent`, as a systemd user unit, a
+   launchd agent, or on Windows a Scheduled Task that starts at logon without administrator
+   rights and logs to `%LOCALAPPDATA%\starbridge\agent.log`.
+5. It uploads a first quota snapshot, then offers to send a test question to your phone and
    prints your answer.
 
-`--yes` takes every default and sends no test question. `--no-quota` skips step 2, CodexBar
-included; `--no-service` skips step 3; `--no-plugin` skips step 4, for every agent.
-`starbridge status` prints the same checks.
+[Permission prompts](#permission-prompts) stay in the terminal unless you turn them on with
+`starbridge config permissions on`; setup's last lines say so, with the commands that check and
+remove the setup.
+
+`--yes`, or running with no terminal, takes every default and sends no test question.
+`--no-quota` skips step 3, CodexBar included; `--no-service` skips step 4; `--no-agents` skips
+step 2. `starbridge status` prints the same checks, and names an agent installed since setup,
+which `starbridge setup --refresh` then sets up.
+
+`starbridge uninstall --agent <name>` (`claude`, `codex`, `pi` or `opencode`) removes Starbridge
+from one agent. Setup and `--refresh` then leave that agent alone, until `starbridge setup
+--agent <name>` installs it there again.
 
 ### Update and uninstall
 
@@ -89,8 +103,8 @@ app is left to them (`brew upgrade codexbar`). When a CodexBar release breaks, i
 a quota error on your devices; `starbridge update --codexbar 0.71.1` installs that release
 instead, until a later `starbridge update` moves it to the latest again.
 
-`starbridge uninstall` removes the agent service, the plugin and the binary, and asks your
-devices to revoke the machine. It deletes the keys only when you say so, or with `--purge`.
+`starbridge uninstall` removes the agent service, Starbridge from every agent and the binary,
+and asks your devices to revoke the machine. It deletes the keys only when you say so, or with `--purge`.
 
 ### Check a download
 
@@ -121,9 +135,19 @@ skill tells them when. `starbridge --help` lists every flag.
 starbridge pair
 ```
 
-It prints a code, a link and a QR code. Open the link in a browser where you are signed in, scan
-the QR code with your phone, or type the code in Settings → Devices → Add a device, on your phone
-or in the web app, which works from a machine with no browser. The code expires in 10 minutes.
+It prints a code, a link and a QR code. Scan the QR code with the Starbridge Android app or your
+phone's camera, open the link in a browser where you are signed in, or type the code in
+Settings → Devices → Add a device, on your phone or in the web app, which works from a machine
+with no browser. The code expires in 10 minutes.
+
+The QR code is a `starbridge://` link that only the Android app opens, and it carries a check
+key with which the app confirms the machine's check code by itself. Approved any other way, the machine prints its check
+code and asks whether the Android app shows the same beside it under Devices: press Enter if so, `n` if not.
+Where setup runs with no terminal, run `starbridge pair --confirm`, or `starbridge pair --reject`
+if the codes differ. A code that differs means a server read your pairing code and paired the
+machine into an account it controls ([PROTOCOL.md](../PROTOCOL.md#pairing)); the machine then
+saves nothing.
+
 The machine pairs with
 https://starbridge.run unless you pass `--server https://starbridge.example` or set
 `STARBRIDGE_SERVER`.
@@ -207,10 +231,25 @@ To upload without the service:
 starbridge quota push --provider claude --provider codex
 ```
 
+### Quiet the phone while you're here
+
+On a desktop or laptop you work at, turn on presence:
+
+```bash
+starbridge config presence on
+```
+
+While this machine's screen is unlocked and had keyboard or mouse input in the last minute,
+notifications on your other devices wait for the time set in Starbridge's Settings (30 s by
+default) and come only if the question is still open, so one you answer here doesn't buzz your
+phone. The question itself shows everywhere at once. The machine reads its lock and idle time
+itself and tells the server only yes or no. It works on macOS, Windows, and Linux under GNOME
+or X11 with `xprintidle`; a machine with no screen sends nothing.
+
 ### Permission prompts
 
-Permission prompts from Claude Code, opencode and Pi stay at the keyboard until you turn them on,
-in setup or with:
+Permission prompts from Claude Code, opencode and Pi stay at the keyboard until you turn them on
+with:
 
 ```bash
 starbridge config permissions on
@@ -250,9 +289,10 @@ Keys and state live in `~/.config/starbridge` (or `$XDG_CONFIG_HOME/starbridge`,
 `$STARBRIDGE_CONFIG_DIR`), readable only by you. `starbridge config` prints this machine's
 settings.
 
-The Claude Code plugin's hooks call `starbridge hook …`. One of them turns Claude Code's
-`AskUserQuestion` into `starbridge ask`, so the question reaches you away from the terminal; if
-the machine is not paired or the server doesn't answer, it lets the question through. The
+The Claude Code plugin's hooks call `starbridge hook …`. When Claude Code opens its
+`AskUserQuestion` picker, `starbridge hook permission` posts the question to your devices too:
+the first answer, in the picker or on a device, wins, and the other closes as answered
+elsewhere. If the machine is not paired or the server can't be reached, only the picker asks. The
 opencode plugin runs `starbridge hook question --agent opencode` on each call of opencode's
 `question` tool: it posts each question to your devices and prints the answers for opencode,
 or nothing if the terminal answers first or the server can't be reached.