If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/gao-sun/eul shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

WAIT — Stale — last commit 2y ago

• 14 active contributors
• MIT licensed
• CI configured
• ⚠ Stale — last commit 2y ago
• ⚠ Concentrated ownership — top contributor handles 58% of recent commits
• ⚠ No test directory detected

_{Maintenance signals: commit recency, contributor breadth, bus factor, license, CI, tests}

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live gao-sun/eul repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/gao-sun/eul.

What it runs against: a local clone of gao-sun/eul — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in gao-sun/eul | Confirms the artifact applies here, not a fork | | 2 | License is still MIT | Catches relicense before you depend on it | | 3 | Default branch master exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 744 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of gao-sun/eul. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/gao-sun/eul.git
#   cd eul
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of gao-sun/eul and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "gao-sun/eul(\\.git)?\\b" \\
  && ok "origin remote is gao-sun/eul" \\
  || miss "origin remote is not gao-sun/eul (artifact may be from a fork)"

# 2. License matches what RepoPilot saw
(grep -qiE "^(MIT)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"MIT\"" package.json 2>/dev/null) \\
  && ok "license is MIT" \\
  || miss "license drift — was MIT at generation time"

# 3. Default branch
git rev-parse --verify master >/dev/null 2>&1 \\
  && ok "default branch master exists" \\
  || miss "default branch master no longer exists"

# 4. Critical files exist
test -f "eul/App.swift" \\
  && ok "eul/App.swift" \\
  || miss "missing critical file: eul/App.swift"
test -f "eul/Views/ContentView.swift" \\
  && ok "eul/Views/ContentView.swift" \\
  || miss "missing critical file: eul/Views/ContentView.swift"
test -f "eul/Services/SMCService.swift" \\
  && ok "eul/Services/SMCService.swift" \\
  || miss "missing critical file: eul/Services/SMCService.swift"
test -f "eul/Models/CPUMonitor.swift" \\
  && ok "eul/Models/CPUMonitor.swift" \\
  || miss "missing critical file: eul/Models/CPUMonitor.swift"
test -f "eul/Models/MemoryMonitor.swift" \\
  && ok "eul/Models/MemoryMonitor.swift" \\
  || miss "missing critical file: eul/Models/MemoryMonitor.swift"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 744 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~714d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/gao-sun/eul"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

eul is a lightweight macOS status monitoring app built entirely in SwiftUI that displays real-time CPU, memory, battery, network, and Bluetooth device metrics in the menu bar and as Big Sur widgets. It directly reads system data via SMC (System Management Controller) calls and Darwin APIs to provide low-overhead hardware monitoring without background processes. Modular widget architecture: main app (eul/) provides the menu bar UI and settings in SwiftUI; four separate widget targets (BatteryWidget/, CpuWidget/, MemoryWidget/, NetworkWidget/) each implement WidgetKit providers for Big Sur compatibility. BuildTools/ manages build configuration, and shared system monitoring logic is likely in a common framework imported across targets.

macOS users (10.15+) who want a minimalist system monitoring tool in their menu bar; developers and power users who need to quickly check CPU/memory/battery without opening Activity Monitor; contributors interested in SwiftUI desktop applications and low-level macOS system APIs.

Actively maintained with a clean release history and Homebrew/App Store distribution. The project demonstrates production-quality UI with dark mode support and widget integration. However, it remains a relatively niche tool with limited test infrastructure visible, and the App Store version lags behind the latest releases due to SMC API restrictions.

Single-maintainer project (gao-sun) with potential SMC API deprecation risk on newer macOS versions. The codebase is Swift-only without comprehensive automated tests visible in the file list. Reliance on low-level system APIs (SMC, Darwin) means future macOS updates could break core functionality, as evidenced by App Store version disabling SMC features.

The project has CI/CD via GitHub Actions (.github/workflows/main.yml for builds, pr-label.yml for automation). Recent activity includes code formatting standards (.swiftformat) and contributor management (.all-contributorsrc), indicating active maintenance. The main branch appears to receive regular updates; check releases page for latest version activities.

Clone and open in Xcode: git clone https://github.com/gao-sun/eul.git && cd eul && open eul.xcodeproj. Select the 'eul' target and press Cmd+R to build and run the app on your macOS system. Widgets can be tested by selecting BatteryWidget/CpuWidget/MemoryWidget/NetworkWidget targets separately.

