corelens 0.1.0

Linux TUI for CPU topology, local AI workloads, and GPU metrics
Documentation

corelens

corelens is a Linux TUI for answering where local AI workloads are actually running:

  • which physical cores and logical threads are busy;
  • whether detectable Intel hybrid work is on P- or E-cores;
  • the last logical CPU observed for a process or thread;
  • whether Ollama models are CPU-bound, GPU-bound, or offloaded;
  • all DRM GPU devices, with NVIDIA NVML metrics when available and Intel/AMD sysfs metrics where exposed.

It is deliberately not a replacement for htop or btop.

Install from crates.io

On a Linux system with Rust installed:

cargo install corelens
corelens

The binary is named corelens, so no separate launcher or configuration is required.

┌──────────────── CPU TOPOLOGY · topology ────────────────┐
│ P0 / pkg 0       T0 82% kernel  T1 31% kernel   4.2 GHz │
│ E4 / pkg 0       T4 55% capacity heuristic       3.0 GHz│
└──────────────────────────────────────────────────────────┘
┌──────────────── PROCESSES ────────────────┐ ┌── OLLAMA ──┐
│ PID    NAME       CPU    RSS   LAST CPU    │ │ model      │
│ 8421   *ollama    188%  1.2G       2       │ │ 100% GPU   │
└───────────────────────────────────────────┘ └────────────┘

Build and run

cargo build --release
cargo run --release
cargo run --release -- --refresh-ms 250 --ollama-url http://127.0.0.1:11434
# equivalent after installation:
corelens --refresh-ms 250

Required validation commands:

cargo build --release
cargo test
cargo clippy --all-targets --all-features -- -D warnings
cargo fmt --check

CachyOS / Arch Linux

Install the Rust toolchain and build tools using the distribution packages:

sudo pacman -S --needed base-devel rust
git clone <repository-url>
cd corelens
cargo build --release
./target/release/corelens

GPU discovery reads /sys/class/drm/card*/device and needs no root access. NVIDIA metrics require a working driver that exposes libnvidia-ml.so; NVML failure does not hide Intel, AMD, or metric-less NVIDIA devices. Ollama metrics require an Ollama server listening on the configured URL.

Permissions

No root privileges are required. corelens reads /proc, CPU sysfs topology, optional hwmon sensors, NVML, and the local Ollama HTTP API. Processes that hide their /proc entries or exit during a scan are skipped safely.

P-core / E-core detection

Detection is deliberately conservative:

  1. kernel topology core_type metadata when available;
  2. reliable architecture metadata when later added;
  3. Linux capacity grouping;
  4. maximum-frequency grouping as a lower-confidence heuristic;
  5. Unknown when no evidence exists.

The CPU panel shows the detection source beside logical-thread utilization. A capacity or frequency result is not presented as certain hardware identity.

Last CPU versus CPU residency

Last CPU comes from the processor field in the current /proc/<pid>/stat or /proc/<pid>/task/<tid>/stat snapshot. It answers where the kernel most recently reported the task, not its historical scheduler residency. Historical residency will require a future scheduler tracing backend; this MVP does not use eBPF and does not require root.

Limitations

  • Linux only.
  • CPU temperature is shown only when a CPU/package hwmon label is available.
  • GPU utilization/VRAM may be unavailable when the kernel driver exposes no matching sysfs metrics or NVML cannot be loaded; discovered devices remain visible.
  • Per-process GPU names are not available from every NVML driver, so GPU process rows use PID and VRAM where supported.
  • Process CPU percentages begin after a second sample.
  • Hybrid classification remains unknown when the kernel exposes no usable metadata.

Collector failures remain visible in the footer, while the last valid snapshot is kept for collectors that previously succeeded.

Roadmap

  • scheduler tracing backend for historical CPU residency;
  • richer Intel/AMD topology metadata;
  • configurable process filters and process detail view;
  • additional GPU backends;
  • optional temperature/frequency calibration and export formats.

Controls

q / Esc quit · Tab focus · j/Down, k/Up select · Enter inspect · r refresh · c toggle topology/logical view · s sort processes · ? help.

License

MIT. See LICENSE.