pidlens

Everything macOS knows about a running process, in one readable report.

ps tells you a process exists. lsof tells you what it has open. codesign tells you who signed it. launchctl tells you who keeps it alive. pidlens asks all of them and prints one report you can actually read — decoded into English, wrapped to your terminal, no flags to memorise.

sthnaqvi@macbook ~ % pidlens 594

╭──────────────────────────────────────────────────────────────────────────╮
│                            Finder  (pid 594)                             │
╰──────────────────────────────────────────────────────────────────────────╯
── IDENTITY ────────────────────────────────────────────────────────────────
Name            : Finder
PID             : 594
Parent PID      : 1
Owner           : sthnaqvi (uid 501)
Terminal        : none — not attached to a terminal
State           : sleeping (waiting, idle under 20s)
Scheduling      : priority 46, nice 0 (normal)
Process group   : 594
Session         : 0

── WHEN IT STARTED ─────────────────────────────────────────────────────────
Started at      : Wednesday, 5 August 2026 at 9:38:15 PM
Running for     : 23 days, 18 hours, 31 min
CPU time used   : 38 min, 26 sec (0.1% of one core over its lifetime)
Booted at       : Wednesday, 5 August 2026 at 9:37:59 PM
Vs. boot        : started 16 sec after boot → a startup service, not
                  something you launched
Unix epoch      : 1785946095

── WHAT IS RUNNING ─────────────────────────────────────────────────────────
Executable      : /System/Library/CoreServices/Finder.app/Contents/MacOS
                  /Finder
Arguments       : none
Working dir     : /
── WHO STARTED IT ──────────────────────────────────────────────────────────
[1] root
  /sbin/launchd
  └─ [594] sthnaqvi
       /System/Library/CoreServices/Finder.app/Contents/MacOS/Finder

── RESOURCE USAGE ──────────────────────────────────────────────────────────
CPU now         : 0.0%
Memory          : 26.6 MB resident (0.1% of RAM)
Virtual size    : 398.8 GB
                  virtual size is address space reserved, not memory in use
Threads         : 10
Open handles    : 249

── NETWORK ─────────────────────────────────────────────────────────────────
  no network sockets open
  plus 1 unix-domain socket(s) for local IPC

── THE BINARY ON DISK ──────────────────────────────────────────────────────
Path            : /System/Library/CoreServices/Finder.app/Contents/MacOS
                  /Finder
Size            : 23.6 MB
Modified        : 17 August 2025 at 12:14 AM
Owner           : root, mode 755
Architectures   : arm64e, x86_64
Signed by       : Software Signing
Chain           : Apple Code Signing Certification Authority → Apple Root CA
Bundle ID       : com.apple.finder
Team ID         : —
Signed on       : 12 Jul 2025 at 2:00:36 PM
Entitlements    : 88 granted
  · com.apple.accounts.appleaccount.fullaccess
  · com.apple.amp.devices.client
  · com.apple.application-identifier
── SERVICE / LAUNCHD ───────────────────────────────────────────────────────
Managed job     : com.apple.Finder
Last exit       : 0
  launchd owns this — it is restarted automatically when it exits

…

Install

Homebrew

brew tap sthnaqvi/tap
brew install pidlens

npm

npm install -g pidlens

pip (or pipx, which keeps it out of your system Python)

pipx install pidlens     # recommended
pip install pidlens

From source

git clone https://github.com/sthnaqvi/pidlens.git
cd pidlens && make venv && make test && pip install .

The npm package bundles the same Python program and only needs Python 3.9+ on your PATH — nothing is compiled or downloaded at install time. Set PIDLENS_PYTHON to pick a specific interpreter.

However you installed it, pidlens --version says which channel that copy came from, so a bug report can name it:

sthnaqvi@macbook ~ % pidlens --version
pidlens 0.1.0 (installed via homebrew)

Usage

pidlens 594                  # by pid
pidlens Finder                 # by name — exact first, then loose, then argv
pidlens node --all             # don't truncate long lists
pidlens 594 --json | jq .    # same data, machine-readable
pidlens 594 -s timing,binary # only the sections you want
sudo pidlens 594             # also reveals environment variables

Exit codes: 0 report produced · 2 no target given · 3 no such process · 4 not macOS.

What each section answers

Answering "when did this start?"

The timing section is the one most people come for:

Started at      : Wednesday, 5 August 2026 at 9:38:15 PM
Running for     : 23 days, 18 hours, 31 min
CPU time used   : 38 min, 26 sec (0.1% of one core over its lifetime)
Booted at       : Wednesday, 5 August 2026 at 9:37:59 PM
Vs. boot        : started 16 sec after boot → a startup service, not
                  something you launched
Unix epoch      : 1785946095

ps -o lstart gives you the first line. The value is in the rest: elapsed time in units you can hold in your head, CPU time as a share of one core, and the comparison against boot that tells you whether anyone ever chose to run this.

JSON

Every value in the report comes from one dict, and --json prints it:

sthnaqvi@macbook ~ % pidlens 594 --json | jq '{started: .timing.started_human,
    age: .timing.elapsed_human, signed_by: .binary.signature.authority,
    launchd: .launchd.label}'
{
  "started": "Wednesday, 5 August 2026 at 9:38:15 PM",
  "age": "23 days, 18 hours, 31 min",
  "signed_by": "Software Signing",
  "launchd": "com.apple.Finder"
}

More recipes — every field is documented in docs/json-schema.md:

pidlens node --json | jq -r '.sockets[].description'
pidlens Safari --json | jq -r '.binary.entitlements[]'
pidlens 594 --json | jq '.timing.started_at_boot'

How it works

pidlens is read-only. It never attaches to, signals, or modifies the process it describes — it shells out to tools already on your Mac and parses what they print:

Two consequences worth knowing:

• Environment variables need root. macOS only exposes another process's environment to root, even your own processes. sudo pidlens PID shows them. Names that look like credentials (*_TOKEN, *_SECRET, *PASSWORD*, …) are masked before printing either way.
• Gatekeeper "not assessed" is normal. spctl only rates app bundles, so a plain executable comes back unassessable even when its signature is perfectly valid. pidlens says that, instead of reporting a scary "rejected".

Requirements

macOS (tested on Sonoma and Sequoia) and Python 3.9 or newer — the version macOS itself ships. No third-party dependencies — the whole tool is the standard library plus the system tools above.

Development

make venv     # local .venv with dev dependencies
make test     # 550+ tests, no live processes required for most of them
make demo     # run pidlens against your shell
make build    # sdist + wheel
make npm-pack # build the npm tarball

The code is split so that almost all of it is testable without a running process:

src/pidlens/
  humanize.py  bytes, durations, ps state codes → English      (pure)
  layout.py    width-aware wrapping and the Renderer           (pure)
  parse.py     one parser per tool's output format             (pure)
  system.py    the only module that shells out
  collect.py   builds the data model for one pid
  report.py    turns the data model into sections
  cli.py       arguments, exit codes, JSON

Tests use fixtures captured from real lsof, codesign, spctl and launchctl output, plus a FakeRunner that answers commands from a dict — so the parsers and the entire report are verified without touching a live process. The layout suite asserts that no line ever exceeds the terminal width and that wrapping loses no characters, across widths from 38 to 110 columns.

Contributing

Issues and pull requests are welcome — see CONTRIBUTING.md.

License

MIT © Sayed Tauseef Naqvi