narsil 0.2.0

A terminal-based system resource monitor — GPU-aware, Braille charts, per-char label inversion
narsil-0.2.0 is not a library.

A terminal-based system resource monitor written in Rust — fast, readable, and GPU-aware.

Named after the reforged sword of Aragorn, narsil is built to be sharper than the tools that came before it. It targets developers and power users who live in the terminal and need real-time system insight without leaving it.

Platform support — narsil runs on Linux, Windows, and macOS. The GPU tab (AMD/NVIDIA) is Linux-only for now; all other tabs work on every supported OS.

📸 Screenshot

narsil screenshot

✨ Features

Current scope (v0.1)

Tab What you see Platform
🗺️ Overview CPU gauge, RAM gauge, live RX/TX sparklines, top processes (fills available height) all
🧠 CPU Global usage history chart (Braille), per-core gauges with colour-coded load all
💾 Memory RAM + Swap history charts, GiB usage gauges all
🌐 Network Combined RX/TX history chart, per-direction current throughput all
💿 Disks Per-partition usage bars at fixed height, scrollable when partitions exceed the terminal all
🔬 Processes Process table sorted by CPU, scrollable, fills available height all
🎮 GPU Per-GPU cards with utilisation + VRAM history charts, gauges, temperature and power draw Linux only

🔑 Key behaviours

  • 🎨 Split-colour gauges — the percentage label rendered inside every gauge automatically inverts its colour character-by-character at the fill boundary so it is always readable, even when the bar is exactly at 50%.
  • 📜 Scroll indicators — any panel that cannot display all items at once shows ▲/▼/▲▼ in its title.
  • 📐 Dynamic sizing — all panels adapt to the current terminal dimensions; no hard-coded row counts.
  • ⚡ Configurable refresh rate — pass --interval <ms> on startup (default 1 000 ms) to tune between low-latency and low-CPU usage; key events are processed between ticks with zero busy-waiting.
  • ⌨️ Keyboard-first navigation: Tab / Shift+Tab wrap-around tab switching; 1–6 direct jump (1–7 on Linux); j/k or arrow keys for scrolling; q or Ctrl-C to quit.
  • 💬 Status bar — persistent one-line keybinding reference at the bottom, context-aware per tab.

🚀 Installation

Prerequisites

  • Linux, Windows 10+, or macOS 12+
  • GPU tab requires Linux with standard /sys mounts and amdgpu (AMD) or NVIDIA proprietary drivers
  • Rust toolchain ≥ 1.85 — needed only for cargo install or source builds (rustup update stable)

Official release channels

Channel Platforms Standard NVIDIA variant
crates.io all cargo install narsil cargo install narsil --features nvidia
AUR Arch Linux narsil · narsil-bin narsil-nvidia · narsil-nvidia-bin
AppImage Linux x86_64 narsil-{ver}-x86_64.AppImage narsil-nvidia-{ver}-x86_64.AppImage
Windows zip Windows x86_64 narsil-{ver}-x86_64-windows.zip narsil-nvidia-{ver}-x86_64-windows.zip
Linux tarball Linux x86_64 narsil-{ver}-x86_64.tar.gz narsil-nvidia-{ver}-x86_64.tar.gz
Source all cargo build --release cargo build --release --features nvidia

AppImage, Windows zip, and Linux tarball are attached to every GitHub release.

crates.io

cargo install narsil                      # standard
cargo install narsil --features nvidia    # with NVIDIA GPU support (Linux only)

AUR (Arch Linux)

Four packages are published to the AUR:

Package Type Description
narsil source standard, compiled from the crates.io source tarball
narsil-nvidia source like narsil but built with --features nvidia
narsil-bin binary standard, installs prebuilt tarball from GitHub Releases
narsil-nvidia-bin binary NVIDIA variant, installs prebuilt tarball from GitHub Releases 
yay -S narsil              # standard, built from source
yay -S narsil-nvidia       # with NVIDIA GPU support, built from source
yay -S narsil-bin          # standard, prebuilt binary
yay -S narsil-nvidia-bin   # with NVIDIA GPU support, prebuilt binary

AppImage (Linux x86_64)

Download from the latest GitHub release, make executable and run:

