The Problem

top and similar tools give you a table of processes but no sense of how system metrics change over time. tiptop solves that by combining live system stats with terminal-rendered graphs, so you can see CPU, memory, disk, and network activity trending in real time without leaving the terminal.

What This Does

tiptop is a command-line system monitor built on Python. It uses psutil to fetch system data and Textual for terminal layout. The core rendering logic lives in src/tiptop/braille_stream.py and src/tiptop/blockchar_stream.py, which convert numeric values into Braille and block-character graphs respectively.

The application is organized into per-resource modules: _cpu.py, _mem.py, _disk.py, _net.py, _battery.py, _procs_list.py, and _info.py. Each module defines a Textual widget that collects data, renders a panel, and handles resize events. The _app.py file wires everything together and defines the run() entry point.

How It Is Wired

Execution starts at run() in src/tiptop/_app.py:33. This is the only entry point and it is called by nothing else in the repo. run() boots the TiptopApp Textual application. From there, control flows into each widget's on_mount handler, which triggers collect_data and refresh_panel methods.

The most connected module is src/tiptop/_app, which imports 7 modules and has an instability score of 0.88. braille_stream is the most depended-upon module (6 importers) and is a stable leaf with no dependencies. The add_value function is called from 9 places, making it the highest-blast-radius change point in the codebase.

The wiring has not been mapped for effects outside the process — there is no database, network service, or filesystem interaction beyond reading system metrics. The app is self-contained and exits after rendering.

Here is the file-by-file map:

  • _app.py — application bootstrap and run() entry point
  • _cpu.py — CPU model detection, temperature reading, and graph rendering
  • _mem.py — memory usage table and graph
  • _disk.py — disk usage and I/O counters
  • _net.py — network interface selection and throughput graphs
  • _battery.py — battery percentage and charge graph
  • _procs_list.py — process table
  • _info.py — system info line (uptime, hostname)
  • braille_stream.py / blockchar_stream.py — graph rendering primitives
  • _helpers.py — sizeof_fmt for human-readable byte formatting

How To Use It

Setup: Install with pip from the project root:

pip install .

The project uses pyproject.toml for packaging and dependencies.

Configuration: No environment variables or config files are required. The --net flag lets you specify a network interface manually; otherwise it auto-selects.

Running it:

tiptop

Options: --version, --log LOG, --net NET.

Real-World Use

tiptop fits where you need a quick visual check of system health during a debugging session. For example, when investigating a memory leak, run tiptop alongside your application and watch the memory graph trend upward. The Braille graphs give you a denser history than top or htop in the same vertical space.

Code Health & Issues

Static analysis found 4 findings (0 high, 3 medium, 1 low):

  • Medium — Broad exception handling in src/tiptop/_cpu.py and src/tiptop/_disk.py. Bare except clauses swallow errors indiscriminately. Catch specific exceptions instead.
  • Medium — Duplicated code blocks across _cpu.py, _procs_list.py, _disk.py, and _net.py. Eight repeated 6-line blocks. Extract shared helpers.
  • Low — 3 TODO/FIXME markers in src/tiptop/_cpu.py. Triage into issues or resolve.

Beyond the measured findings, the CI workflow has several supply-chain issues: third-party GitHub Actions are pinned to tags rather than commit SHAs (High), there is no lockfile for reproducible builds (High), GITHUB_TOKEN permissions are not declared (Medium), no dependency vulnerability scan runs on pull requests (Medium), and persist-credentials is not disabled on checkout (Medium). Tests exist in tests/test_streams.py but cover only the stream rendering, not the system data collection.

The Bottom Line

tiptop is a well-structured terminal monitoring tool with clean separation between data collection and rendering. The Braille graph approach is genuinely useful and the codebase is small enough to modify confidently. The main risks are the unpinned CI actions and missing lockfile — both are quick fixes for someone adopting this repo. It is a solid choice if you want a top alternative with trend visualization and are comfortable with Python.