Rosight
Rosight = ROS + sight. A keyboard-driven terminal cockpit for ROS 2.
Browse the live ROS 2 graph — messages, nodes, services, actions, parameters, TF, bags, interfaces — and live-plot any numeric field, all from one screen without a mouse. Built for SSH, tmux, robot consoles.
📖 Docs: https://deyuf.github.io/rosight/
Messages — subscribed topics with Hz / bandwidth / trend; the message tree highlights values as they change
What's inside
Nine tabs, keyboard-driven, all on one screen:
# |
Tab | What you can do |
|---|---|---|
1 |
Messages | Fuzzy-filter the topic table (● marks subscribed topics; Hz, bandwidth and an Hz trend sparkline per topic). Enter subscribes, x unsubscribes. The message tree highlights values as they change; / searches fields, y / Y copy a path / value. Space pauses and [ / ] step through the last 100 messages. P publishes from a YAML form, i shows publisher QoS, v previews Image / CompressedImage topics. |
2 |
Nodes | Every node with its publishers, subscribers and service endpoints as a tree — Enter on an entry jumps to that topic or service. |
3 |
Services | c calls a service from a YAML request form (pre-filled, remembers your last request) and shows the response. |
4 |
Actions | g sends a goal from a YAML form with live feedback and final status / result; x cancels. |
5 |
Params | Per-node parameters. s sets a value (type-checked, arrays included), y copies all of them as a ROS 2 params file. |
6 |
Plot | Multi-series live plot — scalar time-series and 1D-array snapshots (e.g. LaserScan ranges). Add fields with p / Enter in the message tree without leaving it. Pause, window scaling, CSV export. |
7 |
TF | Auto-built frame tree from /tf and /tf_static. |
8 |
Bags | ros2 bag record / play / info. Recorders are stopped gracefully (bag finalized) and never outlive the app. |
9 |
Interfaces | Browse msg / srv / action definitions of every interface package on the system. |
Image rendering uses the terminal's native graphics protocol when available (kitty / sixel / iTerm2) and falls back to Unicode half-blocks otherwise — see docs/plotting.md for the support matrix.
Screenshots
Plot — time-series and a LaserScan snapshot |
Nodes — enter on an endpoint jumps to it |
Actions — goal running with live feedback |
Services — call result |
Params — s: set · y: copy as params YAML |
Publish / call / goal forms are YAML |
Command palette — completes topics and field paths |
Bags — recording state |
Cross-cutting features:
- Auto-QoS — the subscriber profile is negotiated to match every publisher (BEST_EFFORT vs RELIABLE, TRANSIENT_LOCAL, …), so sensor topics "just work". If a publisher is still incompatible, the topic says so (
QoS!) instead of silently showing 0 Hz. - Cheap on busy graphs — subscriptions receive raw bytes and decode only what is on screen; the graph is discovered once per second on a background thread, never on the UI loop.
- Remembers your session — theme, last tab, filters, plot series and command history are restored on the next start (
state.toml, next to your config). - Fast navigation — fuzzy filters everywhere,
:palette with completion and history,j/k/g/Gmotions, node → topic jumps. - Runtime domain switch —
:domain 5reconnects on a newROS_DOMAIN_IDwithout restarting;:reconnectrestarts the backend if its executor ever stops (the status bar turns red). - No ROS required for the UI — the package imports cleanly without
rclpy, so you can dev / unit-test on cloud machines. Run with--no-rosto stay offline.
Install
From PyPI:
pip install rosight
Then, in any terminal where you want to use it:
source /opt/ros/<distro>/setup.bash
rosight
If you maintain multiple distros, source the one whose rclpy should drive
discovery before launching. See the
installation guide for the
recommended --system-site-packages venv layout that keeps the system rclpy
reachable while pip manages everything else.
From source (for development):
git clone https://github.com/deyuf/rosight
cd rosight
pip install -e ".[dev]"
Quick start
# launch (inherits ROS_DOMAIN_ID from env)
rosight
# pick a domain explicitly + log to file
rosight --domain-id 5 --log-file /tmp/rosight.log
# UI-only mode, no rclpy needed (great for theme / layout dev)
rosight --no-ros
Inside the app:
?— keyboard reference overlay:— command palette with completion (topic <filter>,plot <topic> <field>,node <name>,param <node>,unsub <topic|all>,domain <N>,reconnect,quit)1–9— jump to a tab/— fuzzy-filter the current panelqorCtrl+C— quit (asks first while a bag is recording)r— rediscover the ROS graph now
Plotting workflow (the question new users ask most):
- Messages tab, cursor over a topic, Enter to subscribe (focus auto-jumps to the message tree)
- Use arrow keys / Space to expand fields in the tree
- Cursor on a numeric leaf (int / float), press p — the series is added and you stay in the tree, so you can add more
- Press 6 for the Plot tab (or type
:plot /odom twist.twist.linear.x, which adds and opens it)
Documentation
Full docs site: https://deyuf.github.io/rosight/
| Topic | Page |
|---|---|
| Installation per distro | Install |
| Daily usage | Usage |
| Keybindings | Keybindings |
| Configuration | Configuration |
| Plotting deep-dive | Plotting |
| Architecture | Architecture |
| Contributing | Development |
| FAQ | FAQ |
Project layout
src/rosight/
├── app.py # Textual App, panel registry, global keys, palette commands, state
├── cli.py # argparse entry point
├── config.py # TOML config loader + state.toml persistence
├── ros/
│ ├── backend.py # rclpy facade: lifecycle, raw subscriptions, publish,
│ │ # services, parameters, action goals, executor health
│ ├── discovery.py # GraphMonitor thread + GraphSnapshot
│ ├── introspection.py # dynamic message-type resolution, field walking
│ ├── yaml_msg.py # message <-> YAML for the forms
│ ├── qos.py # plain-data QoS + auto-negotiation
│ └── stats.py # hz / bw monitors
├── utils/
│ ├── datatable.py # incremental table sync + last-column auto-fit
│ ├── fuzzy.py # fuzzy filter
│ ├── ringbuffer.py # thread-safe bounded buffers
│ ├── path.py # message field-path parser
│ └── formatting.py # display helpers, sparklines
└── widgets/ # one file per panel, GraphListPanel base (_base.py),
# message tree, YAML form, palette, help, status bar
Tech stack & rationale — short version
- Python 3.10 (ROS 2 Humble) or 3.12 (Jazzy / Kilted) + rclpy (first-class ROS 2 client, dynamic message introspection via
rosidl_runtime_py) - Textual (modern async TUI, CSS-like styling, headless pilot tests — that's how a 350-test suite stays meaningful for a TUI)
- plotext 5 for ANSI plotting in the Plot tab
- hatch + ruff + mypy + pytest-asyncio for the dev loop
- MkDocs Material for the docs site
- rclpy runs on its own
SingleThreadedExecutorthread with raw-bytes subscriptions, and graph discovery has a thread of its own, so the Textual loop never waits on DDS. See the architecture page for the full reasoning.
Status
Beta. Discovery, subscription, plotting, publish, service calls, action goals, parameter editing, TF, bag record / play, state persistence and runtime domain switch all work, tested headless and against real rclpy on Humble and Jazzy in CI.
License
MIT. See LICENSE.
Metadata
Release files for rosight 0.3.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| rosight-0.3.0.tar.gz | 1.1 MB | With provenance | Details for rosight-0.3.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| rosight-0.3.0-py3-none-any.whl | Python 3 | none | any | Details for rosight-0.3.0-py3-none-any.whl |
Total release size: 1.2 MB
Release files / rosight-0.3.0.tar.gz
| Download URL | rosight-0.3.0.tar.gz |
|---|---|
| Size | 1.1 MB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
28ee54cd98430067ffbfcf46edc68ca1a95bb61b43282c30a77420849d67d49d
|
|
BLAKE2b-256 checksum How to use checksums |
7431d71a530264686cefb4d7e99776a73244891f65a671608b56227233e3bd8b
|
| 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 12, 2026.
Transparency logRelease files / rosight-0.3.0-py3-none-any.whl
| Download URL | rosight-0.3.0-py3-none-any.whl |
|---|---|
| Size | 104.2 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
d0b0074a5de442fe746def4836daa10f2b98ab0971ecb1b4d11d07df32b1615c
|
|
BLAKE2b-256 checksum How to use checksums |
6896fc3d9c47a182899c30c9fd6d9269dc6fb19e1603b115403ffb8cf4e81413
|
| 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 12, 2026.
Transparency logSecurity for rosight 0.3.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.
Attestation for rosight-0.3.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 12, 2026.
Transparency logA 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.