Daily commands: Open eul.xcodeproj in Xcode, select the 'eul' scheme, and press Cmd+R. The app installs to /Applications and appears as a menu bar icon. For widgets, build individual targets (CpuWidget, BatteryWidget, etc.) via Xcode's scheme selector to test in Notification Center.

• eul/App.swift — Main application entry point and root view hierarchy for the macOS status monitoring app
• eul/Views/ContentView.swift — Primary UI layout orchestrating all monitoring panels (CPU, Memory, Battery, Network, Disk)
• eul/Services/SMCService.swift — Core service for reading System Management Controller data (temperatures, fan speeds) via native APIs
• eul/Models/CPUMonitor.swift — Data model and monitoring logic for CPU usage metrics and statistics
• eul/Models/MemoryMonitor.swift — Memory usage tracking and statistics provider for system RAM monitoring
• BatteryWidget/BatteryWidget.swift — WidgetKit implementation for macOS Big Sur battery status widget
• .github/workflows/main.yml — CI/CD pipeline configuration for automated builds and releases

• CPUMonitor / MemoryMonitor / NetworkMonitor (Combine, libproc, IOKit) — Polls system APIs every ~1 second, aggregates metrics, publishes updates via Combine to UI subscribers
  • Failure mode: Stale data displayed; gaps in charts if polling thread hangs; high CPU usage if polling interval too aggressive
• SMCService (IOKit, SMC kernel driver) — Translates human-readable sensor keys into SMC opcodes, performs I/O control calls, parses binary SMC data structures
  • Failure mode: Temperature/fan data unavailable; disabled entirely in App Store builds; crashes if SMC key format changes

Add a new system monitoring metric

1. Create a new monitor class in eul/Models/ following the pattern of CPUMonitor.swift with @ObservedObject publisher for real-time updates (eul/Models/YourMetricMonitor.swift)
2. Implement system data collection using SMCService.swift or ProcessService.swift depending on data source (eul/Services/SMCService.swift)
3. Create a corresponding SwiftUI view in eul/Views/ to display the metric (eul/Views/YourMetricView.swift)
4. Add the new view to ContentView.swift within the main dashboard layout (eul/Views/ContentView.swift)

Add a new widget to macOS dashboard

1. Create new widget target folder (e.g., YourWidget/) with standard widget bundle structure (BatteryWidget/BatteryWidget.swift)
2. Implement WidgetKit entry point following BatteryWidget.swift pattern with Timeline and View providers (YourWidget/YourWidget.swift)
3. Configure widget entitlements and bundle identifiers matching main app (YourWidget/YourWidget.entitlements)
4. Update project.pbxproj to include new widget target in build phases (eul.xcodeproj/project.pbxproj)

Add Bluetooth device monitoring support

1. Extend BluetoothService.swift to query additional device properties or battery levels (eul/Services/BluetoothService.swift)
2. Update BatteryMonitor.swift to incorporate Bluetooth device battery data into aggregated metrics (eul/Models/BatteryMonitor.swift)
3. Enhance BatteryView.swift to display connected device battery levels alongside system battery (eul/Views/BatteryView.swift)

• SwiftUI — Modern declarative UI framework for macOS with automatic state management and real-time reactivity to monitoring data changes
• Combine Framework — Native iOS/macOS reactive streams library enabling efficient publishing of real-time system metrics from background monitors
• WidgetKit — macOS Big Sur native framework for lock screen and notification center widgets without requiring separate process
• System APIs (IOKit, libproc, IOHIDManager) — Direct access to SMC data, process information, and hardware metrics unavailable through high-level frameworks
• Swift Package Manager — Modular build system supporting multiple widget targets and shared code separation

• SMC direct access over high-level temperature APIs

  • Why: Provides granular fan speed and thermal sensor data unavailable through public frameworks
  • Consequence: Disabled in App Store version due to SMC entitlements restrictions; requires direct download for full functionality

• Native system APIs over third-party monitoring libraries

  • Why: Eliminates external dependencies, ensures maximum performance, and leverages Apple's official APIs
  • Consequence: Higher maintenance burden when macOS versions introduce API changes; requires intimate OS knowledge

• Separate widget targets over shared code approach

  • Why: WidgetKit requires independent app extensions with isolated bundle IDs for platform integration
  • Consequence: Code duplication across BatteryWidget, CPUWidget, MemoryWidget, NetworkWidget; potential drift in implementations

• Polling-based monitoring over event-driven notifications

  • Why: Simpler implementation for continuous real-time metrics; some hardware events lack notification APIs
  • Consequence: Higher CPU/battery overhead; configurable polling intervals to balance freshness and efficiency

