Skip to content

Development

Use the source checkout when changing BeeWeave itself.

Repository Layout

beeweave/       # Python CLI, command adapters, services, and domain helpers
  commands/     # argparse adapters and presentation, explicitly registered
  setup/        # typed setup planning and execution components
.skills/        # source skill definitions
bootstrap/      # user-project bootstrap templates
extensions/     # browser extension and assets
tests/          # pytest suite
openspec/       # proposed and active change specs
docs/           # MkDocs source documentation

CLI Architecture

The CLI follows one dependency direction:

beeweave.cli -> commanding/commands -> application services -> domain/filesystem

beeweave/cli.py only creates AppContext, parses and dispatches commands, runs lifecycle notices, and maps expected failures to exit codes. beeweave/commanding.py owns the friendly parser and stable command tree. Each module under beeweave/commands/ owns one functional command group and is listed explicitly in commands/__init__.py. argparse.Namespace must not cross that adapter boundary.

Runtime paths are resolved from immutable AppContext when main() runs. Configuration and profile rules live in configuration.py; Agent and bundled resource metadata live in catalog.py; setup orchestration uses typed SetupOptions, SetupPlan, and SetupResult through SetupService.

Human-readable commands delegate Rich and prompt construction to ui.py. Machine commands use an undecorated serializer and reserve stdout for their JSON or plain-text payload.

CLI Contract Matrix

Root help order is stable: setup, uninstall, upgrade, list, info, external, profile, illustrate, graph-query, batch-plan, graph-analyse, cache-check, cache-update, cache-hash, ast-extract. No arguments, or setup options without the setup word, route to setup. Root version flags are -V, -v, and --version.

Human-readable command contracts:

  • setup [--vault PATH] [--profile NAME] [--project [DIR]] [--agents LIST] [--no-global] [--global-extra LIST] [--no-project-local] [--copy]. Defaults: current project, default profile, deterministic non-TTY Agent defaults, symlink mode, and no optional global extras.
  • uninstall [--agents LIST] [--project [DIR]] [--no-global] [--no-project-local] [--all] [--keep-config] [-y|--yes]. Agent default is all; non-TTY execution requires --yes.
  • upgrade [--check]; info; and list (newline-delimited bundled Skill names).
  • external install SOURCE [--skill NAME] [--path PATH] [--all] [--ref REF] [--link-project PATH]; external link SKILL [--project DIR]; external list; external info SKILL; external update [SKILL]; external remove SKILL.
  • profile set-default NAME; overwriting an existing default requires exact interactive confirmation and is refused non-interactively.
  • illustrate doctor --provider PROVIDER [--project PATH] [--profile NAME] [--probe-image] [--force]; profile defaults to default.

Machine-readable command contracts:

  • graph-query VAULT QUESTION [--top 8] [--max-read 3] [--pretty].
  • batch-plan VAULT SOURCE_DIR [--max-mb 2.0] [--max-files 20] [--no-cache] [--include-code] [--pretty].
  • graph-analyse VAULT [--top 20] [--pretty].
  • cache-check VAULT SOURCES... [--pretty].
  • cache-update VAULT SOURCE [--pages [PAGE...]] and cache-hash PATH.
  • ast-extract PATH [--pretty].

JSON commands emit one JSON value plus a trailing newline. --pretty changes only whitespace. list remains newline-delimited plain text. Machine payloads never contain banners, Rich panels, summaries, or update notices. Diagnostics go to stderr.

Exit codes are 0 for success, 1 for expected domain/refusal failures, 2 for argparse errors, and 130 for keyboard interruption. User-facing errors go to stderr. Human output may differ in Rich styling, but NO_COLOR and non-TTY output must retain the same key fields without ANSI escapes.

Adding A Command

  1. Add argument registration and handler(args, context) -> int to the owning beeweave/commands/ module.
  2. Add its registrar to the ordered tuple in commands/__init__.py.
  3. Convert compound inputs to immutable options before calling application or domain code; return structured results to the adapter for presentation.
  4. Use ui.py for human output or the machine serializer for script output, then add command-contract and focused domain tests.

Do not expose new behavior by re-exporting old beeweave.cli helpers. Its undocumented constants, private functions, and handlers are internal and may change; the supported compatibility surface is the CLI and persisted formats.

Checks

Use the Makefile for the standard local quality gate:

make format
make check

The targets expand to Ruff formatting/linting, mypy type checking, and pytest:

uv run ruff format beeweave tests
uv run ruff check beeweave tests --fix
uv run ruff format --check beeweave tests
uv run ruff check beeweave tests
uv run mypy
uv run python -m pytest

For quick CLI smoke checks, also run:

uv run bwe setup --help
uv run bwe info

Tests are organized in three layers: direct domain/service unit tests, CLI contract tests through main(argv, context=...), and temporary-filesystem integration tests. Architecture tests enforce that application/domain modules do not import the CLI or presentation layers.

Local CLI Install

Install the current source checkout as the active development bwe tool:

make dev-install

This runs uv tool install --reinstall --editable <repo-root> with the repository root resolved from the Makefile location. Run bwe setup afterwards only when you need to refresh installed agent skills from the newly installed package.

Documentation

Install MkDocs tooling outside BeeWeave runtime dependencies:

uv sync --group docs

Or use pip in a documentation environment:

pip install "mkdocs-material>=9.6,<9.7"

Preview locally:

uv run --group docs mkdocs serve

Build strictly:

uv run --group docs mkdocs build --strict

The generated site/ directory is a build artifact and should not be committed to the main branch.

GitHub Pages

Documentation deploys to https://ptonlix.github.io/beeweave/. In the GitHub repository settings, Pages should use:

  • Source: Deploy from a branch
  • Branch: gh-pages
  • Folder: /root

The workflow builds from source and publishes the generated site to the gh-pages branch.

OpenSpec

Use OpenSpec changes for behavior or workflow changes:

openspec validate <change-name> --strict

Archive a change only after implementation and verification are complete.