Back to home

Documentation

Complete guide to Perf Pulse Pro — the premium Mac performance suite.

v1.4.0macOS 12+Apple Silicon & Intel

Getting Started

Installation

Install via Homebrew (recommended):

$ brew install hopeatina/tap/perf-pulse

Manual Install

Or download directly with our install script:

$ curl -fsSL https://perf-pulse.com/install.sh | sh

Activate License

After purchasing, activate your Pro license:

$ perf-pulse activate PP-XXXXXXXX-XXXXXXXX-XXXXXXXX

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:

$ perf-pulse serve

Opens at http://localhost:7575. Use --port 8080 for a custom port.

Performance Score

A single 0-100 number representing your Mac's overall health. The score combines multiple metrics with configurable weights:

ComponentWeightDescription
CPU Headroom30%100 - cpu_percent, penalized above 80%
Memory Pressure25%macOS memory_pressure + percentage
Disk I/O15%Read/write throughput (0-100 scale)
Swap Usage15%0 swap = 100, >2GB = 0
Process Efficiency15%<300 procs = 100, -10 per zombie
CLI Usage
$ perf-pulse score # Current score with breakdown $ perf-pulse score --watch # Live updating score $ perf-pulse score --history 7d # 7-day score history

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
CLI Usage
$ perf-pulse meeting-mode on # Enable Meeting Mode $ perf-pulse meeting-mode off # Disable and restore processes $ perf-pulse meeting-mode status # Show status and paused processes $ perf-pulse meeting-mode --duration 90 # Auto-restore after 90 minutes

Config file: ~/.config/perf-pulse/meeting_mode.json

Battery Optimizer

Monitor energy impact per process and extend battery life by 30%+.

CLI Usage
$ perf-pulse battery status # Battery status + energy impact report $ perf-pulse battery optimize # Apply power-saving optimizations $ perf-pulse battery report # Detailed report with recommendations

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.

CLI Usage
$ perf-pulse profile list # List available profiles $ perf-pulse profile activate react # Activate React/Node profile $ perf-pulse profile create myflow # Create custom profile $ perf-pulse profile export myflow # Export profile as JSON

Startup Manager

View and manage LaunchAgents and LaunchDaemons. See impact scores for each item.

CLI Usage
$ perf-pulse startup list # List all startup items with impact $ perf-pulse startup disable com.app.helper # Disable a startup item $ perf-pulse startup enable com.app.helper # Re-enable a startup 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.

CLI Usage
$ perf-pulse schedule set "02:00" # Run optimization at 2 AM daily $ perf-pulse schedule status # View current schedule $ perf-pulse schedule disable # Disable scheduled runs $ perf-pulse schedule logs # View optimization logs

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.

CLI Usage
$ perf-pulse alerts add slack https://hooks.slack.com/... --threshold 60 $ perf-pulse alerts add discord https://discord.com/api/webhooks/... $ perf-pulse alerts add webhook https://your-server.com/hook $ perf-pulse alerts list $ perf-pulse alerts test slack $ perf-pulse alerts remove slack

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.

CLI Usage
$ perf-pulse patterns analyze # Run pattern analysis $ perf-pulse patterns insights # Show detected patterns and predictions $ perf-pulse patterns reset # Clear historical data

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

$ perf-pulse serve

Start the web dashboard. Opens your browser automatically.

--port <number> — Set custom port (default: 7575)
--no-open — Don't open browser
$ perf-pulse score

Show Performance Score with component breakdown.

--watch — Live updating
--history <period> — Show historical scores (1d, 7d, 30d)
$ perf-pulse analyze

Run a one-time system analysis. Pipe to Claude Code for AI insights.

--json — Output as JSON
--format <table|json|csv> — Output format
$ perf-pulse optimize

One-click 'Make It Fast' — runs all safe optimizations.

--dry-run — Show what would be done
--mode <balanced|aggressive|safe>
$ perf-pulse ports

List all open ports and which process owns each one.

--port <number> — Check a specific port
$ perf-pulse explain <process>

Get a plain-English explanation of what a process does.

--ai — Use Claude/OpenAI for explanation (requires API key)
$ perf-pulse report

Generate before/after comparison report.

--mode <balanced|aggressive|safe>
--export <json|png>
$ perf-pulse top

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

$ perf-pulse analyze --json | claude "What's using the most resources?"

Built-in AI Explainer

$ perf-pulse explain com.apple.bird --ai

Set your API key: ANTHROPIC_API_KEY or OPENAI_API_KEY

Troubleshooting

"Permission denied" on macOS

Perf Pulse needs access to process information:

$ sudo perf-pulse serve

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:

$ rm -rf ~/.config/perf-pulse && rm -rf ~/.local/share/perf-pulse

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