Skip to main content

Beehave

The small branch that matters.
Beehave reads a robot behavior tree (BehaviorTree.CPP v3 or v4, or py_trees) and shows only the actions your robot can take, in order, with the conditions that lead to each one.

CI Docs Python 3.10+ License: Apache-2.0 Status: alpha


Not the Godot addon. This Beehave is a static analysis tool for robot behavior trees written for BehaviorTree.CPP or py_trees (ROS 2, Nav2: drones, mobile robots, manipulators). It is unrelated to the Beehave addon for the Godot game engine.

Why

A behavior tree decides what a robot does next, and the file that holds it is written for the executor, not for people. What happens when a step fails is spread over fallbacks, decorators, reactive nodes, subtrees in other files or ROS packages, and blackboard remapping. To answer "what does the robot do if this step fails halfway through the task?", whether it flies, drives or grasps, you tick the tree in your head. So does every reviewer, every time.

The tools around behavior trees answer other questions:

  • editors and monitors (Groot, Groot2) show the tree as written, or as it runs on a robot;
  • renderers (py-trees-render, Nav2's bt2img.py) draw the parent/child structure;
  • model checkers (BehaVerify and others) need the tree rewritten in their own language first.

Beehave reads the file you ship, with nothing built and no robot running, and answers three questions at a glance:

  • Which actions exist in this tree?
  • What has to be true for each one to run?
  • What runs next on success, and what runs next on failure?

The prior art survey compares the existing tools in detail.

What it does

A 22-node drone mission in, a 10-action graph out. Control nodes become arrows, conditions become arrow labels, subtrees are inlined, retries become notes.

$ beehave graph examples/aerial/drone_mission.xml -f mermaid
---
config:
  theme: base
  themeVariables:
    edgeLabelBackground: "#f5f0e9"
    lineColor: "#1b1813"
---
%% Beehave action graph: DroneMission (btcpp-v3)
flowchart TD
    start(("START"))
    a1["LandNow"]
    a2["Arm"]
    a3["TakeOff"]
    a4["FlyToWaypoint<br/><small>retry ×3</small>"]
    a5["CaptureImage"]
    a6["FlyHome"]
    a7["FindLandingSpot"]
    a8["FlyToLandingSpot"]
    a9["Land"]
    a10["Disarm"]
    success(["SUCCESS"])
    failure(["FAILURE"])
    start -->|"IsBatteryCritical"| a1
    start -->|"not IsBatteryCritical"| a2
    a1 -->|"success"| success
    a1 -.->|"failure"| a2
    a2 -->|"success"| a3
    a2 -.->|"failure"| failure
    a3 -->|"success and IsBatteryOK"| a4
    a3 -->|"success and not IsBatteryOK"| a6
    a3 -.->|"failure"| failure
    a4 -->|"success"| a5
    a4 -.->|"failure"| a6
    a5 -->|"success"| a6
    a5 -.->|"failure"| a6
    a6 -->|"success"| a9
    a6 -.->|"failure"| a7
    a7 -->|"success"| a8
    a7 -.->|"failure"| failure
    a8 -->|"success"| a9
    a8 -.->|"failure"| failure
    a9 -->|"success"| a10
    a9 -.->|"failure"| failure
    a10 -->|"success"| success
    a10 -.->|"failure"| failure
    classDef start fill:#1b1813,stroke:#1b1813,stroke-width:1.5px,color:#f5f0e9
    classDef action fill:#fdfbf9,stroke:#1b1813,stroke-width:1.5px,color:#1b1813
    classDef success fill:#107550,stroke:#fdfbf9,stroke-width:2px,color:#fdfbf9
    classDef failure fill:#b93917,stroke:#fdfbf9,stroke-width:2px,color:#fdfbf9
    class start start
    class a1,a2,a3,a4,a5,a6,a7,a8,a9,a10 action
    class success success
    class failure failure
    linkStyle 0,1 stroke:#1b1813,stroke-width:1.75px
    linkStyle 2,4,6,7,9,11,13,15,17,19,21 stroke:#107550,stroke-width:1.75px
    linkStyle 3,5,8,10,12,14,16,18,20,22 stroke:#b93917,stroke-width:1.75px,stroke-dasharray:7 4

"What if the emergency landing fails?" now takes one arrow to answer, and the answer is a gap: LandNow fails over to Arm, so the drone would start the mission again.

The same works for any robot. The examples/ folder has three generic trees:

Example Robot Tree → graph
Drone survey mission Multirotor 22 nodes → 10 actions
Navigate to a goal, with recovery and docking Mobile base 23 nodes → 11 actions
Pick and place Arm and gripper 24 nodes → 13 actions

Each one is also written in BehaviorTree.CPP v4 (*_v4.xml) and in py_trees (*.py), and every version gives the same graph. The one exception is instructive: py_trees has no IfThenElse, and the usual py_trees way to write the mobile robot's "charge or navigate" lets a failed dock fall through to navigation. Beehave shows it as three extra arrows.

Where it helps

Reviewing a change

An XML diff shows which tags moved, not what the robot now does. Removing the ForceSuccess around the drone's survey is a two-line change that looks like a clean-up:

         <TakeOff altitude="{cruise_altitude}"/>
-        <ForceSuccess>
           <Sequence name="survey">
             ...
           </Sequence>
-        </ForceSuccess>
         <SubTreePlus ID="ReturnToLaunch" __autoremap="true"/>

The graph diff shows what it changes:

-TakeOff --[success and not IsBatteryOK]--> FlyHome
+TakeOff --[success and not IsBatteryOK]--> FAILURE
-FlyToWaypoint --[failure]--> FlyHome
+FlyToWaypoint --[failure]--> FAILURE
-CaptureImage --[failure]--> FlyHome
+CaptureImage --[failure]--> FAILURE

When the battery is low after take-off, or the survey fails, the drone no longer flies home: the tree ends in FAILURE with the drone in the air. Commit the text graph next to the tree and this diff shows up in the pull request, where reviewers already look.

Safety and failure reviews

Every failure transition is listed, with the conditions that lead to it. A hazard review (an FMEA, a test-flight briefing) can walk them one by one instead of rebuilding them from the XML. That is how the LandNow gap above shows up. Safety engineers, test pilots and operators can read the graph without reading the XML.

A CI check that needs no robot

No ROS install, no C++ build, no plugins. Beehave exits with an error when the XML is malformed or a subtree cannot be found, across files, <include>s and ROS packages. Committed graphs fail CI when the tree changes and the graph was not updated (how).

Migrations

Moving from BT.CPP v3 to v4 (as Nav2 did between Humble and Jazzy), or porting a tree between BT.CPP and py_trees: the same tree must give the same graph, so comparing the two graphs checks the port. Beehave's own tests hold its examples and public BT.CPP v3/v4 pairs to that rule.

Diagrams that stay true

Mermaid output renders on GitHub, GitLab and most docs sites. Generate the diagram from the tree and it cannot drift from what the robot runs.

Input for other tools

-f json gives every action with its ports and source line, every transition with a structured guard, and every warning. Build a test plan from it (one simulation scenario per failure transition), check a naming rule, or feed an operator UI.

What it is not

  • Not an editor or a runtime monitor. Groot2 does that.
  • Not a proof. The graph shows what the tree can do; temporal-logic checks are an optional later phase.
  • Not exact everywhere yet. Reactive nodes, loops and Parallel are approximated, and every approximation is printed as a warning.

Install

$ pip install beehave-bt                # or: uv tool install beehave-bt
$ pip install 'beehave-bt[py-trees]'    # to read py_trees trees too

The PyPI package is beehave-bt; the command and the module are beehave. Python 3.10+ (ROS 2 Humble and newer). Under ROS 2, skip the extra and use the py_trees of your distribution.

Use

$ beehave graph mission.xml                       # transitions as text
$ beehave graph mission.xml -f mermaid -o mission.mmd
$ beehave graph mission.xml -f dot | dot -Tsvg > mission.svg
$ beehave graph mission.xml -f json               # for other tools
$ beehave stats mission.xml                       # size, reduction, breakage
$ beehave trees mission.xml                       # list the trees
$ beehave graph behavior_trees/ -t NavigateToPose  # every tree in a folder
$ beehave graph --py-trees robot.trees:create_root  # a py_trees tree

BT.CPP v3 and v4 files are told apart automatically. Subtrees are inlined wherever they live: in the same file, in an <include>, in a ROS package (ros_pkg), or in a folder of trees registered from code. --py-trees imports your module and calls the function, so it runs that code: only point it at code you would run yourself.

import beehave

result = beehave.analyze("mission.xml")
print(beehave.to_mermaid(result.graph))
print(result.stats.reduction)

Custom nodes are actions unless the XML or a small beehave.yaml says they are conditions:

conditions: [BatteryOK, IsEmergency]

Status

Beehave moves along eight tracks, in six milestones (roadmap).

Phases — what the graph says:

Phase What Status
1. Action graph Parse, flatten subtrees, walk, render done, readability gate open
2. Guards and metrics Simplified guards, exact Reactive/Retry/Parallel, gap report planned (M3)
3. Operator view Operator labels, phase view, JSON for ground-control UIs, live status planned (M5)
4a. Graph safety rules Safety rules checked on the graph, with witness paths planned (M4)
4b. Model checking Temporal-logic rules through BehaVerify optional (M6)

Formats — what Beehave reads:

Format Status
BehaviorTree.CPP v3 supported
BehaviorTree.CPP v4 supported, including SKIPPED and pre-conditions
py_trees (2.2 and newer) supported
Nav2 presets, per ROS distro planned (M1, M3)
Groot2 projects, AutoAPMS, BehaviorTree.ROS2 planned (M1, M3)
State machines (YASMIN, SMACH…) later (M6)

Checks against the graph — six more tracks:

Track What it adds Starts in
Foundations Runtime IDs that match BT.CPP's, a graph hash, a JSON Schema M1
Integrations SARIF, GitHub annotations and Action, pre-commit, MCP server, ros2 beehave M1
Quality beehave lint, a quality report, beehave diff, grading generated trees M1
Safety An evidence manifest, graph safety rules, FMEA and assurance-case exports M1
Runs Read BT.CPP logs and Nav2 bags: timelines, edge coverage, conformance M2
Tests Coverage criteria, beehave plan, mock files for BT.CPP and py_trees M2

Nodes Beehave cannot model exactly yet (reactive nodes, loops, Parallel, unknown custom nodes) are approximated and always reported, never silently. See the node support table.

Learn more

Contributing

Contributions are welcome: bug reports with a minimal tree, new node rules, docs. We work test-first, and every walk rule is checked against a reference interpreter with property-based tests. Start with CONTRIBUTING.md and the good first issues.

Please follow the Code of Conduct. Report security issues privately, as described in SECURITY.md.

License

Apache-2.0. The brand (logo, palette, type, graph style) is documented in .branding/; its assets have their own license. If you use Beehave in research, see CITATION.cff.

Metadata

Release files for beehave-bt 0.4.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for beehave-bt 0.4.0
File Size Uploaded Provenance Actions
beehave_bt-0.4.0.tar.gz 78.2 kB With provenance Details for beehave_bt-0.4.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for beehave-bt 0.4.0
File Interpreter ABI Platform Actions
beehave_bt-0.4.0-py3-none-any.whl Python 3 none any Details for beehave_bt-0.4.0-py3-none-any.whl

Total release size: 165.2 kB

Release files / beehave_bt-0.4.0.tar.gz

Download URL beehave_bt-0.4.0.tar.gz
Size 78.2 kB
Tags Source
SHA-256 checksum
How to use checksums
e0cd292d9c178eb809f6d20a75628289a64ece9ee0acf4f9a7c558c4fbf23924
BLAKE2b-256 checksum
How to use checksums
a4c06ac0d66016f5613e5c9ea9a7cf7b84f9a9c3301a2f7baceb25614b5126e3
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 13, 2026.

Transparency log

Release files / beehave_bt-0.4.0-py3-none-any.whl

Download URL beehave_bt-0.4.0-py3-none-any.whl
Size 87.0 kB
Tags Python 3
SHA-256 checksum
How to use checksums
2490d6398bf434e5da1a87132562c63cf3f20c64a6f054ad32ed60e4fd746533
BLAKE2b-256 checksum
How to use checksums
7473fb4dec7b51d0f094d660232894d09d19585f1889cbfde6d347d5279c112b
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 13, 2026.

Transparency log

Security for beehave-bt 0.4.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for beehave_bt-0.4.0.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 13, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page