macpulse v1.0.0 │ MacBookPro │ Apple M3 Max │ macOS 15.2 │ up 3d 12h │ 14:32:07
  ──────────────────────────────────────────────────────────────────────────────────

  ╭─ ▸ CPU ──────────────────────────────────────────────────────────── 42% ─╮
  │  ████████████████████████████░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░  42%  │
  │  C0: 55%  C1: 38%  C2: 61%  C3: 22%  C4: 47%  C5: 33%  C6: 52%        │
  │  Load: 2.45  3.12  2.89                                                 │
  │  ▁▂▃▄▅▆▇█▇▆▅▄▃▂▃▄▅▆▇▆▅▄▃▂▁▂▃▄▅▆▇█▇▆▅▄▃▂▁▂▃▄▅▆▇█▇▆▅▄▃▂              │
  ╰──────────────────────────────────────────────────────────────────────────╯

  ╭─ Memory ────────────────────────────────────────────── 23.4 / 48 GB ────╮
  │  █████████████████████████░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░   49%  │
  │  ■ App: 18.2G   ■ Wired: 3.1G   ■ Compressed: 2.1G   ■ Cache: 12.0G   │
  │  Pressure: ● NOMINAL   Swap: 0B                                         │
  ╰──────────────────────────────────────────────────────────────────────────╯

  ╭─ GPU ─── Apple M3 Max ──────────╮  ╭─ Disk ─────────────────────────────╮
  │  ██████████░░░░░░░░░░░░░░  22%  │  │  R: 120 MB/s   W: 45 MB/s         │
  ╰─────────────────────────────────╯  │  ███████████████████░░░░░░░░  52%  │
                                       ╰─────────────────────────────────────╯

  ╭─ Network ───────────────────────╮  ╭─ Battery ──────────────────────────╮
  │  ↓ 12.3 MB/s   ↑ 3.1 MB/s      │  │  ⚡ ████████████████████████░  82%  │
  │  Interface: en0                 │  │  Health: 91%  │  Cycles: 245       │
  ╰─────────────────────────────────╯  ╰─────────────────────────────────────╯

  [d] detail  [p] process  [g] graph  [q] quit  │  ↑↓ navigate  │  ● dashboard

  macpulse v1.0.0 │ Process View
  ──────────────────────────────────────────────────────────────────────

  ╭─ Processes ──────────────────────────────────────────── by CPU ────╮
  │  PID      NAME                        CPU       MEM               │
  │  ──────── ──────────────────────────  ────────  ──────             │
  │  1234     node                        ██████ 32.1%   4.2%         │
  │  5678     Google Chrome               ████   18.4%   8.1%         │
  │  9012     Code Helper (Plugin)        ███    12.2%   3.5%         │
  │  3456     WindowServer                ██      9.8%   2.1%         │
  │  7890     Safari                      ██      7.3%   5.4%         │
  │  2345     Spotlight                   █       3.2%   0.8%         │
  │  6789     Terminal                    █       2.1%   0.3%         │
  ╰───────────────────────────────────────────────────────────────────╯

  macpulse v1.0.0 │ Graph View
  ──────────────────────────────────────────────────────────────────────

  ╭─ CPU History ─────────────────────────────────────── (2 min) ─────╮
  │  100% ┤                                                           │
  │   75% ┤            ▄██▆▄                                          │
  │   50% ┤      ▂▃▅▆████████▆▅▃▂                                    │
  │   25% ┤  ▁▃▅██████████████████▆▅▃▂▁                              │
  │    0% ┤─────────────────────────────────────────                  │
  │  Current: 42%  Average: 38%  Peak: 87%                            │
  ╰───────────────────────────────────────────────────────────────────╯

  ╭─ Memory History ──────────────────────────────────── (2 min) ─────╮
  │  100% ┤                                                           │
  │   75% ┤                                                           │
  │   50% ┤  ████████████████████████████████████████                 │
  │   25% ┤  ████████████████████████████████████████                 │
  │    0% ┤─────────────────────────────────────────                  │
  │  Current: 49%  Average: 48%  Peak: 52%                            │
  ╰───────────────────────────────────────────────────────────────────╯

Quick Start

npm install -g macpulse
macpulse

That's it. No config files, no setup, no sudo. Just install and run.

For a one-time snapshot without entering the interactive UI:

macpulse --snapshot

What You Get

