# 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).