Skip to content

AGENTS.md

Latest commit

 

History

History
80 lines (60 loc) · 2.31 KB

AGENTS.md

File metadata and controls

80 lines (60 loc) · 2.31 KB

AGENTS.md

Instructions for AI coding agents working on OSView.

Project Overview

OSView is a native macOS system monitoring app built with SwiftUI. It displays real-time CPU, Memory, GPU, Network, and Disk metrics in a floating panel widget. Inspired by the classic IRIX gr_osview tool.

Architecture

MVVM pattern with clear separation:

Models/          → Data structures (SystemMetrics.swift)
ViewModels/      → MetricsViewModel aggregates all monitors
Views/           → SwiftUI views, one per metric type
Services/        → Monitor classes wrapping system APIs
Utilities/       → Settings, FloatingPanel

Data flow:

System APIs (IOKit, Mach, Darwin)
    ↓
Services (CPUMonitor, MemoryMonitor, etc.)
    ↓
MetricsViewModel (@Published properties)
    ↓
Views (@ObservedObject)

Key Conventions

  • @MainActor on ViewModels and Settings
  • @unchecked Sendable on Monitor classes
  • Static .zero factory on all metric structs
  • Colors defined as static extensions on Color in Settings.swift
  • MARK comments to organize code sections

Adding a New Metric

  1. Define model in Models/SystemMetrics.swift
  2. Create monitor in Services/NewMonitor.swift
  3. Add @Published property to MetricsViewModel
  4. Create view in Views/NewView.swift
  5. Add visibility toggle to Settings.swift and SettingsView.swift
  6. Integrate in ContentView.swift

Important Files

Task Files
Metrics polling MetricsViewModel.swift
UI appearance Views/*.swift, Settings.swift
Window behavior FloatingPanel.swift, OSViewApp.swift
User preferences Settings.swift, SettingsView.swift

Dependencies

  • ProcessorKit - CPU usage (external Swift package)
  • IOKit - GPU and Disk stats
  • Darwin/Mach - Memory and Network stats

Build Commands

# Build release
xcodebuild -project OSView.xcodeproj -scheme OSView -configuration Release -derivedDataPath build clean build

# Output
build/Build/Products/Release/OSView.app

Guidelines

  • Keep views small and composable
  • Use MetricBarView, SegmentedBarView, CompactBarView for consistency
  • Metrics should have both raw values and computed percentages
  • Handle edge cases in rate calculations (elapsed time bounds, nil values)
  • Test with #Preview macros