process-inspector

A Rust TUI process inspector that teaches while you inspect live processes.

process-inspector is a read-only terminal UI for exploring live processes on macOS and Linux. It gives developers a fast process table, focused process tree, open-file view, and ports view, while giving learners guided explanations of what PID, PPID, CPU, memory, command paths, file descriptors, and process state actually mean.

┌ process-inspector | 284 processes | search: node ───────────────┐
│ PID     PPID    CPU    MEM      STATUS       NAME               │
│ 19214   9182    12.4   210.3M   Run          node               │
│ 19242   19214   3.1    88.7M    Sleep        npm                │
├ Focused Tree ───────────────────┬ Views ────────────────────────┤
│ launchd (1)                     │ PID: 19214                    │
│   zsh (9182)                    │ Name: node                    │
│     node (19214)                │ Parent PID: 9182              │
│       npm (19242)               │ CPU: 12.4%                    │
├ Files / Ports / Explain ────────┴───────────────────────────────┤
│ node is a running program instance with PID 19214.               │
│ Its parent process is 9182. Parent processes usually started...  │
└──────────────────────────────────────────────────────────────────┘

Why This Exists

Most process tools assume you already understand the operating system. process-inspector is built for two workflows:

• Inspect: quickly search live processes, inspect details, and understand parent/child relationships.
• Learn: follow guided lessons that use your real machine as the teaching material.

Status

process-inspector is early but usable. The current release target is a polished v0.1 for local inspection, learning, demos, and OSS feedback.

Supported now:

• macOS
• Linux

Planned later:

• Windows support
• Homebrew formula
• npm and pipx native-binary wrappers
• Optional safe signal actions after a separate design review

Features

• Terminal-first UI built with Rust and Ratatui.
• Startup mode picker: Inspect or Learn.
• Searchable process table.
• Sticky PID selection that stays stable across refreshes.
• Process tree for parent/child relationships.
• Scroll-following viewport for long process lists.
• Details panel for PID, parent PID, command, executable path, user, CPU, memory, and status.
• Explanation panel that translates process fields into plain language.
• Focused tree view that follows the selected process lineage and descendants.
• Open files and ports tabs powered by lsof for the selected process family.
• Guided lessons for process fundamentals.
• JSON and text snapshot export.
• Read-only by design for v0.1.

Install

Project site: https://omekum99.github.io/process-inspector/

Requirements

• Rust stable 1.75 or newer for source installs.
• lsof for Files and Ports views.
• macOS or Linux.

From Source

git clone https://github.com/omekum99/process-inspector.git
cd process-inspector
cargo install --path .
process-inspector

With Cargo

After the first crates.io release, installation will be:

cargo install process-inspector
process-inspector

Standalone Downloads

Prebuilt binaries are planned for GitHub Releases:

• macOS Apple Silicon
• macOS Intel
• Linux x86_64

Future Installers

Planned after the first stable release:

brew install omekum99/tap/process-inspector
npm install -g process-inspector
pipx install process-inspector

The npm and pipx packages should be lightweight wrappers around the native binary, not separate implementations.

Usage

Open the mode picker:

process-inspector

Start directly in Inspect mode:

process-inspector --mode inspect

Start directly in Learn mode:

process-inspector --mode learn

Change refresh interval:

process-inspector --refresh-ms 1500

Export a JSON snapshot:

process-inspector snapshot --format json --output snapshot.json

Export a text snapshot:

process-inspector snapshot --format text --output snapshot.txt

Inspect Views

View	Purpose
Summary	PID, PPID, user, CPU, memory, executable path, working directory, and command
Tree	Focused lineage and descendants for the selected process
Files	Open files for the selected process family via lsof
Ports	Listening and connected sockets for the selected process family via lsof
Explain	Plain-language explanation of selected process fields

Keyboard

Key	Action
q / Ctrl-C	Quit
?	Help
m	Mode picker
l	Learn mode
i	Inspect mode
Type text	Filter process list
Esc	Clear search
↑ / ↓	Move selection
PageUp / PageDown	Jump selection
e	Toggle explanation panel
Tab / Shift-Tab	Switch inspect view tabs
1	Summary view
2 / t	Focused tree view
3 / f	Open files view
4 / p	Ports view
5	Explanation view

Architecture

OS process APIs
      ↓
ProcessSource
      ↓
Vec<ProcessInfo>
      ↓
Search + Tree Builder + Explainer + lsof Resource Probe
      ↓
Ratatui screens

The UI does not talk directly to the operating system. src/process_source.rs collects live data through sysinfo, then the rest of the app works with normalized ProcessInfo values. src/process_resources.rs shells out to lsof only when Files or Ports views need it. This keeps search, tree building, lesson text, explanations, parsing, and export logic testable.

Safety

process-inspector is read-only:

• It does not kill processes.
• It does not send signals.
• It does not run commands from inside the TUI.
• It does not upload process data.

Snapshot files may contain local paths, command arguments, and process names. Review them before sharing publicly.

Development

cargo fmt --check
cargo test
cargo build

Run locally:

cargo run

Create a local snapshot:

cargo run -- snapshot --format json --output snapshot.json

Roadmap

• v0.1: read-only TUI, lessons, focused process tree, files/ports views, snapshot export.
• v0.2: richer process tree controls, sort modes, better platform-specific fields.
• v0.3: Homebrew tap and binary wrapper packages for npm/pipx.
• Later: Windows support, optional safe signal actions, deeper diagnostics.

License

MIT License.

(c) sriram kumar