Companion CLI
There is one binary: bbs. bbs setup builds it and symlinks it onto
your PATH at ~/.local/bin/bbs (brew install bbs gets you the same binary
with no checkout). Every command below is a subcommand of it — call them as
bbs <sub>. Run bbs <sub> --help for full usage.
bbs is a multicall binary: it also dispatches on argv[0], so a bbs-<name>
argv0 alias still works (bbs-config → bbs config). Those are legacy
aliases only — a checkout install ships none, and a Homebrew install ships
just two (bbs-config, bbs-env) — which is why skills and docs always use
the space form.
Every subcommand is now native Go, with retained behavior guarded by
the differential harnesses in tests/. ticket was the
last strangler: identity/verdict/session/board, the index.json state-accessors
(get/set-*/add-child/add-relation/remove-relation/ensure-size/
append-history/env), the file-only
manifest.yaml ops (init/get-manifest/set-branch), the git-mutating
base-ops (surface lease),
ensure, and path/list/reconcile. No bash remains in
production; a frozen byte-identical copy of the old script lives at
tests/fixtures/bbs-ticket.reference purely as the differential oracle.
| Command | Purpose |
|---|---|
bbs bootstrap / bbs starter check | Create a verified project from a versioned starter; report applicable releases from committed provenance without changing application files. Starter commands and update contract. |
bbs autopilot | snapshot --json reads canonical state, mode, policy and gate evidence; recover --json adds bounded artifact excerpts for recovery. checkpoint, attempt and verification persist execution state; clear, base-branch and lint-workflow support lifecycle. |
bbs ticket | Ticket-layout broker and state-probe surface. env derives SLUG/BRANCH/TICKET/BABYSIT_PROJECT_HOME through the identity ladder — BABYSIT_TICKET env → manifest.yaml cwd-match → branch regex — which is what every skill preamble evals and what autopilot resume relies on; path <kind> resolves Layout C file paths; verdict-status --skill <n> reads the latest verdict for a sub-skill (used by autopilot's Probe and Verify-post) |
bbs config | get / set / list plus workspace operations, all in ~/.babysit/config.yaml |
bbs changelog add|check|rotate | Writes a changelog without an agent reading it. add --notes <file|-> prepends a ## <version> section (refuses a version already present) and reports size; check reports it read-only; past --max-bytes (default 40000) both print rotate: suggested. rotate --keep N (default 10) moves older sections to the top of CHANGELOG-ARCHIVE.md beside it (--archive) and links it from the header. --file defaults to CHANGELOG.md. |
bbs semantic-decision | Bounded judgment step: --input <request.json> --kind <kind> routes to the current LLM by default or configured Cloudflare; --llm-answers <answers.json> records the LLM decision. Configuration and human-review policy. |
bbs team model | Prints the effective model policy as JSON; add --agent codex --complexity normal --phase-class critical to select a model/effort. Pin worker harnesses with `bbs team spawn --plan-worker |
bbs team task create|launch|show|list|done|ask|answer|abandon | The team lead worker lifecycle, owned by bbs on disk ($BABYSIT_HOME/tasks/<task>/): create stores a Task spec, launch opens a Dispatch and starts its agent through orca agent launch --surface terminal (or into --terminal) and records verified launch evidence; the worker reports once with done (a succeeded done of a project ticket snapshots its uncommitted tree for the phase, or its --artifacts for an artifact-only ticket) and asks blocking questions with ask (exit 4 = still pending, --resume <id>), which Team answers with answer. No Orca orchestration, mailbox or heartbeat. Worker lifecycle. |
bbs team integrate <parent> --phase <id> | Composes the phase's recorded snapshots (taken at each ticket's task done, plus any later edit) into one commit on local base (base itself does not move; after the phase landed, the rebuild is one fix commit against it) and checks it out detached in the phase worktree <parent>_phase-<id> (Orca's workspace dir when run in Orca, else <repo>/.babysit/worktrees/) for phase QA. Base moving since the tickets started is a plain three-way merge; a conflict is laid out with markers in that worktree (CONFLICT=, RESOLVE_IN=) — resolve it there and run integrate again to commit the resolution. |
bbs team land <parent> --phase <id> [--commit-local <message>] | Right after integrate, before any QA: fast-forwards local base to the phase commit; its worktrees stay for phase QA and fixes, and are removed when phase QA passes. If base moved since integrate, composes the phase again on the new tip (REINTEGRATED=). If a checkout of base has local edits to a file the phase changes, stops before anything moves and lists that checkout's changes (LOCAL_CHANGES=); with the human's permission, --commit-local commits them on base and lands on top. Never stashes or resets. |
bbs team next <parent> [--json] | Suggests what Team does now — publish or revise the design, bind or open a phase, dispatch, integrate, verify, land, release, complete — each with its command, or who it is waiting on. Advice derived from the same snapshot and gates the verbs enforce; it changes nothing. |
bbs contract list|pin|status|check | Interface contracts: repo files indexed in .babysit/contracts.yaml (optional owner, consumers' checks), versioned by content digest. A ticket pins what it builds against; a changed pin is reported by contract status, never a gate; integrate refuses a phase that changes a contract another team lead owns and records the changed ones for phase QA; check runs their checks. Contracts. |
bbs team readiness <parent> --action dispatch|integrate|land|release --phase <id> --json | Gates each step of a phased project: opening phase k needs phase k-1 landed; integrating, landing or releasing it needs every earlier phase released and no failed release upstream. Prints ready and reasons; a zero exit only means the read succeeded. |
bbs team release <parent> --phase <id> --request / --skip / --file receipt.json | --request publishes the phase's human release approval (never self-resolvable); on an auto phase whose base carries work outside the project it is a confirmation with a deadline (--wait, default 30m). --skip [--reason] skips an auto phase's release (not the last phase, not after a failure): it ships with a later release. --file records a release verdict (RELEASED, ROLLED_BACK, PARTIAL) after checking the released SHA contains every ticket of the phase and earlier ones. |
bbs team supervisor status|install|uninstall | The launchd/systemd unit that keeps bbs team watch alive while a batch is open; bbs team batch installs it. BBS_WATCH_SUPERVISOR=off disables it. |
bbs update | git pull + bbs setup, then refreshes installed Claude Code and Codex plugins; writes a JUST_UPGRADED marker. bbs update check is the cached probe — prints UPGRADE_AVAILABLE <old> <new> when a new release exists |
bbs secrets | Everything a skill reads to reach a running app. load (emit export KEY='…' for .babysit/.env keys not already in shell env) / seed / ensure-gitignore — project-local credential auto-loader; resolve / is-set / list-prefix / prompt — env resolution with .env.base auto-load; qa <probe|list|default-env|check|leak-check> — named-environment fields (url, start, check, flows, prepare/revert) from .babysit/qa.yaml |
bbs dashboard | Serves the dashboard + JSON API on 127.0.0.1 and opens it. The SPA is embedded in released binaries, so a brew-only install needs no checkout and no npm; a checkout's own web/dist wins when it exists. --snapshot writes web/dist/data.js and opens the file:// build instead, build rebuilds web/, --no-open for CI, --dev for vite + HMR |
CLI simplification removes these redundant entry points:
| Removed | Replacement | Reason |
|---|---|---|
bbs design (tokens, suggest, components, ux-check) | Read the project's design doc and component/token source directly. | No workflow needs the parser or generic CSV recommendations; design-ui handles project context and visual iteration. |
bbs autopilot probe, bbs autopilot explain | bbs autopilot snapshot --json | The skill already uses the canonical snapshot; the old probe initialized ticket state and maintained a second routing implementation. Mode is in data.run.mode, with policy, artifacts and gates alongside it. |
bbs autopilot context | bbs autopilot recover --json | No skill, hook or dashboard consumes the cursor/delta cache. Recovery supplies the bounded artifact view without writing a cache. |
bbs ticket get-pointer <key> | bbs ticket get pointers.<key> | Same field read through the existing dotted-path accessor. |
bbs agent resolve | Orca settings; bbs agent detect for the current harness | The resolver was already a failure-only retirement stub. |
The removed commands fail as unknown commands. Snapshot and recovery do not
choose a workflow for the model: workflow selection remains in the autopilot
skill. Existing checkpoint/attempt formats and QA/release gates are unchanged.
Legacy root aliases (env, slug, qa-config, workspace, update-check)
remain for older installed packs and the frozen differential fixtures; env
and config argv0 aliases also remain part of the Homebrew install.
