Running, success, and failure drive every tree tick
Bonsai models control logic as a tree whose nodes return Running, Success, or Failure. Sequence nodes advance when children succeed, selectors try another path after failure, and decorators change a child's result or repetition. The library also has parallel forms such as WhenAll, WhenAny, Race, and After. This vocabulary suits game characters, robot routines, simulations, and software agents where priorities and fallback paths become hard to follow in a large state machine.
The repository we measured had 99 files, about 10,142 source lines, and occupied 6 MB. Rust is the primary implementation, with a Python extension exposing the same engine through a different API. The core is available as bonsai-bt on crates.io, and Python users import a package of the same name as bonsai_bt. Its MIT license allows commercial and internal use under straightforward terms.
Determinism stops at side effects inside one tick
The concepts guide is unusually candid about parallel semantics. Bonsai remains deterministic at the tree level, but it cannot perfectly simulate simultaneous events within a single-threaded time slice. If two racers finish inside the same update interval, list order may determine which completion the tree observes first. Applications should keep the authoritative physics, clocks, or external facts outside the tree and use Bonsai to decide what action follows from them.
Actions also need to return immediately. The README says work lasting seconds or minutes should run in background threads, with status sent back through a channel. That requirement keeps traversal responsive, but Bonsai does not become an async job runner by itself. The checkout's 10,142 source lines include an async-drone example showing the pattern. Teams still own cancellation, thread failures, resource cleanup, and the boundary between a tick and an external task.
What happened when we ran it
Our sandbox installed 402 packages in 48 seconds. The build then failed with exit code 101 after 118 seconds. The linker error came from bonsai-py and said rust-lld: error: unable to find library -lpython3.11. The same tail shows the Rust core, Python package, and examples compiling in one workspace. This result describes commit acd9c81 in a fresh unprivileged container with 3 CPUs and 12 GB of RAM.
Tests failed with exit code 101 after 6 seconds for the same stated reason. The linker could not produce the bonsai-py test library without Python 3.11. No test cases ran to a pass or fail result in the supplied summary, so this is a build prerequisite finding rather than evidence of wrong behavior-tree semantics. The repository had 4 CI workflow files, no Dockerfile, and no tests directory visible to the harness.
The failure also clarifies the lowest-risk adoption path. A Rust application can start with the published core crate instead of building every workspace member. Python users can try the published wheel before compiling with maturin. Anyone changing the shared repository should install a matching Python development library and verify what the linker sees. Our 118-second build reached native linking before stopping, so simply rerunning Cargo without fixing the environment would not address the logged error.
The blackboard is one context object, not typed ports
Bonsai separates a declarative behavior from the runtime state that tracks its progress. An application supplies its own action type and context, then handles each action in a callback. That is flexible in Rust and keeps domain data outside the library. Open issue 61 points to the tradeoff: state moves through one monolithic context object instead of a decoupled blackboard with typed inputs and outputs between nodes. Large trees may need application conventions to prevent that context from becoming a grab bag.
The available node set covers many common flows, but it does not match every behavior-tree system. Issue 62 asks for an N-of-M threshold across parallel children because WhenAny is less flexible. Issue 78 requests force-result, timeout, retry, repeat, and keep-running decorators. All 3 issues remained open, so buyers should compare their required tree vocabulary with the current API instead of assuming familiar names from another library exist here.
v0.12.0 added a live view on port 8910
Release v0.12.0, published May 14, 2026, added live behavior-tree visualization. The example enables telemetry on port 8910, runs a 30-node tree, and opens a browser view that colors node status and marks the active path. Graphviz export is also documented for static diagrams. These tools are useful when a tree's declarative shape looks correct but its running state does not match what an operator sees.
GitHub recorded the last push on August 17, 2026, and issue 78 was updated on August 21. The repository had 1,042 stars and 9 combined open issues and pull requests. That is recent activity with a modest queue, though the combined count is not a defect count. The open design requests concern meaningful API gaps, while the current examples include game AI, flocking, background drone work, timeouts through racing behavior, and the live inspector.
Bonsai is worth trying when the Rust crate already has the primitives your control logic needs. Its small source tree and explicit tick model are easier to reason about than a homegrown nest of state transitions. The full workspace asks more of the machine than the core API suggests because Python linking is part of the default path we exercised. Keep the first evaluation narrow: build the Rust crate, model one real tree, and test cancellation plus side effects before expanding to Python or visualization.