chmod +x narsil-*-x86_64.AppImage
./narsil-*-x86_64.AppImage

Two variants per release: narsil-{version}-x86_64.AppImage (standard) and narsil-nvidia-{version}-x86_64.AppImage (with NVIDIA support).

Windows (x86_64)

Download narsil-{version}-x86_64-windows.zip or narsil-nvidia-{version}-x86_64-windows.zip from the latest GitHub release, extract, and run narsil.exe in PowerShell or cmd.

The GPU tab is not compiled into the Windows build.

Linux tarball (x86_64)

Download from the latest GitHub release:

tar xzf narsil-{version}-x86_64.tar.gz
./narsil-{version}/narsil

Both standard and NVIDIA variants are available.

Build from source

git clone https://github.com/Pommersche92/narsil
cd narsil
cargo build --release
./target/release/narsil        # Linux / macOS
.\target\release\narsil.exe    # Windows

# With NVIDIA GPU support (Linux only):
cargo build --release --features nvidia

🎮 GPU support matrix

GPU monitoring is Linux-only. On Windows and macOS the GPU tab is not compiled in; all other tabs work normally.

Vendor Driver Detected Utilisation Memory Temperature Power
🔴 AMD discrete amdgpu ✅ ✅ gpu_busy_percent ✅ VRAM ✅ hwmon ✅ hwmon
🔴 AMD iGPU (APU) amdgpu ✅ ✅ ⚠️ GTT (shared RAM) ✅ ✅
🟢 NVIDIA proprietary + --features nvidia ✅ ✅ NVML ✅ NVML ✅ NVML ✅ NVML
🔵 Intel iGPU i915 / xe ❌ — — — —
🔵 Intel Arc discrete xe ❌ — — — —

⚠️ AMD APU note: the VRAM figures reflect GTT memory (system RAM dynamically assigned to the GPU), not dedicated video memory. The values are accurate but on-screen labels will stay as "VRAM" until the display is updated in a future release.

🗓️ Intel note: Intel GPU support is planned — see Roadmap below.

⌨️ Keybindings

Key Action Platform
Tab / Shift+Tab Next / previous tab (wraps around) all
1 – 6 Jump directly to tab all
7 Jump to GPU tab Linux only
→ / l Next tab all
← / h Previous tab all
↓ / j Scroll down (Disks, Processes; + GPU on Linux) all
↑ / k Scroll up all
q / Ctrl-C Quit all

🏗️ Architecture

src/
├── main.rs               — terminal setup, raw-mode lifecycle, event + tick loop
├── app.rs                — App state dispatcher: calls each metrics::refresh on every tick
├── metrics/
│   ├── mod.rs            — HISTORY_LEN constant, push_history helper, re-exports
│   ├── cpu.rs            — CpuState, per-core + global history
│   ├── memory.rs         — MemState, RAM + swap
│   ├── network.rs        — NetState, RX/TX rates and history
│   ├── disks.rs          — DiskState, per-partition usage
│   ├── processes.rs      — ProcessEntry, top-100 by CPU
│   └── gpu/
│       ├── mod.rs        — GpuEntry, vendor dispatch
│       ├── amd.rs        — sysfs-based AMD metrics
│       └── nvidia.rs     — NVML-based NVIDIA metrics (feature-gated)
└── ui/
    ├── mod.rs            — draw() entry point
    ├── helpers.rs        — format_bytes, usage_color, scroll_indicator
    ├── statusbar.rs      — persistent keybinding bar
    ├── tab_bar.rs        — tab header row
    ├── widgets/
    │   └── split_gauge.rs — SplitGauge custom widget
    └── tabs/
        ├── overview.rs   — combined overview tab
        ├── cpu.rs
        ├── memory.rs
        ├── network.rs
        ├── disks.rs
        ├── processes.rs
        └── gpu.rs

Data flows in one direction:

app.on_tick()  →  App (shared state)  →  ui::draw()  →  ratatui frame

There is no async runtime; crossterm::event::poll provides the non-blocking event check.

🧪 Testing

