Documentation
Complete guide to Perf Pulse Pro — the premium Mac performance suite.
Getting Started
Installation
Install via Homebrew (recommended):
Manual Install
Or download directly with our install script:
Activate License
After purchasing, activate your Pro license:
Your license is stored locally at ~/.config/perf-pulse/license.json. Works on up to 3 Macs you own.
Launch Dashboard
Start the web dashboard:
Opens at http://localhost:7575. Use --port 8080 for a custom port.
Crash Guard
Crash Guard monitors memory pressure, swap growth, per-app memory velocity, and writable disk headroom. It can warn you before resource exhaustion makes your Mac unresponsive, then bring the exact live dashboard tab forward so you can review the cause.
Turn on protection at login
This installs a per-user macOS launch agent. It does not require a root daemon, admin password, or system extension. Always-on protection requires Perf Pulse Pro. If a manual dashboard is already using port 7575, close that session first or install with --port 7576.
Inspect protection
Alerts and actions
Native alerts use concise incident-first copy. With Bring dashboard forward enabled, the alert opens the live local #guard view. Process stops require confirmation and a fresh PID, name, and start-time check. Storage diagnostics never delete files automatically.
Tune or disable it
In the Crash Guard dashboard tab you can toggle memory, disk, and native notifications independently. Pro users can choose Early warning, Balanced, or Quiet protection and fine-tune thresholds.
Uninstalling removes the launch agent and keeps local settings and logs.
Performance Score
A single 0-100 number representing your Mac's overall health. The score combines multiple metrics with configurable weights:
| Component | Weight | Description |
|---|---|---|
| CPU Headroom | 30% | 100 - cpu_percent, penalized above 80% |
| Memory Pressure | 25% | macOS memory_pressure + percentage |
| Disk I/O | 15% | Read/write throughput (0-100 scale) |
| Swap Usage | 15% | 0 swap = 100, >2GB = 0 |
| Process Efficiency | 15% | <300 procs = 100, -10 per zombie |
Score grades: 90+ (Excellent), 70-89 (Good), 50-69 (Fair), <50 (Poor)
Meeting Mode
Pause resource-heavy background processes for smoother video calls. Uses SIGSTOP/SIGCONT for safe pause/resume.
Default Targets:
- •
Docker Desktop— hypervisor and containers - •
mds / mds_stores— Spotlight indexing - •
backupd— Time Machine - •
bird— iCloud sync - • Custom processes via config file
Config file: ~/.config/perf-pulse/meeting_mode.json
Battery Optimizer
Monitor energy impact per process and extend battery life by 30%+.
What Gets Optimized:
- • Throttle high-energy processes when on battery
- • Pause background sync services
- • Reduce process priorities for non-essential apps
- • Recommendations for manual actions (close tabs, quit apps)
Developer Profiles
Pre-configured optimization profiles for different workflows:
React/Node
Prioritize node, npm, Chrome, VS Code. Auto-pause idle Docker.
iOS/Xcode
Prioritize Xcode, Simulator, swift. Auto-pause Docker, node.
Data Science
Prioritize python3, jupyter, R. Aggressive memory cleanup.
General Dev
Auto-detect your top 5 processes. Balanced optimization.
Creative
Prioritize Photoshop, Final Cut. Pause dev tools.
Startup Manager
View and manage LaunchAgents and LaunchDaemons. See impact scores for each item.
Impact scores are calculated from CPU/memory usage during boot. System-critical items are protected from modification.
Auto-Scheduling
Schedule automatic optimization runs via launchd.
Uses native macOS launchd for reliable scheduling even when the app isn't running.
Webhook Alerts
Get notified when your Performance Score drops below a threshold.
Supported Integrations:
- • Slack — Incoming webhooks
- • Discord — Webhook URL
- • Generic — Any HTTP endpoint (POST JSON)
AI Pattern Detection
Learn your usage patterns over time. All analysis runs locally — no cloud AI.
What Gets Detected:
- • Time-based slowdowns — "Performance drops at 3pm when Docker + Chrome peak"
- • Memory leaks — "Slack grows 200MB+ over 8 hours"
- • Process bottlenecks — Identify apps causing consistent issues
- • Optimal windows — Best times for heavy tasks
Requires 7-14 days of data for meaningful insights. Data stored at ~/.local/share/perf-pulse/history/
CLI Reference
Start the web dashboard. Opens your browser automatically.
--port <number> — Set custom port (default: 7575) --no-open — Don't open browser
Show Performance Score with component breakdown.
--watch — Live updating --history <period> — Show historical scores (1d, 7d, 30d)
Run a one-time system analysis. Pipe to Claude Code for AI insights.
--json — Output as JSON --format <table|json|csv> — Output format
One-click 'Make It Fast' — runs all safe optimizations.
--dry-run — Show what would be done --mode <balanced|aggressive|safe>
List all open ports and which process owns each one.
--port <number> — Check a specific port
Get a plain-English explanation of what a process does.
--ai — Use Claude/OpenAI for explanation (requires API key)
Generate before/after comparison report.
--mode <balanced|aggressive|safe> --export <json|png>
Live terminal TUI monitor (like htop but prettier).
--refresh <seconds> — Update interval (default: 2)
AI Integration
AI features are entirely optional. The built-in knowledge base covers 500+ macOS processes.
Using with Claude Code
Built-in AI Explainer
Set your API key: ANTHROPIC_API_KEY or OPENAI_API_KEY
Troubleshooting
"Permission denied" on macOS
Perf Pulse needs access to process information:
You only need sudo once. After granting permission, run without sudo.
Dashboard won't open
Try http://localhost:7575 manually, or use --port 8080.
License activation failed
Ensure internet connection for initial activation. Email support@perf-pulse.com with your license key.
Reset configuration
To reset all settings to defaults:
System Requirements
- macOS 12 (Monterey) or later
- Apple Silicon or Intel
- Homebrew (recommended) or manual install
- Internet only needed for initial license activation
- ~50MB disk space