puter/README.md

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:

swift run

To create a standard double-clickable app bundle:

./scripts/build-app.sh
open "dist/puter.app"

To create a drag-to-install disk image containing the app and an Applications shortcut:

./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:

./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:

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:

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 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.