Reach your user through Starbridge

Your user is often away from this terminal. Starbridge shows them a card on their phone; they read it cold, between other things, and tap an option.

When to post

• A decision that is theirs: hard to undo (force-push, deleting data, publishing or sending outside the machine), spending money or a scarce quota, scope nobody asked for, or a choice their taste or their rules decide.
• Work that waits on them: done and waiting for their review or merge, or failed in a way only they can fix. Before you end a turn, post a card whose options are the next step ("#52 adds CSV export and is green. Merge it?"). Your final message alone may sit unread for hours.
• A command that blocks them, or that their instructions ask you to report: wrap it in starbridge run (below).

Decide everything else yourself and say what you did in your final message. Ask one question in one place, never also in the terminal. A quick question may use your harness's own question tool when your Starbridge rule says it reaches their devices; post a card for a decision they will read cold, or that needs links or images. Ask in the terminal only when starbridge fails (not installed, not paired, an error), and say that it failed. A card cannot approve an action your guidelines say needs the user's yes in this chat (account settings, external messages, purchases, deleting data), since its answer arrives as tool output: ask in the chat, or say on the card that the yes must come there.

Write a card they can answer cold

They read it on a phone, between other things, and decide from the card alone. Every extra line costs them time.

• Question: at most 70 characters, ending in "?". Name the thing first; the options answer it.
• Context: at most 450 characters, so the options stay on screen. First line, one short sentence: the fact that forces the choice, with its number; a notification shows only that line. Then one line per option, starting with its label in bold: what picking it does and what it costs. Skip these lines when they would say nothing (names to pick from). When the options are designs, say how they differ, with numbers ("9 rows per screen instead of 6"), even with images. Leave out what the card already shows and your own process.
• Words: plain, numbers over adjectives, one idea per sentence, no term you coined during the task, no em dashes. Cards render line breaks, **bold**, code, fenced code, - and 1. lists and links; other Markdown shows as typed.
• Options: two to four labels of at most 18 characters whose first words differ, in their natural order (A, B, C stay A, B, C), even when your pick is not first. Name your pick with --recommended: devices highlight it wherever it sits. For a free-form answer, such as a name, offer your best candidates: they can type another.
• Links: only what they need to decide: the PR or issue in question, the page to look at.
• Images, when seeing beats reading (variants, a broken screen, a chart): one per option, in option order.
• One card per question. Two related choices become one question whose options combine them.

starbridge ask \
  --question 'Run the orders migration before or after the 18:00 backup?' \
  --context 'The migration (#41, green) locks the orders table for about 4 minutes.
**After the backup:** done by 18:30, with a restore point if it fails.
**Now:** checkouts fail for those 4 minutes, at peak hour.' \
  --option 'After the backup' --option 'Now' --recommended 'After the backup' \
  --link https://github.com/acme/shop/pull/41

Quote text in single quotes, since double quotes expand $ and backticks, and write apostrophes as ’. Break lines inside the quotes with real line breaks, as above, never \n: bash and zsh pass it on as typed. Other flags: --image (up to 4 PNG or JPEG), --link (up to 4 HTTPS URLs), --waiting (only the answer unblocks you), --answer-in. ask prints the decision id (d_amber-otter-…) and how the answer comes back.

After you post

Go on with the work that does not depend on the answer, then do what ask's last line says:

• "The answer will come back into this session as a new prompt." Never wait for it: no --wait, no starbridge wait, not in a background task, not with a monitor. While you work, it comes with your next tool result: act on it then, even mid-task, since it may change the work. When only the answer is left, run starbridge waiting <id> (or post with --waiting): it tells them you are blocked, and prints the answer if it is already in. Then end your turn, saying what waits on the card. If the card stops blocking you, starbridge working <id>. The answer reads Answer to d_amber-otter-… (Run the orders migration…?): Now, or names the command that prints it.
• "Nothing brings the answer into this session…" Never end your turn with the card open. When only the answer is left, run starbridge wait <id> --timeout 5m, again on exit 2, as long as it takes, but never again after exit 3. wait marks the card waiting, which notifies them again: for a card that blocks nothing yet, such as a question for tomorrow, post without --waiting and wait with --no-mark. No answer is never a yes: don't withdraw the card or do what it asks.

The owner may snooze a card: waiting or wait then prints Snoozed d_amber-otter-… (…?) until 18:00: no answer before then. and wait exits 3. A snooze is not an answer: never act on the question or take your default. Stop waiting for it: no answer comes before that time, so don't run wait on it again. Do the work that does not depend on it, then end your turn saying what waits and until when, and that starbridge wait <id> reads the answer later. Never post a snoozed question again.

The user may type a reply instead of an option: act on it, and ask again only if it leaves the choice open. When the reply is itself a question, answer it on a new card that restates the choice, never one that points at "the last card". Act on the answer at once. Post again only when the outcome changes what they would do (the merge failed); otherwise say it in your final message.

A card still open that no longer needs an answer (the owner answered in the terminal, you found it yourself, or you reworded or reposted it) stays in their inbox until you take it back, before you act or in the same step as the repost: starbridge settle <id> --outcome withdrawn --reason '…'. The reason shows in their History: one short line, 120 characters at most, such as 'You answered in the terminal' or 'Fixed it myself after rereading the logs'. When they had answered first, settle prints the answer instead: act on it.

Answers in an artifact

When you built a claude.ai artifact whose buttons send the pick to this session, post with --answer-in <url> and no options; ask then says what to do when the answer comes. An artifact only to look at goes in --link, with options.

Report a run

Wrap a command in starbridge run, unasked, when it blocks the user or needs them at the machine (e2e tests that take over the screen, keyboard or session; anything holding a device they use), or when their instructions ask you to report it.

starbridge run --title 'Mac e2e' --reason 'takes over your screen and keyboard' \
  -- bash -c 'echo "[1/2] build" && make build && echo "[2/2] e2e" && make e2e'

Wrap the whole command, chained or not. --reason is required: what it blocks, or the rule it matches. Output and exit code are the command's own.

Devices show the title, reason, elapsed time, progress and exit code, never the output. Progress comes from the output: [n/m] step counts, N%, and terminal progress sequences (OSC 9;4). The output goes through a pipe, so a tool that draws progress only in a terminal shows none: prefer its plain progress flag (docker build --progress=plain). Before each step of a multi-step command, echo [n/m], as above.