shervinsights 0.1.2

Read-only Mac/Linux triage CLI for debugging interviews and SadServers-style scenarios.

shervinsights

shervinsights is a read-only Mac/Linux system triage CLI.

It provides a compact summary of common machine-level issues and offers follow-up commands for deeper inspection. It is designed to be safe by default: it does not kill processes, delete files, restart services, or modify system state.

What it checks

• system load
• disk and inode usage
• high CPU and memory processes
• zombie and uninterruptible-sleep processes
• deleted-but-open files
• actively growing log-like files
• listening TCP ports
• Python and model-serving-like processes
• shell script syntax errors
• Linux-specific services, logs, timers, and GPU state when available

Install

pip install shervinsights

If your Python environment blocks direct installs, use a virtual environment:

python3 -m venv ~/.venvs/shervinsights
~/.venvs/shervinsights/bin/pip install shervinsights
~/.venvs/shervinsights/bin/shervinsights --hints

Usage

shervinsights
shervinsights --hints
shervinsights --sample 10 --hints

Show more detail for a specific area:

shervinsights --details disk
shervinsights --details proc
shervinsights --details logs
shervinsights --details ports
shervinsights --details scripts
shervinsights --details ml
shervinsights --details linux

Examples

Compact summary:

shervinsights --hints

Check log growth over a longer window:

shervinsights --details logs --sample 10 --hints

Inspect process pressure:

shervinsights --details proc --hints

Inspect ports:

shervinsights --details ports --hints

Safety

shervinsights is read-only. It prints observations and suggested next commands, but it does not apply fixes automatically.

Typical follow-up commands include:

ps -p PID -o pid,ppid,user,stat,pcpu,pmem,command
lsof -p PID
lsof FILE
tail -n 100 FILE
curl -v localhost:PORT
bash -n SCRIPT
bash -x SCRIPT

Platform notes

On macOS, shervinsights primarily uses:

• ps
• lsof
• df
• du
• find
• tail
• bash
• curl

On Linux, it also uses available tools such as:

• systemctl
• journalctl
• ss
• nvidia-smi
• /proc

Output depends on the current user's permissions. Without elevated privileges, some process, file, service, or log details may be hidden by the operating system.

License

MIT