Bee - Task Pipeline Orchestration

Bee is a task pipeline orchestration tool written in Rust. It lets you define tasks, connect them into pipelines with automatic dependency resolution, and run them in parallel or sequentially.

Building

Bee requires Rust (stable). Build with Cargo:

cargo build          # debug build
cargo build --release  # release build
cargo test           # run tests

The binary is at target/debug/bee or target/release/bee.

The git commit hash of the source is embedded at build time. Show the installed version:

bee version

This prints the git rev-parse HEAD hash recorded when the binary was built/installed (e.g. by bee update).

Update project documentation

bee init also writes bee/README.md, bee/AGENTS.md, and bee/CLAUDE.md inside each project. Regenerate them from the built-in templates with:

bee docs update

Project Initialization

Initialize bee in the current directory:

bee init

This creates the full directory structure and starter files:

bee/
├── tasks/
│   ├── build.yml        # starter build task
│   └── test.yml         # starter test task
├── pipelines/
│   └── main.yml         # default pipeline (build -> test)
├── rules/               # (empty)
├── cache/               # trigger states and task run history
├── logs/                # per-task execution logs (<task>.log)
├── deps/                # installed dependencies
├── system/
│   ├── config.yml       # master registry of all tasks/pipelines/rules
│   ├── init             # initialization proof (hash)
│   ├── hash/
│   │   ├── init         # SHA-256 of init file
│   │   └── config       # SHA-256 of config.yml
│   └── backup/          # configuration snapshots
├── deps.yml             # external dependency definitions
├── README.md            # this file
└── .gitignore           # ignores cache/deps/backup/hash

Subsystems

Bee detects when you run bee init inside an already-initialized bee project and proposes creating a subsystem — a lightweight, self-contained bee instance scoped to the current folder.

Creating a subsystem

bee init

Bee walks up the directory tree, finds the nearest valid parent bee system, and asks:

Detected a parent bee system at '/path/to/parent'.
Create a subsystem of it in this directory? [Y/n]

Y (default) — creates a lightweight subsystem:
- own bee/tasks/, bee/pipelines/, bee/rules/ — works independently
- minimal bee/system/ (init, config.yml, hashes)
- bee/system/parent — relative pointer back to the parent system
- registers itself in the parent's bee/system/subsystems.yml
n — creates a normal, fully independent bee project.

Flags:

bee init --yes          # auto-accept subsystem creation (no prompt)
bee init --name auth    # override subsystem name (default: current directory name)

Subsystem commands

Within a subsystem the basic commands operate on the subsystem's own resources: bee task, bee pipeline, bee rule, bee run, bee status, bee subsystem. bee install, bee backup, and bee graph are not available in a subsystem.

bee subsystem list    # in a subsystem: shows the parent + sibling subsystems (marks current)
                      # in a parent: lists registered subsystems
bee subsystem status  # shows the link to the parent system and registration details

Task connections (parent ↔ subsystem)

A parent task can invoke a task or pipeline inside a subsystem, and tasks on either side can react to each other through trigger rules.

Parent calls a child task or pipeline:

bee subsystem run <subsystem> task <task>
bee subsystem run <subsystem> pipeline <pipeline>

Run it from a parent task's run command to chain systems, e.g.:

name: build-all
run: bee subsystem run auth task build && bee subsystem run payments pipeline build

Parent reacts to a subsystem — create a rule in the parent with one of:

bee rule modify on-child --trigger-type subtask_completed --trigger-param subsystem=auth --trigger-param task=build
bee rule modify on-child --trigger-type subtask_failed    --trigger-param subsystem=auth --trigger-param task=build
bee rule modify on-child --trigger-type subtask_changed   --trigger-param subsystem=auth --trigger-param task=build
bee rule modify on-child --trigger-type subsystem_changed --trigger-param subsystem=auth

Subsystem reacts to the parent — create a rule inside the subsystem:

bee rule modify after-parent --trigger-type parent_task_completed --trigger-param task=deploy
bee rule modify after-parent --trigger-type parent_task_failed    --trigger-param task=deploy

The state of each task lives in the owning system's bee/cache/triggers/, so subtask_*/subsystem_changed read the subsystem's cache from the parent, and parent_task_* reads the parent's cache from the subsystem.

Parent registry

The parent system stores bee/system/subsystems.yml (name, path, date, hash) and a tamper-detection hash in bee/system/hash/subsystems. The file is created on demand, so existing projects work without changes.

Directory Structure

Directory	Purpose
`tasks/`	Task definitions (YAML). Each file defines a single task with a shell command and optional dependencies.
`pipelines/`	Pipeline definitions (YAML). Each file lists tasks to run in order, respecting the dependency DAG.
`rules/`	Trigger rules (YAML). Defines when tasks should run based on file changes, git state, other tasks, etc.
`cache/`	Runtime cache data. Stores trigger states and task execution history.
`logs/`	Task execution logs. Each task writes its stdout/stderr to `bee/logs/<task>.log` instead of the console.
`deps/`	Installed dependencies. Tools and libraries fetched by `bee install`.
`system/`	Internal metadata. Config registry, integrity hashes, and backup storage.
`system/hash/`	Tamper-detection hashes for config and init files.
`system/backup/`	Backup snapshots of tasks, pipelines, and rules.
`deps.yml`	Project dependencies — define external tools to install with `bee install`.

