procman

name	procman
description	Inspect and safely control CPU, GPU, memory, energy, battery, sleep, launchd services, ports, and loaded local models on macOS. Use when a Mac is slow, hot, swapping, draining battery, refusing to sleep, running an unknown service, exposing a port, or holding a local LLM in memory.
version	2.0.0
license	MIT
platforms	["macos"]
metadata	{"tags":["macos","processes","cpu","gpu","memory","energy","battery","launchd","monitoring"]}

procman — macOS resource manager

Use procman for machine-wide resource diagnosis and safe process control. The default install path is ~/.local/bin/procman; use the absolute path when the shell environment may not include it.

Start with procman doctor --json when capability or compatibility is uncertain.

Read commands

Prefer --json when interpreting output programmatically.

Command	Purpose
procman --json	Machine overview: CPU/load, memory, GPU, power, models, top processes
procman doctor --json	macOS version, architecture, required tools, optional capabilities
procman hogs --json	Actionable resource findings with severity and next steps
procman mem --json	Memory pressure, wired/compressed/swap, true footprint, process families
procman top --by cpu|mem|footprint --json	Ranked processes
procman gpu --json	Device GPU telemetry and optional per-process GPU sample
procman energy --json	macOS POWER/energy-impact sample
procman power --detail --json	Battery, thermals, assertions, health, low-power mode
procman services --json	launchd jobs; add --system, --failed, --all, or --find REGEX
procman ports --json	TCP listeners and UDP sockets with owners
procman find REGEX --json	Full command-line process search
procman info PID --json	Process details, footprint, cwd, ports, launchd ownership
procman models --json	Loaded LM Studio/Ollama/configured local endpoint models
procman awake status --json	Managed caffeinate agent and sleep state
procman report	Markdown audit suitable for chat or incident notes

Diagnostic sequence

1. Run procman hogs --json.
2. Follow with the focused command named in each finding.
3. Inspect a target with procman info PID --json before changing it.
4. Preview mutations with the exact same command plus --dry-run.
5. Apply only the smallest necessary change.

Examples:

• High memory or swap: procman mem --json.
• High CPU or heat: procman top --by cpu --json, then procman energy --json and procman power --json.
• GPU concern: procman gpu --json; unavailable per-process data is a capability limitation, not proof that no process uses the GPU.
• Battery drain or sleep problem: procman power --detail --json, then procman awake status --json.
• Service failure: procman services --failed --json.
• Unknown network listener: procman ports --json, then procman info PID --json.
• Forgotten local model: procman models --json; unload only when the user authorizes it.

Mutating commands

procman stop PID_OR_LABEL_OR_REGEX --dry-run --json
procman kill PID_OR_LABEL_OR_REGEX --dry-run --json
procman pause PID_OR_REGEX --dry-run --json
procman resume PID_OR_REGEX --dry-run --json
procman models --unload --json
procman awake on --json
procman awake off --json

Required behavior

• Always use --dry-run first for process or service actions unless the user supplied an exact PID and explicitly requested immediate action.
• Do not add --all until every matched process has been reviewed.
• Do not use --force merely to bypass uncertainty.
• Do not use --signal-only for a launchd service unless a raw signal is specifically required; normal stop/kill uses launchctl bootout to avoid KeepAlive respawn.
• Treat unloaded models, stopped services, and sleep changes as user-visible state changes that require authorization.
• Never infer that a large Apple Silicon GPU allocation is a leak. Unified memory may be legitimate and active.

Built-in safety

• Protects core macOS services, remote-access lifelines, and procman's ancestry.
• Refuses regex actions matching more than three processes without --all.
• Uses only non-interactive sudo -n.
• Resolves launchd-managed PIDs and boots out the service instead of causing a respawn loop.
• Checks --dry-run before every signal, bootout, or privilege escalation.
• Tracks ownership before changing global pmset disablesleep state.

Machine-specific additions

After installation, add local context here or in ~/.config/procman/config.json:

• agent gateways, remote-control services, or watchdogs that must remain protected;
• deliberate always-awake behavior;
• local model servers and loopback /v1/models endpoints;
• threshold adjustments for unusually large-memory Macs.