Skip to content
CaptainSlothPublic

About

A lightweight macOS menu bar app that monitors CPU and memory usage of running processes, logging those that exceed configurable thresholds.

Resources

Stars

0 stars

Watchers

0 watching

Forks

Repository files navigation

Overseer

A lightweight macOS menu bar app that monitors CPU and memory usage of running processes, logging those that exceed configurable thresholds.

Quick Start

For Users (Pre-built App)

  1. Download Overseer.zip from releases
  2. Unzip and move Overseer.app to Applications
  3. Right-click → Open (first time only)
  4. Look for the eye icon (👁️) in your menu bar

See DISTRIBUTION.md for detailed installation instructions.

For Developers

# Clone the repo
git clone <repo-url>
cd Overseer

# Build from source
./build_app.sh

# Or run directly
swift run

# Or build and run
swift build && .build/debug/Overseer

Usage

First Launch

When you first launch Overseer:

  1. An eye icon (👁️) appears in your menu bar
  2. Green dot = monitoring active, Gray dot = paused
  3. Click the icon to open settings
  4. Adjust thresholds as needed

Settings Panel

  • CPU Threshold: Log processes using more than this % CPU (10-100%)
  • Memory Threshold: Log processes using more than this % of total RAM (10-100%)
  • Sampling Interval: How often to check processes (1-30 seconds)
  • Log Rate Limit: Maximum log frequency per process (1-60 seconds)

Right-Click Menu

  • Monitoring Status: Shows if monitoring is active or paused
  • Pause/Resume: Toggle monitoring on/off
  • Current Thresholds: Quick view of CPU and Memory thresholds
  • Open Logs Folder: Opens ~/Library/Logs/Overseer/ in Finder
  • Quit Overseer: Exit the application

Log Format

[2026-03-17 17:45:23] Chrome (1234): CPU=85.3%, MEM=2.1GB (duration: 15s)
[2026-03-17 17:45:28] Chrome (1234): CPU=87.1%, MEM=2.2GB (duration: 20s)

Each log entry includes:

  • Timestamp
  • Process name and PID
  • CPU usage percentage
  • Memory usage (MB or GB)
  • Duration process has been above threshold

Architecture

Core Components

  • ProcessMonitor: Main monitoring engine using proc_pidinfo() and task_info()
  • LoggerService: Asynchronous logging with rotation
  • ConfigurationManager: UserDefaults-based settings persistence
  • AppDelegate: Menu bar integration and app lifecycle
  • SettingsView: SwiftUI configuration interface

Low-Resource Strategy

  1. Smart Sampling: Only monitors top 20 processes by CPU
  2. Efficient APIs: Uses low-level BSD syscalls instead of parsing shell output
  3. Adaptive Polling: 5-second base interval
  4. Self-Monitoring: Automatically throttles if own usage exceeds 2% CPU

Configuration Files

Settings Storage

User preferences are stored in macOS UserDefaults:

~/Library/Preferences/com.overseer.app.plist

Log Location

~/Library/Logs/Overseer/
  ├── overseer-2026-03-17.log
  ├── overseer-2026-03-16.log
  └── ...

Logs automatically rotate daily and are retained for 30 days.

Troubleshooting

App Not Appearing in Menu Bar

  • Ensure you're running macOS 13.0 or later
  • Check that the app has accessibility permissions (System Settings > Privacy & Security > Accessibility)

No Logs Being Created

  • Check that ~/Library/Logs/Overseer/ directory exists
  • Verify monitoring is active (green dot in menu bar)
  • Ensure some processes are exceeding your thresholds

High Own CPU Usage

  • Increase sampling interval to 10-30 seconds
  • Increase log rate limit to reduce write frequency
  • Check logs for "WARNING: Overseer CPU usage high" messages

Development

Project Structure

Overseer/
├── Overseer/
│   ├── OverseerApp.swift          # App entry point
│   ├── AppDelegate.swift          # Menu bar and lifecycle
│   ├── Monitoring/
│   │   ├── ProcessMonitor.swift   # Core monitoring logic
│   │   └── ProcessInfo.swift      # Process data model
│   ├── Services/
│   │   ├── LoggerService.swift    # Async logging
│   │   └── ConfigurationManager.swift  # Settings management
│   └── UI/
│       ├── SettingsView.swift     # Main settings interface
│       └── MenuBarView.swift      # Menu bar popover (unused currently)
├── Package.swift                   # Swift Package Manager config
└── Overseer.xcodeproj/            # Xcode project

Adding Features

The app is designed to be extensible:

  • Add new metrics in ProcessMonitor
  • Extend log format in LoggerService
  • Add UI controls in SettingsView
  • Persist settings in ConfigurationManager

Future Enhancements

Potential features for future versions:

  • Historical graphs and charts
  • Multiple threshold profiles
  • Process killing from menu
  • Alert sounds or notifications
  • Network and disk I/O monitoring
  • Export logs to CSV
  • Launch at login option
  • Custom icon states (idle/alert)

License

This project is licensed under the PolyForm Noncommercial License 1.0.0. See the LICENSE file for details. This means you are free to use, modify, and share this code for personal or academic purposes, but commercial use is strictly prohibited.

Contributing

This is a personal project, but suggestions and feedback are welcome! CPU and Memory monitor

About

A lightweight macOS menu bar app that monitors CPU and memory usage of running processes, logging those that exceed configurable thresholds.

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages