Skip to main content

Development Guide

This guide covers the development workflow, building, testing, and contributing to BranchBox.

Build with plain Cargo. CI uses an ordinary dependency cache; the mbx experiment is withdrawn. See Rust build caching for the current policy and historical benchmark evidence.

Measure readiness by verified user outcomes and end-to-end workflows. Keep Rust line coverage as a diagnostic, and record the scope and limitations of each test layer.

Development Environment Setup​

This project includes a complete devcontainer setup that provides a consistent development environment.

Prerequisites:

  • Docker Desktop or Docker Engine
  • VS Code with Remote - Containers extension, or
  • Cursor (has built-in devcontainer support)

Steps:

  1. Clone the repository:

    git clone https://github.com/branchbox/branchbox.git
    cd branchbox

  2. Open in devcontainer:

    • VS Code/Cursor: Command Palette → "Reopen in Container"
    • CLI: devcontainer up --workspace-folder .

Pre-built images:

The devcontainer uses a pre-built image from GHCR by default (ghcr.io/branchbox/branchbox/devcontainer:latest), which speeds up startup significantly. The image is automatically rebuilt and pushed when .devcontainer/ files change on main.

  • Default behavior: Pull pre-built image if not present locally, fall back to local build if unavailable
  • Force latest: Set DEVCONTAINER_PULL_POLICY=always in .env to always pull the latest image
  • Force local build: Set DEVCONTAINER_PULL_POLICY=build in .env to always build locally
  • Custom image: Set DEVCONTAINER_IMAGE=your-image:tag in .env to use a different image
  1. Inside the container: 
    # Build the core library
    cd core
    cargo build

    # Run tests
    cargo test

    # Check documentation
    cargo doc --open

Tooling baked into the devcontainer:

  • Rust stable toolchain with cargo-watch, cargo-edit, and cargo-expand
  • Node.js 20 plus the @openai/codex and @anthropic-ai/claude-code CLIs via ghcr.io/rbarazi/devcontainer-features/ai-npm-packages
  • Docker-in-Docker runtime (official Docker packages) for container orchestration tests
  • Persistent Codex configuration/history stored on the host at .codex/

Devcontainer sync strategy:

  • By default BranchBox copies the .devcontainer/ directory into each feature worktree.
  • Override behaviour per command with BRANCHBOX_DEVCONTAINER_STRATEGY=copy|symlink branchbox feature start.
  • Persist a different default by setting BRANCHBOX_DEVCONTAINER_STRATEGY in your .env (template comment provided in generated env.sample files).
  • Refresh existing worktrees whenever the main .devcontainer/ changes: branchbox devcontainer sync [--dry-run] [--strategy copy|symlink].
  • On feature start --reuse, copy mode compares the worktree against its last BranchBox sync baseline. The safe default refuses divergence. Choose --devcontainer-reuse preserve to keep feature-local edits, overwrite to replace them deliberately, or inspect to print the exact diff command without changing files. The decision is recorded in the feature registry.

Module Architecture Notes​

  • Devcontainer provisioning is handled by DevcontainerModule, one of the composable modules executed during feature start.
  • The module copies or symlinks files from the main .devcontainer/ directory, excluding .env, and prunes stale artifacts during sync.
  • branchbox devcontainer sync reuses the module to propagate updates to all active feature worktrees, respecting the same strategy logic.

Devcontainer Smoke Test Playgrounds​

  • Run ./scripts/setup-sample-workspaces.sh to copy tracked templates from test/workspaces/templates/ into the git-ignored test/workspaces/local/. Each template declares its stack via template.json, so the script prints the correct branchbox init --stack <stack> command.
  • The repository currently ships rust-cli and node-api samples; add more templates as needed for other stacks.
  • Example flow: 
    ./scripts/setup-sample-workspaces.sh node-api
    cd test/workspaces/local/node-api
    BRANCHBOX_SKIP_HOST_VALIDATION=1 branchbox init --stack nodejs
    branchbox feature start devcontainer-smoke
  • Open both the main sample and generated feature worktree in VS Code/Cursor to confirm devcontainer propagation, shared credential mounts, and module telemetry.
  • After testing, clean up with branchbox feature teardown devcontainer-smoke --complete-spec and simply delete test/workspaces/local/ if you want a fresh slate.