The test suite lives in src/tests/ and is compiled only in test builds (#[cfg(test)]). It covers the full public API: metric structs, refresh functions, UI helpers, and the SplitGauge widget.

cargo test

Test coverage overview

Module What is tested
tests::push_history Ring-buffer eviction, growth to capacity, length invariant
tests::helpers format_bytes SI boundaries, usage_color/_f64 thresholds, scroll_indicator states
tests::cpu CpuState::new zeroed state & history dimensions; refresh valid range & history cap
tests::memory MemState::new zeroed state; refresh used ≤ total + history cap
tests::network NetState::new zeroed state; refresh history cap & rate consistency
tests::disks DiskState field storage; refresh non-empty result, used ≤ total, non-empty names/mounts
tests::processes ProcessEntry field storage; refresh ≤ 100 entries, CPU-descending sort, non-empty names
tests::gpu GpuEntry::new zeroed fields, history lengths; amd::refresh smoke test & invariants
tests::split_gauge Ratio clamping, full/empty/half fill, label centring, block inner area, zero-size no-panic

Running with NVIDIA feature

cargo test --features nvidia

📦 Dependencies

Crate Purpose
ratatui TUI layout and widget rendering
crossterm Cross-platform terminal control, raw mode, event stream
sysinfo CPU, RAM, swap, network, disk, process data
anyhow Ergonomic error handling
nvml-wrapper (optional) NVIDIA GPU metrics via NVML

🗺️ Roadmap

Items are loosely ordered by priority.

🔜 Near-term

  • 🔵 Intel GPU support — utilisation via GT frequency ratio (i915/xe sysfs), LMEM for Intel Arc cards, temperature via hwmon; shown with appropriate caveats for iGPUs
  • 🏷️ AMD APU label fix — distinguish GTT (shared) from dedicated VRAM and label accordingly
  • ⏱️ Configurable refresh rate — CLI flag --interval <ms> to tune between low-latency and low-CPU usage ✅
  • 🎨 Colour themes — built-in dark/light/high-contrast theme switcher

🔧 Medium-term

  • 🔬 Per-process GPU attribution — show which processes hold GPU memory (via NVML or fdinfo on the DRM driver)
  • 🌡️ Temperature history charts — per-core CPU and GPU temperature sparklines, not just current values
  • 💨 Fan speed — hwmon fan RPM display in the GPU card and a new thermal overview section
  • 🌐 Network per-interface breakdown — drill-down view listing each interface (eth0, wlan0, lo…) separately with its own sparkline
  • 💽 Disk I/O throughput — read/write MB/s per device, not just partition usage percentages
  • 🔋 Battery / power panel — laptop-focused: charge level, rate of charge/discharge, estimated time remaining

🚀 Long-term / differentiators

  • 📋 Log tail panel — a dedicated tab that tails systemd journal or a user-specified log file in real time, with regex highlight rules; something htop and gotop completely lack
  • 🚨 Alert rules — user-defined thresholds (e.g. CPU > 90% for > 5 s, VRAM > 80%) that flash the affected panel border red and optionally send a desktop or webhook notification
  • 🔌 Plugin / script hooks — allow arbitrary shell scripts or Rust dynamic libraries to provide custom metric panels, making narsil extensible without a fork
  • 📼 Session recording & replay — record a metric session to a compact binary file and replay it later for post-mortem analysis
  • 🖥️ SSH-aware remote mode — connect to a remote host via SSH and display its metrics locally in the same TUI, without needing narsil installed on the remote
  • 🖱️ Mouse support — click tabs and scroll panels with the mouse alongside the existing keyboard navigation
  • 📊 Export — one-shot --json / --prometheus output mode for integration with external dashboards (Grafana etc.)

⚖️ Comparison with existing tools

Feature top htop gotop narsil
Language C C Go 🦀 Rust
GPU metrics ❌ ❌ partial ✅ AMD + NVIDIA (Linux)
Braille charts ❌ ❌ ✅ ✅
Per-char label inversion ❌ ❌ ❌ ✅
Disk usage bars ❌ ❌ ✅ ✅
Status bar with keybindings ❌ ❌ ❌ ✅
Log tail panel ❌ ❌ ❌ 🗓️ planned
Alert rules ❌ ❌ ❌ 🗓️ planned
Remote mode ❌ ❌ ❌ 🗓️ planned
Session replay ❌ ❌ ❌ 🗓️ planned

📄 License

GPL-3.0 — see LICENSE.