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:

```bash
cargo install corelens
corelens
```

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

```text
┌──────────────── 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

```bash
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:

```bash
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:

```bash
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](LICENSE).