• Does not support Linux or Windows (macOS-only status monitoring app)
• Does not provide remote monitoring or cloud sync capabilities
• Does not include persistent historical data logging or time-series analytics
• Does not support third-party plugin extensions
• Does not provide process management (kill, priority adjustment) in App Store version

SMC API calls require elevated privileges or special entitlements; the App Store version explicitly strips these for sandbox compliance, breaking some features. Widgets are separate targets that must be individually signed and provisioned—building just the main app won't include widgets in the final bundle. macOS version support: SwiftUI requires 10.15+, but Big Sur widgets (WidgetKit) need macOS 11+, creating compatibility branches. The app reads /var/run/sysctl* and Darwin IOKit interfaces which may be restricted in future macOS releases.

• WidgetKit (Big Sur Widgets) — eul's core value is displaying system stats in Notification Center; WidgetKit is the framework enabling this. Understanding TimelineProvider, IntentConfiguration, and widget refresh policies is essential to extending monitoring capabilities.
• System Management Controller (SMC) API — eul reads thermal, fan, and power data directly via SMC—a private Apple API. Understanding its capabilities and sandbox restrictions (why App Store version disables it) is critical for debugging and future-proofing.
• Darwin IOKit Framework — Underlying macOS API for hardware monitoring (CPU, memory, network interfaces). eul queries IOKit to get system metrics without polling slow system calls.
• SwiftUI Property Wrappers (@State, @StateObject, @Published) — eul is 'written in SwiftUI as much as possible'—mastering @State for UI updates, @StateObject for lifecycle management, and @Published with Combine for reactive data binding is essential to understanding the codebase.
• macOS Menu Bar (NSStatusBar) Integration — eul's primary UI paradigm is a persistent menu bar icon. Understanding how SwiftUI bridges to AppKit's NSStatusBar and NSMenu is crucial for UI modifications.
• App Sandbox and Entitlements — The gap between direct download (full SMC access) and App Store version (sandboxed, SMC disabled) hinges on entitlements. Understanding .entitlements files and why certain APIs are restricted is critical for release strategy.
• Combine Framework (Reactive Programming) — Real-time system monitoring requires async data updates. eul likely uses Combine Publishers and Subscribers to push metrics to UI without blocking the main thread.

• iina/iina — macOS media player written in Swift with similar focus on native UI patterns; good reference for SwiftUI + system API integration on desktop
• Carthage/Carthage — Dependency manager for macOS/iOS apps; relevant for managing frameworks if eul expands its build system
• mas-cli/mas — Command-line interface to the App Store for macOS; complements eul's distribution strategy and shows how to work with sandbox restrictions
• Whisper-Transcription/whisper-playground — SwiftUI macOS app example showing native Swift patterns; useful reference for menu bar and widget UI implementation
• sparkle-project/Sparkle — Standard macOS app auto-update framework; likely used or relevant for eul's release distribution outside the App Store

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add widget configuration persistence and testing for BatteryWidget, CpuWidget, MemoryWidget, and NetworkWidget

The four widget targets (BatteryWidget/, CpuWidget/, MemoryWidget/, NetworkWidget/) each have intentdefinition files and entitlements, but there's no visible test coverage for widget data refresh logic, data formatting, or configuration state management. Adding unit tests would ensure widgets correctly parse system metrics and handle edge cases (e.g., battery at 0%, maxed out CPU usage, no network activity).

• [ ] Create Tests/ directory at repo root with BatteryWidgetTests target
• [ ] Add unit tests in BatteryWidgetTests/ for battery percentage formatting and state updates
• [ ] Repeat for CpuWidgetTests/, MemoryWidgetTests/, NetworkWidgetTests/ covering metric parsing and bounds checking
• [ ] Update main.yml GitHub Action workflow to run widget tests on PR
• [ ] Reference .swiftformat in test files to maintain code style consistency

Create comprehensive widget integration tests in GitHub Actions workflow

The .github/workflows/main.yml and pr-label.yml workflows exist but likely don't validate that widgets build successfully or that widget entitlements/intentdefinitions are valid. Adding a dedicated build verification step would catch widget-specific regressions early (e.g., missing entitlements in BatteryWidget.entitlements preventing background refresh).

• [ ] Examine current main.yml workflow to identify missing xcodebuild steps for widget targets
• [ ] Add 'Build BatteryWidget' step: xcodebuild -scheme BatteryWidget -configuration Release
• [ ] Add 'Build CpuWidget', 'Build MemoryWidget', 'Build NetworkWidget' steps following the same pattern
• [ ] Add validation step to verify each widget's .entitlements and .intentdefinition files are valid plists
• [ ] Document widget build requirements in README.md (e.g., minimum macOS version per widget)