| Metric | Details | |---------|---------| | CPU | Total + per-core usage, load average, spike detection, sparkline history | | RAM | Used/free/pressure, app/wired/compressed/cache breakdown, swap usage | | GPU | Metal usage estimation, GPU model detection (Apple Silicon native) | | Disk | Read/write speed (bytes/sec), capacity usage with percentage | | Network | Download/upload rates (bytes/sec), active interface detection | | Battery | Charge %, health %, cycle count, charging status, time remaining |

Every metric updates every second. No polling lag, no stale data.

Controls

| Key | Action | |-----|--------| | ↑ / k | Navigate up (select previous panel) | | ↓ / j | Navigate down (select next panel) | | d | Toggle detailed mode | | p | Process view (top processes by CPU) | | g | Graph mode (sparkline history) | | l / Space | Toggle detail for selected panel | | q | Quit |

All keyboard shortcuts work instantly with zero input delay.

View Modes

Dashboard (default)

The compact overview mode. All six panels -- CPU, RAM, GPU, Disk, Network, Battery -- render simultaneously in a grid layout. Each panel shows the most critical metric at a glance: usage percentage, a compact progress bar, and key secondary stats.

Detailed (d)

Expanded panel mode with deep-dive information:

• CPU: Per-core utilization bars, processor model, clock speed, 1/5/15 min load averages
• Memory: Full breakdown of app, wired, compressed, and cached memory with swap usage and memory pressure indicator
• Disk: Read/write throughput rates alongside total/used/free capacity with a usage bar
• Battery: Charge level, battery health percentage, cycle count, charging state, and estimated time remaining

Process (p)

Top processes sorted by CPU usage. Displays up to 30 processes with:

• PID
• Process name
• CPU %
• Memory %

Equivalent to a focused top view without leaving macpulse.

Graph (g)

Sparkline history mode for CPU and RAM over the last 2 minutes (120 data points). Renders inline Unicode sparkline characters directly in the terminal -- no external graphing libraries needed.

CLI Options

macpulse              # Interactive dashboard (default)
macpulse --snapshot   # One-time snapshot, prints metrics and exits
macpulse -s           # Short alias for --snapshot
macpulse --help       # Show help and available commands
macpulse -h           # Short alias for --help

Snapshot Output Example

  macpulse snapshot

  CPU:     12% (10 cores)
  RAM:     11.2/16 GB (70%)
  GPU:     3%
  Disk:    45% used
  Battery: 87% ⚡

Architecture

┌─────────────────────────────────────────────┐
│              TUI Renderer (ANSI)            │
│  Alternate screen, raw mode, box drawing    │
└─────────────────┬───────────────────────────┘
                  │
┌─────────────────▼───────────────────────────┐
│         State Manager                       │
│  mode, selectedPanel, cpuHistory, memHistory│
└─────────────────┬───────────────────────────┘
                  │
┌─────────────────▼───────────────────────────┐
│           Metrics Engine                    │
│  collectAll() — aggregates all collectors   │
└─────────────────┬───────────────────────────┘
                  │
┌─────────────────▼───────────────────────────┐
│          macOS System APIs                  │
│                                             │
│  ├── os.cpus()         → CPU metrics        │
│  ├── vm_stat           → Memory pressure    │
│  ├── ioreg             → GPU (Metal)        │
│  ├── iostat / df       → Disk I/O & space   │
│  ├── netstat           → Network throughput  │
│  ├── pmset             → Battery status     │
│  └── ps                → Process list       │
└─────────────────────────────────────────────┘

macpulse uses zero npm runtime dependencies. Every metric is collected through Node.js built-in modules (os, child_process) calling native macOS command-line tools. This means:

• No native bindings to compile
• No node-gyp headaches
• Works on any Mac with Node 18+
• Instant install, instant run

Tech Stack

| Component | Technology | |-----------|-----------| | Language | TypeScript 5.5+ (strict mode) | | Runtime | Node.js 18+ | | Build | tsup (esbuild under the hood) | | Test | Vitest | | Type checking | tsc --noEmit | | Module format | CommonJS (for CLI compatibility) | | Terminal rendering | Raw ANSI escape sequences | | Metrics collection | Node.js os + child_process (execSync) | | Dependencies | Zero runtime dependencies |

What Makes macpulse Different

