# puter A native macOS system monitor written in SwiftUI and inspired by Windows 11 Task Manager. Validated with automated tests, debug and release builds, packaged-app code-signature checks, and hands-on UI regression through macOS accessibility and screenshots. ## Features - Live process list with CPU, memory, disk I/O, and network usage - Cached native application icons throughout process groups, app history, startup apps, users, services, properties, and dependency views - Search and sortable process columns, including live Disk and Network rates - Drag-resizable, persisted Processes columns with memory hover details showing both resident bytes and physical-memory percentage - Process headers cycle through descending, ascending, and unsorted states; the third click restores Windows-style process categories - Expandable application groups plus a resizable Details table with application icons, persisted optional columns, live selection actions, threads, open handles, architecture, priority/nice, parent PID, CPU time, and other diagnostics - Collapsible Windows-style Apps, Background processes, and macOS processes categories - Native process sampling reports from the Inspect submenu, with save-location memory and completion feedback - Persistent preferences for the default start page, Performance selection and CPU graph mode, update speed, always-on-top behavior, and process/detail table layouts - Expandable application groups with aggregate metrics and individual child processes - Group-wide right-click controls for ending, pausing, resuming, reprioritizing, copying, and inspecting related processes - Nested right-click menus for process control, priority, copying, inspection, and properties - Graceful termination, force quit, process-tree termination, pause, and resume actions - CPU and memory history charts - Right-click CPU graph switching between summary and live per-core views - Live network receive/send throughput with an auto-scaling 60-second chart - Persistent per-app history with cumulative CPU time, network totals, download/upload breakdowns, and reset confirmation - Disk, uptime, process, and thread statistics - One live Performance entry per available removable volume, with capacity, availability, filesystem, mount point, and ejectable status; disconnected volumes are hidden - Physical-disk health inventory with one card per attached disk and macOS-reported SMART status, NVMe wear/life, spare capacity, temperature, TRIM, power hours/cycles, unsafe shutdowns, media errors, and lifetime reads/writes - Detailed memory telemetry for active, cached, wired, compressed, and swap usage plus hardware type, manufacturer, and reported speed/frequency - Kernel-driven Normal/Warning/Critical memory-pressure status with plain-language guidance; reclaimable cache is no longer misreported as application memory in use - A maintained M1-through-M5 Apple-silicon memory catalog, including core-count configuration variants; Intel Macs continue to use DIMM speeds reported directly by System Information - Native disk read/write throughput, IOPS, active time, and response-time histories - Live Apple GPU utilization with overall, renderer, and tiler histories plus GPU memory and core statistics - Hardware diagnostics for battery health, capacity, cycle life, temperature, charge state, live SMC-backed system/battery/adapter watts, thermal pressure, USB-PD negotiation and advertised power profiles - Energy & Sleep dashboard with transparent CPU/disk/network-based process impact estimates, active power policy, sleep timers, and the processes currently preventing idle sleep - Event-driven lifecycle, application, mount, wake, thermal, memory-pressure, and power-source refreshes backed by independent adaptive telemetry, process-inventory, hardware, and service lanes; pages such as Hardware, Startup, Services, and Settings reuse cached processes and run only lightweight native system telemetry between process events - USB-C, USB, and Thunderbolt port inventory with negotiated link speeds, connected-device power requirements, and an optional available-port map - User, detail, service, persistent app history, and startup views covering LaunchAgents immediately, with an explicit on-demand scan of the modern macOS background-task registry - Estimated live startup impact with Low, Medium, and High classifications and detailed CPU/memory/disk evidence - Combined user and system launchd Services registry with scope filtering, running/stopped state, safe Start/Stop/Restart controls, protected-system labeling, configuration reveal, Details, and Properties actions - Process dependency inspector with relationship chains, network/local sockets, canonical framework dependencies, open files, and handle totals - On-demand process security inspector using Security.framework and Gatekeeper for signature validity, signing identity/team/authority, CDHash, hardened runtime, sandbox/debug entitlements, quarantine, and assessment status - Persistent Resource values submenu for switching memory, disk, and network cells between values and percentages - Signed-in Users sessions with active-state and aggregate resources plus Lock, home-folder, account-management, Copy, Details, and Properties actions - Configurable 1/5/10-second diagnostic samples with remembered folders and optional automatic timestamped output - Run New Task sheet and persistent update-speed settings - Persistent expanded and compact navigation: one native macOS `NavigationSplitView` and sidebar `List` narrow in place, hiding only the brand and row labels while preserving selection, material, keyboard behavior, and the divider - Native macOS menus, toolbar, light/dark mode, and accessibility behavior - Per-resource top-process panels on Performance with application icons, owning users, and live CPU, memory, disk, or network values - Native JSON export of performance, process, user, battery, power-delivery, thermal, and connected-hardware snapshots - Bounded telemetry session recording with start/stop controls and JSON or CSV export of CPU, memory pressure, disk, GPU, network, power, thermals, and process counts - Configurable sustained CPU, memory, disk, and thermal alerts with consecutive-sample gating, notification permission handling, cooldowns, foreground banners, and recent alert history - Persistent on-demand diagnostic captures with current system, memory-pressure, storage-health, and top-process evidence; select one for inspection or two for before/after delta comparison and JSON export - Integrated SMC fan telemetry and safe in-app cooling controls with per-fan RPM ranges, manual targets, and one-click return to macOS automatic management - Optional menu-bar monitor for CPU, memory, network, or power that reuses the shared sampler rather than starting another polling loop - Command-limited `SMAppService` launch-daemon helper for fan writes, with same-Team-ID client validation, bounded fan/RPM inputs, explicit enable/disable status, and no arbitrary shell-command interface - Sparkle 2 automatic update support with EdDSA-verified appcasts; unsigned validation builds clearly show when release update credentials are not configured ## Run Open `Package.swift` in Xcode and press Run, or use: ```sh swift run ``` To create a standard double-clickable app bundle: ```sh ./scripts/build-app.sh open "dist/puter.app" ``` To create a drag-to-install disk image containing the app and an Applications shortcut: ```sh ./scripts/build-app.sh ./scripts/build-dmg.sh ``` To run the same structural, signature, Hardened Runtime, icon, Sparkle, helper, and mounted-DMG checks used by CI: ```sh ./scripts/validate-package.sh ``` ### Signed and notarized releases `build-app.sh` produces a Hardened Runtime validation build by default. For a public release, provide a Developer ID Application identity and a notarytool keychain profile: ```sh export PUTER_SIGN_IDENTITY='Developer ID Application: Your Name (TEAMID)' export PUTER_NOTARY_PROFILE='puter-notary' export PUTER_UPDATE_FEED_URL='https://your-host.example/puter/appcast.xml' export PUTER_UPDATE_PUBLIC_KEY='SPARKLE_EDDSA_PUBLIC_KEY' ./scripts/build-app.sh ./scripts/build-dmg.sh ./scripts/notarize-release.sh ``` The release runner must also provide the Stats-derived `smc` backend through `PUTER_SMC_SOURCE` or have Stats installed at `/Applications/Stats.app`. Release validation deliberately fails if live SMC power and fan support would be missing. The fan helper is embedded at `Contents/Resources/puter-helper` and its launchd property list at `Contents/Library/LaunchDaemons`. macOS will not register an ad-hoc helper; test registration from the Developer ID-signed app after placing it in Applications. To generate or update a signed Sparkle appcast from release archives: ```sh export PUTER_UPDATE_DOWNLOAD_PREFIX='https://your-host.example/puter/releases/' export PUTER_SPARKLE_PRIVATE_KEY='SPARKLE_EDDSA_PRIVATE_KEY' ./scripts/generate-appcast.sh dist/updates ``` Keep the Sparkle private key and notarization credentials outside the repository. The Gitea build workflow runs compile, unit, native-sampler performance, app-signature, mounted-DMG, helper, icon, and update-framework checks. Tag releases additionally require the Developer ID certificate, notary API key, Sparkle signing keys, release token, and SMC backend. A successful tag publishes the notarized DMG, stapled app ZIP, signed appcast, and SHA-256 checksum manifest. See [RELEASE_CHECKLIST.md](RELEASE_CHECKLIST.md) for the credential inventory, signed workflow, independent-machine verification, and release acceptance criteria. Live CPU and rate metrics still require coordinated sampling, now using native Mach/libproc, virtual-memory, network-interface, and System Configuration APIs on the hot path. Foreground cadence follows the selected update speed where useful, while background, hardware, service, process-diagnostic, device, port, and persistence work runs independently at slower demand-aware intervals. Some system-owned processes cannot be ended without elevated permissions.