Refactor shared widget resources and create a WidgetCore framework

Each widget directory (BatteryWidget/, CpuWidget/, etc.) duplicates Assets.xcassets structure with AccentColor and WidgetBackground colorsets. Extracting common widget assets, color definitions, and data formatting utilities into a shared WidgetCore framework would reduce duplication, improve maintainability, and make widget styling updates a single-point change.

• [ ] Create new WidgetCore/ directory alongside existing widget targets
• [ ] Create WidgetCore/WidgetCore.xcodeproj with a framework target
• [ ] Move common AccentColor and WidgetBackground color assets from each widget into WidgetCore/Assets.xcassets
• [ ] Extract metric formatting utilities (bytes to GB, percentages, Mbps) into WidgetCore/Utilities/
• [ ] Update each widget's Package.swift or project file to depend on WidgetCore framework
• [ ] Remove duplicate colorset Contents.json files from BatteryWidget/, CpuWidget/, MemoryWidget/, NetworkWidget/

• Add unit tests for system data providers (CPU, memory, network stats). Create Tests/ folder and write XCTest cases for each metric fetcher to improve code reliability and catch API changes early.
• Expand localization: translations exist for Spanish, Russian, German, and French (.all-contributorsrc shows contributors), but many UI strings in eul/ likely need extraction to Localizable.strings; audit the codebase for hardcoded English strings and create .strings files for missing languages.
• Document the SMC API integration: write a guide in CONTRIBUTING.md explaining how the app reads temperature, fan speed, and power data via SMC, including code examples and explaining why this feature is unavailable on App Store builds. This will help future maintainers understand API deprecation risks.

The eul macOS monitoring application shows a generally good security posture for a system utility. The codebase is relatively small and focused on monitoring system metrics. Key observations: (1) No obvious hardcoded secrets or credentials detected in the visible file structure, (2) No SQL injection or XSS risks identified (Swift/SwiftUI app - not web-based), (3) Docker/infrastructure misconfiguration not applicable, (4) The main security concerns relate to visibility limitations: unreviewed entitlements files, unaudited Swift package dependencies, and Bluetooth permission handling. The removal of SMC calls in the App Store version suggests the direct version requires careful privilege management. Recommended actions: audit all entitlements, implement automated dependency scanning, review Swift package versions for known vulnerabilities, and ensure Bluetooth operations follow Apple security best practices.

• Medium · Missing Dependency Lock File Review — BuildTools/Package.swift, BuildTools/Package.resolved. The BuildTools/Package.resolved file exists but Swift Package Manager dependencies are not fully visible in the provided file structure. Without complete visibility of dependencies, potential vulnerable transitive dependencies could be missed. Fix: Regularly audit Swift package dependencies using swift package describe --type json and implement automated dependency scanning tools. Review Package.resolved for known vulnerabilities.
• Medium · Entitlements Not Reviewed in Analysis — BatteryWidget/BatteryWidget.entitlements, CpuWidget/CpuWidget.entitlements, MemoryWidget/MemoryWidget.entitlements, NetworkWidget/NetworkWidget.entitlements. Multiple .entitlements files are present (BatteryWidget.entitlements, CpuWidget.entitlements, MemoryWidget.entitlements, NetworkWidget.entitlements) but their content is not visible. These define security-sensitive permissions for the application and widgets. Fix: Review all .entitlements files to ensure only necessary permissions are requested. Verify no unnecessary capabilities are enabled (e.g., network access, file system access beyond requirements).
• Low · Potential Information Disclosure via Bluetooth — BatteryWidget/. The application explicitly handles Bluetooth battery levels according to the README highlights. While this is a legitimate feature, Bluetooth communication should ensure proper pairing and authentication to prevent unauthorized access to device information. Fix: Ensure Bluetooth operations follow Apple's security guidelines. Validate that Bluetooth connections are authenticated and encrypted. Only pair with authorized devices.
• Low · SMC Access Removed in App Store Version — README.md - App Store installation notes. According to the README, the App Store version has 'all SMC calls' removed. While this is mentioned as a limitation, it indicates the direct macOS binary version may have elevated privileged access that could be abused if the application is compromised. Fix: For the direct release version with SMC access, implement strict input validation and error handling around SMC calls. Consider further sandboxing and request minimization for privileged operations.

LLM-derived; treat as a starting point, not a security audit.

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.