A human-friendly process explainer - understand what's running on your system
PID Pal bridges the gap between raw system process data and human understanding, providing clear, conversational explanations of running processes.
| Platform | Status |
|---|---|
| Linux | Full support |
| macOS | Planned (contributions welcome) |
| Windows | Planned (contributions welcome) |
Ever wondered "What is this process and should I care?" PID Pal answers that question in plain English.
Instead of this:
PID USER %CPU %MEM COMMAND
1234 root 2.3 1.5 /usr/lib/systemd/systemd-journald
You get this:
╭─ systemd-journald (PID 1234)
│
│ System journal logging service.
│
│ What is it?
│ System journal logging service that collects and stores system logs
│ for troubleshooting.
│
│ Why is it running?
│ This process is part of the operating system and likely started at boot.
│
│ ✓ Identified process - appears normal.
│
│ Category: Background service
│ Source: Operating system
│
│ Resources: CPU 2.3% | Memory 1.5%
│ Running as: root
╰─
- Plain English explanations of what processes do and why they exist
- Calm, educational tone - never alarmist, never condescending
- LLM-powered rich explanations (OpenAI, Anthropic Claude)
- Works without LLM - useful fallback mode with curated knowledge
- Extensible - Linux now, macOS and Windows planned
- Lightweight - local-only mode avoids network calls; web-search identifications are cached
- Privacy-respecting - read-only, no system modification
- Developer-friendly - JSON output, scripting support
PID Pal provides informational guidance based on observable process data and a curated knowledge base. It is not a security product or expert assessment. Always verify with official documentation or trusted sources. You are responsible for decisions you make, and the owners, authors, and contributors are not liable for outcomes.
Download the latest binary from releases (if available):
# Linux x86_64
wget https://github.com/MSNYC/pidpal/releases/latest/download/pidpal-linux-x86_64
chmod +x pidpal-linux-x86_64
sudo mv pidpal-linux-x86_64 /usr/local/bin/pidpalOr install from source:
git clone https://github.com/MSNYC/pidpal.git
cd pidpal
pip install .For rich LLM-powered explanations:
# Install LLM dependencies (if installed from source)
pip install ".[llm]"
# Anthropic (recommended)
export ANTHROPIC_API_KEY="your-api-key-here"
# Or OpenAI
export OPENAI_API_KEY="your-api-key-here"Get API keys from:
- Anthropic: https://console.anthropic.com/
- OpenAI: https://platform.openai.com/
Note: When an API key is present, PID Pal enables basic usage logging by default.
Set PIDPAL_OBSERVABILITY=off to disable it.
# Guided mode (interactive wizard - great for beginners)
pidpal
# Explain a process
pidpal 1
# Get detailed information
pidpal 1234 --verbose
# List top 10 processes by resource usage
pidpal --top 10
# JSON output for scripting
pidpal 1234 --json
# Use without LLM
pidpal 1234 --no-llm- Quickstart - Get running in under 5 minutes
- Usage Guide - Complete usage documentation
- Configuration - Config file and environment options
- Architecture - Technical architecture
- Roadmap - Development roadmap
- Contributing - How to contribute
# Explain the init system (PID 1 always exists)
$ pidpal 1
# Explain a specific process by PID
$ pidpal 1234# List top processes by resource usage
$ pidpal --top 5
# Then explain one that interests you
$ pidpal <PID># Get JSON output for scripting
$ pidpal 1 --json | jq '.explanation.summary'
# Check whether a process is marked as normal/expected
$ pidpal 1 --json | jq -r '.interpretation.is_normal'Version: 0.1.0 (MVP in development)
What works:
- Linux process data collection
- Process interpretation with curated knowledge base
- LLM explanations (Anthropic Claude, OpenAI)
- CLI with multiple output modes
- Guided mode (interactive wizard for beginners)
- Process listing with sorting and filtering
- PyInstaller binary build script
- Token/cost observability (enabled by default when an API key is present; configurable)
Coming soon:
- Enhanced knowledge base (200+ processes)
- macOS support
- Windows support
See the roadmap for details.
- Learn about your system without reading dense documentation
- Understand background processes that mystify most users
- Investigate issues with guidance on what matters
- Feel confident about what's running on your computer
- Debug faster with context about running processes
- Understand dependencies and their behaviors
- Script process monitoring with JSON output
- Learn system internals through clear explanations
- Onboard new team members with a learning tool
- Investigate unusual processes with guided explanations
- Use explanations as a starting point for documentation/runbooks
PID Pal operates on these principles:
- Explain, not just display - Convert raw data into understanding
- Be conversational, not cryptic - Output should feel like an expert explaining
- Respect system truth - Never fabricate process details
- Be OS-agnostic - All platforms deserve great tools
- Remain optional-LLM - Provide value without LLM, excel with LLM
PID Pal uses a three-layer architecture:
- Observation Layer - Collects verifiable system data
- Interpretation Layer - Derives structured meaning with heuristics
- Explanation Layer - Produces natural language via LLM or templates
This design ensures:
- System data is never fabricated
- Interpretations are traceable
- Explanations degrade gracefully without LLM
- Each layer can be tested independently
See architecture.md for details.
Contributions are welcome! See CONTRIBUTING.md.
Easy ways to contribute:
- Add process knowledge to the database
- Improve heuristics
- Write documentation
- Report bugs
- Request features
# Clone the repository
git clone https://github.com/MSNYC/pidpal.git
cd pidpal
# Set up development environment
python -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"
# Run tests
pytest tests/
# Run linting
black src/ tests/
ruff check src/ tests/
mypy src/pidpal
# Build binary
bash scripts/build.shMIT License - see LICENSE for details.
- Built with psutil for cross-platform process utilities
- Powered by Anthropic Claude and OpenAI for rich explanations
- CLI built with Click
- Issues: https://github.com/MSNYC/pidpal/issues
- Discussions: https://github.com/MSNYC/pidpal/discussions
- v0.1.0 (Current): MVP with Linux support and LLM integration
- v0.2.0: Observability improvements, broader knowledge base, richer guided experience
- v0.3.0: macOS and Windows support
- v0.4.0: Plugin system, community knowledge base, local LLM support
- v0.5.0: AI-powered anomaly detection, TUI, advanced integrations
See the full roadmap for details.
Made with curiosity and respect for system internals.
PID Pal - Understanding your machine, one process at a time.