Back to home

Documentation

Everything you need to get started with Perf Pulse.

Getting Started

Installation

The recommended way to install Perf Pulse is via Homebrew:

$ brew install perf-pulse

Manual Install

Download the latest release binary and add it to your PATH:

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

Activate License

After purchasing, activate your license key:

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

Your license is stored locally at ~/.config/perf-pulse/license.json.

Launch

Start the dashboard in your default browser:

$ perf-pulse serve

CLI Reference

$ perf-pulse serve

Start the web dashboard. Opens your browser automatically.

--port <number> — Set custom port (default: 7575)
$ perf-pulse analyze

Run a one-time system analysis and print results to stdout. Pipe to Claude Code or Codex for AI insights.

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

List all open ports and which process owns each one.

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

Get recommendations for freeing memory and CPU.

--apply — Automatically apply safe recommendations
--dry-run — Show what would be done (default)
$ perf-pulse explain <process>

Get a plain-English explanation of what a process does. Uses built-in knowledge base or AI.

--ai — Use Claude or Codex for explanation (requires API key)
$ perf-pulse activate <key>

Activate your Pro license.

$ perf-pulse status

Show license status and system info.

AI Integration

Perf Pulse integrates with AI models for process explanation and system analysis. AI features are entirely optional — the built-in knowledge base covers most common macOS processes.

Using with Claude Code

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

Using with Codex

$ perf-pulse analyze --json | codex "Analyze this system state"

Built-in AI Explainer

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

Set your API key via environment variable: ANTHROPIC_API_KEY or OPENAI_API_KEY.

Troubleshooting

"Permission denied" on macOS

Perf Pulse needs access to process information. On first run, macOS may ask for permission. If you see a permission error:

$ sudo perf-pulse serve

You only need to do this once. After granting permission, you can run without sudo.

Dashboard won't open in browser

Try opening http://localhost:7575 manually, or specify a different port with --port 8080.

License activation failed

Make sure you have an internet connection for the initial activation. The license is validated once and then stored locally. If the issue persists, email support@perf-pulse.com with your license key.

System Requirements

  • macOS 12 (Monterey) or later
  • Apple Silicon or Intel
  • Homebrew (recommended) or manual install
  • Internet only needed for initial license activation