muesli-bt is a compact Lisp-authored Behaviour Tree runtime for robotics, with bounded-time planning, cancellable asynchronous jobs, and canonical event logs.
muesli-bt combines task-level Behaviour Tree (BT) execution, bounded-time planning, cancellable asynchronous jobs, and canonical event logs in one runtime contract.
It is intended for task-level robot control where decisions must be inspectable, replayable, and robust to planner or model latency. It is not a hard real-time servo controller and does not replace ROS2, Nav2, MoveIt, or robot drivers.
muslisp is the executable. muesli-bt is the runtime and project.
Robotics task logic often needs more than a plain BT tick:
- planner work must respect tick budgets;
- model or VLA jobs can return late and need cancellation;
- execution traces must be good enough for debugging, conformance, and external evaluation;
- simulator and ROS2 backends should not redefine the BT semantics.
muesli-bt keeps these concerns explicit through the Lisp BT DSL, the runtime contract, and the canonical mbt.evt.v1 event stream.
- Lisp-authored Behaviour Trees with explicit tick semantics.
- Bounded-time planning inside ticks.
- Cancellable async/VLA jobs.
- Canonical event logs and replay/conformance tooling.
Use muesli-bt if you need task-level robot control where:
- Behaviour Tree logic should remain editable and inspectable;
- planners or model calls must respect tick budgets;
- async jobs must be cancellable and replayable;
- execution traces matter for debugging, evaluation, or audit.
Do not use it for:
- hard real-time servo control;
- replacing ROS2, Nav2, MoveIt, or robot drivers;
- hiding arbitrary Python/C++ code behind opaque BT leaves;
- production VLA control without a host-side validation layer.
Status vocabulary used in this repository:
released: documented, tested, and part of the supported release surface.experimental: implemented but not yet stable enough for strong external dependence.contract-only: documented boundary or schema, but not yet a complete executable implementation.planned: roadmap item, not released functionality.
| Area | Status | Where to start |
|---|---|---|
| Core Lisp runtime | released | language syntax |
| Behaviour Trees | released | BT introduction |
| Bounded planning | released | planning overview |
| Canonical event logs | released | event log |
| Conformance L0/L1/L2 | released | conformance levels |
| PyBullet/Webots examples | released | examples overview |
| ROS2 thin transport | released | ROS2 tutorial |
| Async cancellation lifecycle | released | event log |
| Lisp DSL round-trip and hash evidence | experimental | why Lisp as DSL? |
| Generated-fragment rejection fixtures | experimental | why Lisp as DSL? |
| Host capability bundles | contract-only | host capability bundles |
cap.echo.v1 registry smoke path |
released | cap.call |
| VLA lifecycle hooks and stubs | experimental | VLA integration |
| Production VLA providers | planned | roadmap to 1.0 |
| Nav2/MoveIt adapters | planned | roadmap to 1.0 |
In the diagram, arrows show the primary runtime data/control flow. Two-headed arrows mean the runtime sends a request and later observes result, state, or acknowledgement.
muesli-bt runs task-level BT logic in a compact Lisp runtime. Host backends provide robot or simulator IO. Long-running planners and model calls are submitted, polled, cancelled, and logged through the runtime contract. Each run can emit canonical mbt.evt.v1 traces for replay and inspection.
Small canonical event-log excerpt:
{"schema":"mbt.evt.v1","type":"tick_begin","tick":1}
{"schema":"mbt.evt.v1","type":"node_exit","tick":1,"data":{"node_id":1,"status":"running"}}
{"schema":"mbt.evt.v1","type":"tick_end","tick":1,"data":{"root_status":"running"}}Core runtime path:
cmake --preset dev
cmake --build --preset dev -j
./build/dev/muslisp examples/bt/hello_bt.lisp
./scripts/setup-python-env.sh
make verify-installmake verify-install writes and validates logs/verify-install.mbt.evt.v1.jsonl.
For the shortest walkthrough, use first 10 minutes. For fuller setup options, use getting started.
- Hello BT: smallest BT with a visible
runningtosuccesstransition. - Runtime contract in practice: run, log, validate, and inspect canonical events.
- PyBullet e-puck-style goal seeking: first simulator-backed flagship path.
- New users: choose your path, what is muesli-bt, feature inventory, first 10 minutes.
- BT users: BT introduction, BT syntax, why not just BehaviorTree.CPP?.
- Robot and simulator integration: integration overview, env API, ROS2 tutorial.
- Tool builders and reviewers: runtime contract v1, conformance levels, evidence index.
- Limits and roadmap: known limitations, roadmap to 1.0, release notes.
Benchmark numbers are reported for curated evidence bundles. The README links to the current harness and interpretation, but ad hoc local runs are not treated as release evidence.
ROS2 support is a thin host integration layer. The released baseline is Humble-focused and keeps the core transport surface intentionally narrow: nav_msgs/msg/Odometry in, geometry_msgs/msg/Twist out, canonical logs through mbt.evt.v1.
Start with the ROS2 tutorial, then read ROS2 backend scope and host capability bundles. Nav2 and MoveIt adapters are roadmap work unless a release note says otherwise.
VLA/model support is currently experimental lifecycle infrastructure: submit, poll, cancel, timeout handling, BT node semantics, and canonical logging. Production provider transport, credentials, and safety validation are planned work behind host-side capability layers unless a concrete backend is documented and tested in release notes.
See VLA integration, VLA nodes, and known limitations.
If you use muesli-bt, cite the repository version you used. Citation metadata is provided in CITATION.cff.
Contributions should keep code, docs, tests, and event-contract evidence aligned. Start with CONTRIBUTING.md, the docs style guide, and the support policy.