| Feature | top | htop | Activity Monitor | macpulse | |---------|-------|--------|-----------------|-------------| | Real-time dashboard | - | Partial | Yes | Yes | | GPU monitoring | No | No | Yes | Yes | | Battery health + cycles | No | No | No | Yes | | Memory pressure level | No | No | Yes | Yes | | Network throughput | No | Partial | Yes | Yes | | Disk I/O rates | No | No | Yes | Yes | | Sparkline graphs | No | No | No | Yes | | Keyboard navigation | Partial | Yes | Mouse only | Yes | | Terminal-native | Yes | Yes | No (GUI) | Yes | | Zero dependencies | Yes | No | N/A | Yes | | npm installable | No | No | No | Yes | | Cross-view modes | No | No | Tabs | Yes (d/p/g) | | Apple Silicon optimized | Partial | Partial | Yes | Yes |

macpulse combines the best of all worlds: the terminal-native simplicity of top, the interactivity of htop, the comprehensive metrics of Activity Monitor, and the modern developer experience of a TypeScript CLI tool.

macOS Specific Features

Memory Pressure

macOS manages memory differently than Linux. Instead of simple used/free, macOS uses a memory pressure system with three levels:

• Nominal (green): plenty of memory available, no compression or swapping
• Warn (yellow): system is actively compressing memory, performance may degrade
• Critical (red): heavy swapping, system may terminate background apps

macpulse reads the kernel memory pressure level directly via sysctl kern.memorystatus_vm_pressure_level and displays it alongside the traditional used/free breakdown.

Memory Breakdown

macpulse surfaces the four memory categories that macOS actually uses:

• App Memory: RAM actively used by running applications
• Wired Memory: RAM that cannot be compressed or paged out (kernel, drivers)
• Compressed: RAM that macOS has compressed in-place to free physical pages
• Cached: File-backed pages that can be reclaimed instantly

This gives you the same insight as Activity Monitor's Memory tab, right in your terminal.

Metal GPU Monitoring

Apple Silicon Macs use the Metal framework for GPU compute and rendering. macpulse detects your GPU model via ioreg and estimates GPU utilization by monitoring GPU-related system processes (WindowServer, MTLCompilerService). While this is an approximation (true GPU utilization requires sudo powermetrics), it provides a useful signal without requiring elevated privileges.

Battery Intelligence

macpulse reads battery data from pmset and ioreg to provide:

• Current charge percentage
• Battery health (maximum capacity vs. design capacity)
• Cycle count (how many full charge cycles the battery has completed)
• Charging status (charging, discharging, fully charged)
• Time remaining estimate (when available from macOS)

This is information that macOS makes surprisingly difficult to find -- normally buried in System Information or accessible only via ioreg commands.

Project Structure

macpulse/
├── src/
│   ├── index.ts              # Main entry point, interactive loop, CLI parsing
│   ├── metrics/
│   │   ├── cpu.ts            # CPU usage, per-core, load average
│   │   ├── memory.ts         # RAM, swap, pressure, vm_stat parsing
│   │   ├── gpu.ts            # Metal GPU detection and usage estimation
│   │   ├── disk.ts           # Disk I/O rates and capacity
│   │   ├── network.ts        # Network throughput via netstat
│   │   └── index.ts          # Barrel export, collectAll(), getTopProcesses()
│   └── ui/
│       └── index.ts          # ANSI renderer, dashboard layout, view modes
├── dist/                     # Compiled output (tsup)
├── package.json
├── tsconfig.json
├── tsup.config.ts
├── LICENSE
└── README.md

Development

# Clone the repository
git clone https://github.com/Worth-Doing/macpulse.git
cd macpulse

# Install dev dependencies
npm install

# Run in development mode (watch + rebuild)
npm run dev

# Run the CLI
npm start

# Type check
npm run typecheck

# Run tests
npm test

# Build for production
npm run build

Contributing

Contributions are welcome. macpulse is built and maintained by WorthDoing AI.

1. Fork the repository
2. Create a feature branch (git checkout -b feature/your-feature)
3. Commit your changes (git commit -m "Add your feature")
4. Push to the branch (git push origin feature/your-feature)
5. Open a Pull Request

Guidelines

• All code must pass npm run typecheck with zero errors
• Maintain zero runtime dependencies -- use only Node.js built-ins
• Test on both Apple Silicon and Intel Macs when possible
• Follow the existing code style (strict TypeScript, no any)

License

MIT -- Copyright (c) 2026 WorthDoing AI