Feature Start UX & Fast Path Modes​

  • branchbox feature start ships with a muscle-memory alias: branchbox feature new. Both commands accept the same flags.
  • Minimal mode (--minimal, with hidden alias --fast) skips the devcontainer, compose, and specs modules by default for lightweight edits—no preview flag required. Other modules and policy-enforced setup can still run; inspect the summary rather than assuming nothing was provisioned.
  • --default-prompt drops in the built-in BranchBox seed for minimal starts so agents have immediate context. Use --prompt "seed text" when you want to provide your own (still capped at 2,000 characters and annotated with the prompt-bridge flag).
  • --json mirrors the entire summary (checklist, module table, warnings, prompt seed, timestamps) as structured JSON; pair it with --no-summary if you only want machine-readable output.
branchbox feature new backlog-quick-fix \
  --minimal \
  --default-prompt \
  --json
  • Set BRANCHBOX_DEFAULT_AGENT_CMD (optionally with BRANCHBOX_DEFAULT_AGENT_NAME) to auto-launch your preferred coding agent after the devcontainer module finishes. Minimal starts record that state in the checklist so you know whether it will run immediately or is waiting for branchbox devcontainer sync.

Start Summary Cheat Sheet​

  • Text mode now prints 🚀 Feature workspace ready (<mode>) followed by a checklist table (Step, Result, Details) that calls out the worktree, branch, adapter, URLs, .env, prompt seed, module health, skipped modules, and default agent plan.
  • A dedicated module table still lists every module with status (success, skipped, failed), duration, notes, and a forced marker for policy-required runs.
  • Separate “Skipped modules” and “Warnings” sections provide reasoning and remediation; minimal runs end with a reminder to finish provisioning via branchbox devcontainer sync.

Listing Features​

  • branchbox feature list now surfaces Mode, Prompt, and Modules columns so you can gauge module health at a glance (e.g., 3 ok / 1 skip).
  • branchbox feature list --json returns the same data structure captured in .branchbox/registry.json, including start_mode, prompt_seed, and each module outcome, so dashboards and agents stay in sync without re-running feature start.

Local Development (without devcontainer)​

Prerequisites:

  • Rust 1.75+ (Install Rust)
  • Git
  • Docker (optional, for testing Docker operations)

Setup:

# Clone repository
git clone https://github.com/branchbox/branchbox.git
cd branchbox

# Build core library
cd core
cargo build

# Run tests
cargo test

# Install development tools
cargo install cargo-watch cargo-edit cargo-expand

Building​

# Build all workspace members
cargo build

# Build with release optimizations
cargo build --release

# Build specific package
cargo build --package worktree-core

Testing​

# Run all tests
cargo test

# Run with output
cargo test -- --nocapture

# Run specific test
cargo test naming

# Run doctests
cargo test --doc

# Watch mode (requires cargo-watch)
cargo watch -x test

Install Script Tests​

The install script has automated tests. See test/README.md for details.

# Run tests
bats test/install.bats         # All tests
shellcheck install.sh          # Linting

# Test on specific distro
docker run -it --rm -v $(pwd)/install.sh:/install.sh:ro ubuntu:22.04 bash /install.sh

Coverage: Static analysis (shellcheck) + automated tests (bats) + CI (GitHub Actions)

Mac App​

The Mac app lives in macos/, a Swift package with no third-party dependencies. It needs macOS 26 and Xcode 26 or later (Swift 6.2). Linux devcontainers cannot build it: the Apple SDKs only ship with macOS.

