Skip to main content

Rosight logo

Rosight

PyPI Python Downloads CI Docs License: MIT

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 tab 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 tab
Plot — time-series and a LaserScan snapshot
Nodes tab
Nodes — enter on an endpoint jumps to it
Actions tab
Actions — goal running with live feedback
Services tab
Services — call result
Params tab
Params — s: set · y: copy as params YAML
Publish form
Publish / call / goal forms are YAML
Command palette
Command palette — completes topics and field paths
Bags tab
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 / G motions, node → topic jumps.
  • Runtime domain switch — :domain 5 reconnects on a new ROS_DOMAIN_ID without restarting; :reconnect restarts 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-ros to 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 panel
  • q or Ctrl+C — quit (asks first while a bag is recording)
  • r — rediscover the ROS graph now

Plotting workflow (the question new users ask most):

  1. Messages tab, cursor over a topic, Enter to subscribe (focus auto-jumps to the message tree)
  2. Use arrow keys / Space to expand fields in the tree
  3. Cursor on a numeric leaf (int / float), press p — the series is added and you stay in the tree, so you can add more
  4. 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 SingleThreadedExecutor thread 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)

Source distribution for rosight 0.3.0
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)

Table of built distributions (wheels) for rosight 0.3.0
File Interpreter ABI Platform Actions
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 log

Release 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 log

Security 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.

Select from 2 files

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 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