How do I safely terminate a process?

Always run pstop info first to understand the process, then use pstop kill (prefer SIGTERM). Use --force only if the process does not terminate.

How do I view a process tree?

Run pstop tree to display hierarchical relationships among processes. For context, you can combine it with pstop list/top outputs.

How can I set up automated alerts for resource usage?

Use pstop watch --alert with --cpu and/or --mem thresholds (e.g., --cpu 80 --mem 90). You can pair it with lanchr for persistent monitoring.

pstop

Scanned

npx machina-cli add skill lu-zhengda/macos-toolkit/pstop --openclaw

Files (1)

SKILL.md

3.7 KB

pstop — Process Explorer

Show top resource-consuming processes:

!pstop top 2>&1 || echo "pstop not installed — brew install lu-zhengda/tap/pstop"

Analyze the output above. Flag any processes consuming excessive CPU (>50%) or memory (>1 GB). Identify what each process is and whether it looks normal. Offer to get more details with pstop info <pid> or kill with pstop kill <pid>.

Commands

Command	Purpose	Example
`pstop list`	List all running processes	`pstop list --sort cpu`
`pstop list --user <name>`	Filter by user	`pstop list --user root`
`pstop top`	Show top N processes by CPU	`pstop top -n 20`
`pstop top --battery`	Highlight battery-draining processes	`pstop top --battery`
`pstop top --format spark`	Show CPU/mem sparkline trends	`pstop top --format spark`
`pstop find <query>`	Search processes by name or command	`pstop find node`
`pstop info <pid>`	Detailed process info (files, ports, children)	`pstop info 1234`
`pstop kill <pid>`	Kill process (SIGTERM)	`pstop kill 1234`
`pstop kill <pid> --force`	Force kill (SIGKILL)	`pstop kill 1234 --force`
`pstop tree`	Display process tree	`pstop tree`
`pstop dev`	Group processes by dev stack (Node, Python, Docker, etc.)	`pstop dev`
`pstop watch <pid>`	Live-monitor a process	`pstop watch 1234 --interval 5`
`pstop watch --alert`	Threshold-based alerting	`pstop watch --alert --cpu 80 --mem 90`
`pstop crashes`	Recent crash reports and app hangs	`pstop crashes --last 7d`
`pstop crashes info <path>`	Detailed crash report with backtrace	`pstop crashes info /path/to/report.ips`

Crash Reports

View recent crash reports, app hangs, and kernel panics:

# Show recent crash reports
pstop crashes

# Filter by time range
pstop crashes --last 7d

# Filter by process name
pstop crashes --process Safari

# Combine filters
pstop crashes --last 24h --process node

# View detailed crash report with backtrace
pstop crashes info /Library/Logs/DiagnosticReports/Safari_2026-02-15.ips

# JSON output for scripting
pstop crashes --json

Threshold Alerting

Monitor processes and alert when thresholds are exceeded:

# Alert when any process exceeds 80% CPU or 90% memory
pstop watch --alert --cpu 80 --mem 90

# Exit code 1 when thresholds exceeded — useful in scripts and lanchr agents
pstop watch --alert --cpu 95 --mem 95

Combine with lanchr create --template monitor-cpu to set up persistent alerting.

Sparkline Format

View inline CPU/memory trend history:

pstop top --format spark

Renders compact sparkline graphs alongside each process, showing resource usage over time.

Sort Options

Use --sort with list to sort by: cpu, mem, pid, name (default: cpu).

Safety Guidelines

Always info before kill: Check what a process does before terminating
Prefer SIGTERM (default): Allows graceful shutdown. Only use --force as last resort
Use find for discovery: Safer than guessing PIDs

TUI Mode

Launch pstop without arguments for an interactive process dashboard.

Source

git clone https://github.com/lu-zhengda/macos-toolkit/blob/main/skills/pstop/SKILL.mdView on GitHub

Overview

pstop is a macOS process explorer that surfaces top resource-consuming processes. It helps you identify what’s using CPU or memory, inspect details with pstop info, view process trees, and safely terminate processes when needed. It also supports live monitoring, threshold alerts, and crash diagnostics.

How This Skill Works

pstop gathers live process data through commands like pstop list, pstop top, and pstop find, then highlights high-usage items (>50% CPU or >1 GB RAM). You can drill into details with pstop info, terminate with pstop kill, or view relationships with pstop tree and pstop dev. Optional live monitoring and visuals come from pstop watch and --format spark, plus crash data via pstop crashes.

When to Use It

When you need to identify CPU or memory hogs on macOS to troubleshoot performance
When battery drain is suspected and you want to pinpoint the responsible process
When an app hangs or crashes and you need to inspect related processes
When you must safely terminate a misbehaving process after diagnosing with pstop info
When you want to understand process relationships or development stacks with pstop tree or pstop dev

Quick Start

Step 1: Run pstop top -n 10 to surface the top resource users, or pstop list to see all running processes
Step 2: Inspect a PID with pstop info <pid>, then kill with pstop kill <pid> after confirming
Step 3: Optional — set up alerts with pstop watch --alert --cpu 80 --mem 90 or view sparkline with pstop top --format spark

Best Practices

Always run pstop info before killing a process to understand its role
Prefer SIGTERM (pstop kill) for graceful shutdown; use --force only as a last resort
Use pstop find to safely locate a process before acting
Use pstop tree to understand parent-child relationships; use pstop dev to group by dev stack
Use pstop watch --alert to monitor thresholds and trigger actions automatically

Example Use Cases

Identify Safari consuming CPU during web usage
Find and terminate memory hogs like node or Chrome
Diagnose battery drain by listing processes with --battery
Inspect process tree to locate related child processes of a misbehaving app
Review crash reports with pstop crashes to investigate app hangs or kernel panics

Frequently Asked Questions

Add this skill to your agents