Key Files

system/config.yml — Master registry of all tasks, pipelines, and rules. Auto-managed by bee task/pipeline/rule create/delete. Do not edit manually.
deps.yml — Dependency definitions (URL, git, or package manager).
README.md — This file.

Managing Tasks

Create a task

bee task create <name>

Creates bee/tasks/<name>.yml with a default echo command.

List tasks

bee task list

Run a task

bee task run <name>

Runs the task directly, bypassing pipeline ordering. The trigger system still checks whether the task should execute.

Delete a task

bee task delete <name>

Task YAML format

name: compile
run: gcc -o main main.c && echo "Compiled!"
depends_on:
  - setup

Field	Type	Description
`name`	string	Task name (must match filename)
`run`	string	Shell command to execute
`depends_on`	list[string]	Optional list of task names this task depends on

Tasks without depends_on or with an empty list have no dependencies and run first.

Managing Pipelines

Create a pipeline

bee pipeline create <name> [-t <task>...] [-p <pipeline>...]

Flag	Description
`-t <task>`	Add a task to the pipeline (repeatable)
`-p <pipeline>`	Add a subpipeline to invoke (repeatable)

List pipelines

bee pipeline list

Run a pipeline

bee pipeline run <name>

Runs the full pipeline. The system automatically:

Runs all subpipelines first (in order), recursively with cycle detection
Builds a dependency graph (DAG) from task depends_on fields
Performs topological sort
Groups tasks into layers (parallel groups)
Runs layers sequentially, tasks within a layer run in parallel (separate threads)

Subpipelines

A pipeline can invoke other pipelines. When you run it, all subpipelines run first (in the order listed), then the pipeline's own tasks run through the normal DAG:

name: full
tasks:
  - package
  - deploy
pipelines:
  - build
  - test

bee pipeline create build -t compile
bee pipeline create full -t package -p build
bee pipeline run full

Subpipelines run recursively (a subpipeline can itself have subpipelines). Cycles are detected automatically, e.g. build -> ci -> build.

Run all pipelines

bee run

Delete a pipeline

bee pipeline delete <name>

Pipeline YAML format

name: ci
tasks:
  - compile
  - test
  - lint
  - package
  - deploy
pipelines:
  - build        # optional subpipelines, run before this pipeline's tasks