cd macos
swift build --build-tests -Xswiftc -warnings-as-errors   # what CI runs
swift test --parallel
swift run BranchBox                                       # unbundled dev build
  • swift run BranchBox runs without notifications and uses separate "BranchBox Dev" settings and storage. Test a branch-built CLI with BRANCHBOX_CLI_PATH="$PWD/../target/debug/branchbox" swift run BranchBox.
  • Debug builds can run without any CLI on a fake backend: BRANCHBOX_BACKEND=preview BRANCHBOX_PREVIEW_SCENARIO=showcase swift run BranchBox.
  • scripts/macos-dev.sh wraps a debug build as macos/build/dev/BranchBox Dev.app and runs it with logs in your terminal; --open launches it like Finder does, which reproduces the minimal PATH a released app sees.
  • Integration tests against a real CLI run only when asked: BRANCHBOX_IT=1 BRANCHBOX_IT_CLI="$PWD/target/debug/branchbox" swift test --package-path macos --filter BranchBoxIntegrationTests.
  • Package with scripts/package-macos-app.sh (universal, ad-hoc signed; --zip for an archive).
  • Before a PR that touches the app or the CLI's JSON output, run the Mac App ↔ CLI Loop at the end of the CLI end-to-end test.

The app reads the CLI's --json output, so changes to payloads must follow the JSON contract: only add keys, keep error codes stable, and regenerate the golden fixtures with UPDATE_CONTRACT_FIXTURES=1. See macos/README.md for the target layout and CI jobs, and the Mac app user guide for supported controls and runtime limits. Preview-backend screens use sample data and do not validate real CLI behavior.

Code Quality​

# Format code
cargo fmt

# Run Clippy (linter)
cargo clippy

# Check without building
cargo check

Documentation​

The documentation website is built using Docusaurus. The devcontainer ships with Node.js 20.

# Navigate to the docs directory
cd docs

# Install dependencies
npm install

# Start the local development server
npm start

# Build the static site for production
npm run build

# Generate and open Rust API docs
cargo doc --open

# Generate API docs without opening
cargo doc --no-deps

When updating CLI commands, regenerate docs/docs/reference/cli.md from the --help output of branchbox and every subcommand. When a --json payload or error code changes, update docs/docs/reference/json-contract.md too. docs/docs/reference/configuration.md is generated: run UPDATE_CONFIG_REFERENCE=1 cargo test -p worktree-core config_edit.

Project Structure​

branchbox/
├── .devcontainer/          # Dev container configuration (meta!)
│   ├── devcontainer.json   # VS Code devcontainer config
│   ├── compose.yaml        # Docker Compose setup
│   └── Dockerfile          # Rust development image
├── core/                   # Core Rust library
│   ├── src/
│   │   ├── naming.rs       # Feature name generation
│   │   ├── validation.rs   # Environment validation
│   │   ├── adapters/       # Stack adapters (Rails, Node.js)
│   │   ├── modules/        # Feature modules (tunnel, database)
│   │   └── bootstrap/      # Self-bootstrapping system (meta!)
│   └── Cargo.toml
├── agent/                  # Local agent daemon (Milestones 1-2)
├── cli/                    # CLI tool
├── macos/                  # BranchBox for Mac (Swift package, drives the CLI)
├── docs/                   # Documentation
├── .env.sample             # Environment variable template
├── .gitignore
├── Cargo.toml              # Workspace configuration
└── README.md

Contributing​

  1. Fork the repository
  2. Create a feature branch
  3. Make your changes
  4. Run tests: cargo test --all (Rust) or ./test/run-tests.sh (install script)
  5. Submit a pull request

Commit Guidelines​

Use conventional commit format:

  • feat(modules): add docker compose planner
  • fix(cli): correct feature name validation
  • refactor(adapters): simplify rails detection
  • docs(readme): update installation guide
  • test(core): add naming edge cases

Code Review Checklist​

Before submitting a PR:

  • Run cargo fmt --all -- --check
  • Run cargo clippy --all-targets --all-features -- -D warnings
  • Run cargo test --all-features
  • Run cargo doc --no-deps (check for doc warnings)
  • Update relevant documentation
  • Add tests for new functionality
  • Rebase on latest main

Architecture Documentation​

For detailed architecture information, see:

Development Status​

Current Progress:

  • Architecture design
  • Protocol specification
  • Core library implementation (Milestone 0)
  • CLI implementation (Milestone 0)
  • Agent implementation (Milestone 1 — daemon + CLI IPC on macOS/Linux/devcontainers)
  • Mac app (native SwiftUI front end for the CLI's --json contract; agent backend later)