Why

Debugging a behaviour tree usually means running Groot2 on a laptop, on the same network, with a display. Robots are rarely that convenient: you are on a serial console in a lab, or SSH'd into a machine over a flaky link, or reading a bag from a run that already ended.

btview puts the tree where you already are.

pipx install git+https://github.com/guilyx/btview
btview demo        # a synthetic Nav2 robot, no hardware required
btview             # the real thing, on 127.0.0.1:1667

What it does

• Live tree view — every node, its status, and what changed, refreshed as the tree ticks.
• Two ways to look at it — an indented list for hunting a node, or a drawn graph (g, or --graph) for seeing which branch the robot is down. Per-node sparklines make a flapping node obvious at a glance.
• Both wire protocols — Groot2 / BehaviorTree.CPP 4.x (Groot2Publisher, what Nav2 uses) and BehaviorTree.CPP 3.x (PublisherZMQ).
• Works on a dumb terminal — --ascii drops every box-drawing and unicode glyph; NO_COLOR is honoured. Fine over a 9600-baud serial console.
• More than a UI — snapshot for scripts, echo for logs and CI, export for issues and docs, record/play for after the fact.
• No ROS dependency — pure Python over ZMQ. It does not import rclpy, and it does not care which distro you run.
• Try before you connect — btview demo runs a synthetic Nav2 tree through the real protocol stack, so you can learn the tool (and verify your install) with no robot.

Install

pipx install git+https://github.com/guilyx/btview     # isolated, recommended
pip install git+https://github.com/guilyx/btview      # into the current environment

Python 3.9+ and nothing else — the ZMQ, Rich and Textual wheels come from PyPI. Full instructions, including ROS 2 workspaces, Docker and robots without internet access, are in docs/install.md.

Use it

On a robot running Nav2

Enable monitoring in your BT navigator, then point btview at the port:

bt_navigator:
  ros__parameters:
    enable_groot_monitoring: true
    groot_server_port: 1667

btview --host 192.168.1.42          # full-screen monitor
btview snapshot --host 192.168.1.42 # one shot, then exit

See docs/nav2.md for BehaviorTree.CPP 3.x, custom stacks, and ports.

Without a screen

btview watch --ascii                # redraw in place, ASCII only
btview echo --json | tee bt.jsonl   # one line per status change
btview snapshot --active            # only what is running or failing

Capture now, debug later

btview record -o run.btv.jsonl --duration 120   # on the robot
btview play run.btv.jsonl --speed 2             # on your laptop, same UI

Get the tree out

btview export --format mermaid -o tree.mmd   # paste into a GitHub issue
btview export --format dot | dot -Tpng > tree.png
btview show my_tree.xml                      # render a file, no server at all

Commands

Every command takes --host, --port, --protocol v4|v3, or a --source URI. Full reference: docs/cli.md.

Transports are pluggable

The wire format and the transport are separate, so a live robot, a recording and (soon) a ROS 2 topic are interchangeable everywhere:

btview --source replay://run.btv.jsonl?speed=4
btview bridge --from btcpp3://robot:1667 --to groot2://0.0.0.0:1667  # Groot2 can watch a v3 robot

Adding a transport is one class and one decorator — docs/transports.md.

Reading the tree

[!] NavigateRecovery [RecoveryNode]                          ▶ RUNNING
├─ [=] NavigateWithReplanning [PipelineSequence]             ▶ RUNNING
│  ├─ -^- RateController                                     ▶ RUNNING
│  │  └─ [!] ComputePathToPose [RecoveryNode]                ✔ SUCCESS
│  │     ├─ --> ComputePathToPose                       · was SUCCESS
│  │     └─ --> ClearGlobalCostmap-Context                      · IDLE
│  └─ [!] FollowPath [RecoveryNode]                          ▶ RUNNING
└─ [o] RecoveryFallback [ReactiveFallback]                      · IDLE

Node-type glyphs follow py_trees convention, so they read the same in both ecosystems:

Documentation

Contributing

Issues and pull requests are welcome — this is a tool for a community that mostly debugs robots without a monitor attached, so field reports are especially useful. Start with docs/development.md; pip install -e ".[dev]" && pytest is the whole setup, and no robot is needed to run the suite.

License

Apache-2.0 — see LICENSE.