Field	Type	Description
`name`	string	Pipeline name
`tasks`	list[string]	List of task names (order doesn't matter — DAG sorts them)
`pipelines`	list[string]	Optional list of subpipelines invoked before this pipeline's tasks

Managing Rules

Create a rule

bee rule create <name> --task <task>

Creates a manual rule (only runs when explicitly requested).

List rules

bee rule list

Delete a rule

bee rule delete <name>

Rule YAML format

name: rebuild-on-source
task: compile
triggers:
  - type: file_change
    paths:
      - src/**/*.c
      - src/**/*.h

Dependency Management

Bee can manage external dependencies (tools, libraries).

List dependencies

bee install list

Add a dependency

bee install add <name> --dep-type <type> --source <source> [--version <ver>] [--command <cmd>]

Dependency types:

package — system package (requires --command, e.g. sudo apt-get install -y)
url — download from URL (archive)
git — clone a git repository

Install all dependencies

bee install run

Remove a dependency

bee install remove <name>

deps.yml format

dependencies:
  - name: jq
    type: package
    source: jq
    command: "sudo apt-get install -y"
  - name: shellcheck
    type: url
    source: https://github.com/koalaman/shellcheck/releases/download/v0.9.0/shellcheck-v0.9.0.linux.x86_64.tar.xz
    version: v0.9.0

Dependency Graph Visualization

All pipelines

bee graph all [format]

Specific pipeline

bee graph pipeline <name> [format]

Formats:

tree (default) — text tree
dot — GraphViz DOT
mermaid — Mermaid diagram

Example (tree):

Pipeline: ci (5 tasks, 3 groups)
  [1/3] compile (parallel)
  [2/3] test, lint (parallel)
  [3/3] package
  [4/3] deploy

Example (mermaid):

graph LR;
  compile-->test;
  compile-->lint;
  test-->package;
  lint-->package;
  package-->deploy;

Backup System

Create a backup

bee backup create

Copies current tasks, pipelines, rules, and config to bee/system/backup/<hash>. Automatically cleans old backups (max 20).

List backups

bee backup list

Restore a backup

bee backup restore <hash>

Cache Management

bee clean

Removes the entire bee/cache/ directory, resetting all trigger states and run history.

Task Logs

When a task runs, its output is not printed to the console (task outputs would interleave across parallel threads). Instead, every task writes its stdout/stderr to a log file:

bee/logs/<taskname>.log

The log file is overwritten on each run. On failure the log contains the exit code, stderr, and any stdout produced. The console only shows the task status lines (running, FAILED, SKIPPED, etc.).

cat bee/logs/compile.log   # inspect what the compile task output

bee clean does not remove bee/logs/ — delete log files manually if you want to clear them.

Project Status

bee status

Displays:

Number of pipelines, tasks, and rules
Pipeline details (task order + cached/pending status)
Count of cached tasks

YAML File Formats

config.yml (system/config.yml)

Master registry — automatically updated by bee task/pipeline/rule create/delete:

tasks:
  - compile
  - test
  - lint
pipelines:
  - ci
  - build-only
rules:
  - compile
  - test

WARNING: Do not edit this file manually. Bee manages it automatically through commands.

Trigger System

Rules define when tasks should run. Without a rule, a task runs every time.

Available trigger types

Trigger	Description	Parameters
`manual`	Only on explicit request	—
`always`	Always run	—
`file_change`	Run when matching files change	`paths` — list of globs
`git_changed`	Run when git-tracked files change	`paths` — list of globs
`task_completed`	Run when another task succeeds	`task` — task name
`task_failed`	Run when another task fails	`task` — task name
`dependency_changed`	Run when upstream task changes	`task` — task name
`env_changed`	Run when environment variables change	`vars` — list of var names
`dependency_missing`	Run when a file/binary is missing	`path` — file path
`checksum_changed`	Run when file checksums change	`paths` — list of globs
`schedule`	Run on a cron schedule	`cron` — cron expression
`git_tag`	Run on git tags	`pattern` — optional pattern
`subtask_completed`	Run when a task in a subsystem succeeds	`subsystem`, `task`
`subtask_failed`	Run when a task in a subsystem fails	`subsystem`, `task`
`subtask_changed`	Run when a task in a subsystem changes state	`subsystem`, `task`
`parent_task_completed`	Run when a task in the parent system succeeds (in a subsystem)	`task`
`parent_task_failed`	Run when a task in the parent system fails (in a subsystem)	`task`
`subsystem_changed`	Run when any task state in a subsystem changes	`subsystem`

Examples

# Auto-compile when sources change
name: auto-compile
task: compile
triggers:
  - type: file_change
    paths:
      - src/**/*.rs

# Run test after compile succeeds
name: test-after-compile
task: test
triggers:
  - type: task_completed
    task: compile

# Deploy only manually
name: manual-deploy
task: deploy
triggers:
  - type: manual

# Retry deploy when package fails
name: retry-deploy
task: deploy
triggers:
  - type: task_failed
    task: package
  - type: manual

# Build when binary is missing
name: build-if-missing
task: compile
triggers:
  - type: dependency_missing
    path: target/release/myapp

How triggers work

When bee task run <name> is called, the system checks all rules assigned to that task
If no rules exist → task always runs
If rules exist → any trigger returning true causes the task to run
The manual trigger never returns true automatically
Trigger states are cached in bee/cache/triggers/
bee clean resets all trigger states

Full Configuration Example

1. Initialize

bee init

2. Create tasks

bee task create compile
bee task create test
bee task create lint
bee task create package
bee task create deploy

3. Edit task files

bee/tasks/compile.yml:

name: compile
run: cargo build --release
depends_on: []

bee/tasks/test.yml:

name: test
run: cargo test
depends_on:
  - compile

bee/tasks/lint.yml:

name: lint
run: cargo clippy -- -D warnings
depends_on:
  - compile

bee/tasks/package.yml:

name: package
run: tar -czf release.tar.gz target/release/myapp
depends_on:
  - test
  - lint

bee/tasks/deploy.yml:

name: deploy
run: scp release.tar.gz user@server:/opt/app/
depends_on:
  - package

4. Create a pipeline

bee pipeline create ci

bee/pipelines/ci.yml:

name: ci
tasks:
  - compile
  - test
  - lint
  - package
  - deploy

5. Create rules

bee/rules/auto-compile.yml:

name: auto-compile
task: compile
triggers:
  - type: file_change
    paths:
      - src/**/*.rs

6. Run

bee pipeline run ci    # Run the full pipeline
bee task run deploy    # Run a single task
bee graph pipeline ci  # Show dependency graph
bee status             # Show project status

Integrity Security

Bee stores SHA-256 hashes:

bee/system/init — initialization proof
bee/system/hash/init — hash of init file
bee/system/hash/config — hash of config.yml
bee/system/hash/deps — hash of deps.yml
bee/system/hash/subsystems — hash of the parent's subsystems registry

Each bee/system/hash/<file> entry has a companion bee/system/hash/<file>.bee containing the bee git hash (bee version) that created it, so future versions can tell which bee build produced each hash.

The system verifies integrity on every operation. If hashes don't match, bee returns "run bee init first".

Name		Name	Last commit message	Last commit date
Latest commit History 35 Commits
src		src
.gitignore		.gitignore
Cargo.lock		Cargo.lock
Cargo.toml		Cargo.toml
LICENSE		LICENSE
README.md		README.md
build.rs		build.rs
rust-toolchain.toml		rust-toolchain.toml

Folders and files

Latest commit

History

Repository files navigation