Install & troubleshoot

For agent-assisted installation, copy the one installation prompt in the README. 2build needs both the bbs CLI and the skill pack in your coding agent. The skill pack works with Claude Code, Codex, Antigravity, OMP, Grok and any coding agent that supports Claude Code skills. Orca is not needed for Autopilot.

Installation contract for agents

1. Identify the OS/architecture and the current harness from session context. Installed executables alone do not identify the agent running this session. Target that harness, rather than installing into every agent on the machine.

2. Check command -v bbs, bbs --version and bbs install --help. Reuse a working released CLI that supports installation. If an older CLI lacks install, use bbs update for a supported install shape or replace it with a current release archive, then recheck. For a missing CLI, use Homebrew below if available, otherwise a verified release archive. Do not require Go, Node, a source checkout or Orca for a release install. Windows users should run the CLI and coding agent in WSL.

3. For Claude Code/Codex, check the harness CLI is on PATH and supports plugin commands. A desktop app alone is insufficient. If missing, report the exact prerequisite and let the user enable/install that harness's CLI; do not silently install the pack for a different agent.

4. Run bbs install claude, bbs install codex, or bbs install antigravity for those harnesses. For OMP, Grok or another compatible agent, use the compatible-agent installation path. Installation must exit successfully. If a command fails, fix a recoverable local issue and retry for that target, or report the failed command and the missing prerequisite.

5. Verify both layers before reporting installed:

   Layer	Check
   CLI	bbs --version reports a release version and bbs install --help works from the user's shell.
   Claude Code	claude plugin list --json shows bbs@babysit installed and enabled.
   Codex	codex plugin list --json shows 2build installed and enabled; do not confuse an available marketplace listing with an installed plugin.
   Antigravity	Its managed plugin has plugin.json, skills/autopilot/SKILL.md and skills/references/preamble.md in the locations below.
   OMP / Grok / other compatible agents	The agent discovers autopilot/SKILL.md and can read the sibling references/preamble.md by filesystem path.

6. Tell the user to restart the affected agent and supply its first invocation: Claude Code/Grok /bbs:autopilot, Codex $bbs:autopilot, OMP /autopilot; in Antigravity or another compatible agent, use its native skill invocation or ask it to use the installed autopilot skill. After restart, confirm that the agent can discover the skill before claiming it is loaded. Explain the first-ticket plan/prototype review → build handoff.

Completion means the CLI is runnable and the pack is installed for the intended agent. A restart still pending means installed, restart required, not a verified first run. The user's existing agent/model account supplies inference; 2build adds no separate model service requirement. Normal agent usage costs apply.

Install into your harness

bbs install                 # auto-detect Claude Code, Codex and Antigravity
bbs install claude          # Claude Code only
bbs install codex           # Codex only
bbs install antigravity     # Antigravity only

Detection checks CLI executables, Antigravity's .gemini/antigravity* directories, and Codex / Antigravity macOS apps. Leftover ~/.claude or ~/.gemini/config directories are not treated as an installed harness. Claude Code and Codex require their CLI on PATH: bbs install registers the 2build marketplace and installs bbs@babysit. The marketplace keeps its legacy ID babysit for compatibility; the source is 2found/2build. An existing marketplace is refreshed, so rerunning the command is supported. Failures name the harness and return a nonzero exit code; installation still continues for other detected harnesses. No detected harness is an error with instructions, not a silent success. Restart affected harnesses afterwards.

Antigravity receives a native skill plugin at ~/.gemini/config/plugins/bbs; when its CLI is detected, also at ~/.gemini/antigravity-cli/plugins/bbs. These are the documented Antigravity plugin locations. The installer uses the CLI checkout's skills when available; otherwise it downloads the matching release tag using Git. It preserves sibling references, workflows, scripts and data, and only replaces bundles marked as managed by bbs install. This installs skills; it does not port Claude's hooks or add Antigravity worker dispatch to Foreman.

For 2build development, go run ./cmd/bbs setup --full builds the CLI and prints the commands for registering the checkout as a local marketplace.

OMP, Grok and other compatible agents

Install the bbs CLI using Homebrew or a release archive, then load the skills through your agent's own mechanism. bbs install currently automates the three harnesses listed above; it does not install OMP or Grok.

• OMP: add the absolute path to this repository's .claude/skills directory to skills.customDirectories, preserving any existing entries. A downloaded source archive or existing plugin checkout also supplies that directory. Invoke /autopilot. See agent skill discovery for configuration details.
• Grok: run grok plugin install https://github.com/2found/2build, restart, then invoke /bbs:autopilot.
• Other agents supporting Claude Code skills: make the complete .claude/skills tree available using the agent's skill-directory configuration or native installer. Keep sibling references/, workflows, scripts and data together; copying only individual SKILL.md files loses required resources. Use the agent's native invocation or ask it to run the installed autopilot skill.

Confirm the agent discovers Autopilot and can read its shared references before starting a task. Skill compatibility does not install runtime hooks or add Foreman worker support; see hook adapters and Foreman for those capabilities.

What bbs gives you today

bbs is a multicall binary: one executable that behaves differently depending on the name it's invoked as. Most of babysit's core bins are now Go and ship inside this one binary, reachable as bbs <sub>:

Strangler note on ticket: the Go ticket command owns the identity core (resolve, verdicts, session, board), the index.json state-accessors (env, get, set-status, set-phase, set-parent, set-sibling, set-pointer, ensure-size, append-history), the file-only manifest.yaml ops (init, get-manifest, set-branch), the base-ops family (refresh, surface, serve, land), ensure, and path/list/reconcile. bbs ticket is now entirely self-contained in the binary — a brew-only install runs every subcommand without the skill pack.

Note on dashboard: released binaries carry the built SPA inside them (internal/webui, staged by scripts/build-webui.sh in goreleaser's before-hooks), so bbs dashboard on a brew-only install serves the real dashboard with no checkout and no npm. A checkout's own web/dist takes precedence when it exists, so bbs dashboard build still does what it always did. --snapshot needs real files next to index.html, so it unpacks the embedded copy into ~/.babysit/cache/dashboard and writes data.js there.

Note on design: the design command itself is Go (ships in the binary), but its CSV/DESIGN.md data files live in the skill pack, so a brew-only bbs design suggest needs --data <dir> pointed at a skill-pack checkout.

The release binary contains the CLI. bbs install supplies the skill pack (skills, workflows, DESIGN.md/CSV data) through each harness's plugin system.

bbs --version (or -v) prints the version. A release binary reports the tag it was built from, injected at build time; a clone install has no injected value and reads VERSION from the checkout instead, so it stays accurate after a git pull without a rebuild. unknown means neither source was available.

macOS — Homebrew (primary)

brew tap 2found/2build https://github.com/2found/2build
brew install 2found/2build/bbs
bbs install

The explicit tap URL is required because the repository is 2found/2build rather than the conventional homebrew-2build name. The fully qualified formula selects this tap's package. See Homebrew's tap documentation.

Verify:

bbs --help          # babysit CLI
bbs --version       # installed CLI version

Upgrade / uninstall:

bbs update
brew uninstall bbs

bbs update follows the running binary: a checkout is pulled and rebuilt; a Homebrew installation is upgraded with brew upgrade bbs. When running from a checkout, it also checks brew list --versions bbs and upgrades that copy if present. A failed Homebrew upgrade returns a failure instead of claiming the entire update succeeded. Other standalone binary copies must be replaced manually. Use type -a bbs to inspect PATH precedence.

Release archives (macOS or Linux)

Homebrew works on macOS and Linux. Without it, download the archive for your OS and architecture plus checksums.txt from the same release. Use the platform matrix below to choose the archive. Verify its SHA-256 with sha256sum on Linux or shasum -a 256 on macOS against the matching row in checksums.txt before extracting. Keep the published filename so it matches that row. Do not install an archive with a missing or mismatched checksum.

After verification, extract bbs and install it:

mkdir -p ~/.local/bin
install -m 0755 bbs ~/.local/bin/bbs
export PATH="$HOME/.local/bin:$PATH"
bbs --version
bbs install

Add the PATH entry to your shell's startup file if it is missing, then verify bbs --version in a new shell. The bbs-config / bbs-env compatibility aliases are optional; current skills call bbs <subcommand> directly.

Troubleshooting the first install

For a source/development install, use go run ./cmd/bbs setup --full in a checkout, then run the local marketplace registration commands it prints.

Platform matrix

Released artifacts (no Windows — see below):

Windows: bbs is cross-compiled for Windows in CI purely as a regression check (so a change that breaks the Windows build fails a PR). No Windows artifact is published. The runtime hooks are compiled into bbs (bbs hooks pre-tool-gate / bbs hooks session-writer), so they run on any OS with no bash or jq on PATH. For native PowerShell/cmd, the skill pack ships .claude/skills/references/preamble.ps1 (the shared preamble — same state-echo contract as the bash block) and bbs setup (the installer — go run ./cmd/bbs setup from a checkout); skill bodies still assume a POSIX commands, so Git-Bash/WSL remains the fully supported path.

How the aliases work

bbs inspects argv[0]: the alias bbs-config runs the config subcommand, and the alias bbs-env runs the env resolver that now also answers to bbs secrets resolve. The Homebrew formula installs the real binary once and adds bbs-config / bbs-env as symlinks to it — so the bbs-* names work exactly like the in-repo dev symlinks, without a separate build per bin.

env and qa-config are still reachable as top-level commands, but hidden from bbs --help: they moved under secrets, and the old spellings stay only so a brew-updated binary keeps working for a skill pack that hasn't upgraded yet. New callers should use bbs secrets ….

For maintainers: cutting a release

Changing VERSION and pushing to main triggers the release pipeline.

1. Bump VERSION, both fields in .claude-plugin/marketplace.json (metadata.version, plugins[0].version) and .codex-plugin/plugin.json (version) — the 4-field rule in CLAUDE.md.
2. Push the approved version change to main. The workflow creates its tag inside the release job; a manual v* tag remains a supported alternative.
3. .github/workflows/release.yml validates all four versions, builds the four archives plus checksums, commits the real checksums into Formula/bbs.rb, then publishes the GitHub Release.

Validate the pipeline locally without tagging:

goreleaser check                       # config is valid
goreleaser build --snapshot --clean    # 4 binaries
brew style Formula/bbs.rb              # formula lint