Repository Public License
1<!--2ORIX Monitor3File: README.md4Author: Simon-Pierre Boucher5Contact: contact@spboucher.ai6-->78<div align="center">910<img src="docs/assets/icon.png" alt="ORIX Monitor icon" width="168" height="168">1112# ORIX Monitor1314**Understand Every Pulse of Your Mac.**1516A native macOS system monitor that shows what your Mac is really doing — CPU, GPU, memory, storage, network, processes,<br>17power and thermal state — with the source of every number, a local history, alerts, findings and reports.<br>18Every metric is measured. Everything the system does not expose is said to be unavailable, never invented.1920**Author: [Simon-Pierre Boucher](https://www.spboucher.ai)**21222324252627282930-F59E0B?style=flat-square)3132333435363738-06B6D4?style=flat-square)394041<br>4243<img src="docs/screenshots/dashboard-dark.png" alt="ORIX Monitor dashboard in Dark Mode, showing live CPU, memory, GPU, thermal state, battery, network and disk activity" width="920">4445<sub>The dashboard on a MacBook Pro (M5 Max). Every figure in every screenshot of this page is a live reading captured from the signed app; none is staged.</sub>4647</div>4849<div align="center">5051### [⬇ Download ORIX Monitor 1.0.0 (DMG, 3.5 MB)](https://git.spboucher.ai/releases/orix-monitor/v1.0.0/ORIX-Monitor-1.0.0.dmg)5253[ZIP](https://git.spboucher.ai/releases/orix-monitor/v1.0.0/ORIX-Monitor-1.0.0.zip) · [SHA-256 checksums](https://git.spboucher.ai/releases/orix-monitor/v1.0.0/SHA256SUMS.txt) · [Release notes](https://git.spboucher.ai/releases/orix-monitor/v1.0.0/RELEASE-NOTES.md) · [All releases](https://git.spboucher.ai/orix-monitor/releases)5455</div>5657> **Badge values are not live.** They are static and were written from the runs recorded in58> [`RELEASE-REPORT.md`](RELEASE-REPORT.md) on 2026-11-21.5960---6162## Contents63641. [Overview](#1-overview) · 2. [Product philosophy](#2-product-philosophy) · 3. [Application preview](#3-application-preview) ·654. [System dashboard](#4-system-dashboard) · 5. [CPU](#5-cpu-monitoring) · 6. [GPU](#6-gpu-monitoring) · 7. [Memory](#7-memory-monitoring) ·668. [Disk](#8-disk-monitoring) · 9. [Network](#9-network-monitoring) · 10. [Processes](#10-process-explorer) · 11. [Power](#11-power-and-battery) ·6712. [Thermal](#12-thermal-monitoring) · 13. [Menu bar](#13-menu-bar) · 14. [History](#14-historical-telemetry) · 15. [Alerts](#15-alerts) ·6816. [Insights](#16-performance-intelligence) · 17. [Reports](#17-reports) · 18. [Metric sources](#18-metric-sources) ·6919. [Metric availability](#19-metric-availability) · 20. [Technology stack](#20-technology-stack) · 21. [Architecture](#21-architecture) ·7022. [Installation](#22-installation) · 23. [Build](#23-build-instructions) · 24. [Testing](#24-testing) · 25. [Benchmarks](#25-benchmarks) ·7126. [Overhead](#26-performance-overhead) · 27. [Privacy](#27-privacy) · 28. [Accessibility](#28-accessibility) · 29. [Localization](#29-localization) ·7230. [Roadmap](#30-roadmap) · 31. [Release status](#31-release-status) · 32. [Known limitations](#32-known-limitations) ·7333. [ORIX ecosystem](#33-orix-ecosystem) · 34. [License](#34-license)7475---7677## 1. Overview7879ORIX Monitor is one application that does the work of an activity monitor, a menu bar meter, a history recorder and a80diagnostic report tool.8182| It gives you | How |83|---|---|84| A live picture of the Mac | 13 pages: overview dashboard, CPU, GPU, memory, disk, network, processes, power, thermal, history, insights, alerts, reports |85| A memory | A local SQLite time-series store with three retention tiers (every sample, per-minute, per-hour) |86| Answers | Findings derived from stored history, each with its evidence, threshold, duration and a suggested next step |87| Warnings | Alert rules with a hold time, cooldown and snooze; Notification Center is optional |88| Something to hand over | Reports in PDF, Markdown, CSV and JSON, listing units, methods, sampling and data gaps |89| A glance | A configurable menu bar item with mini charts and a quick panel |9091It is written in Swift 6 with SwiftUI and Swift Charts, uses only Apple frameworks, runs without an account, without92administrator rights and without any network connection of its own.9394## 2. Product philosophy95961. **Measured or absent.** A number is shown only if a system interface produced it. There are no simulated sensors, no97 decorative gauges and no placeholder controls.982. **Every value says where it comes from.** Each page ends with its sources and methods, read from the same catalogue the99 code uses ([`Metric.swift`](Packages/ORIXMonitorCore/Sources/ORIXMonitorCore/Metrics/Metric.swift)).1003. **Four honest labels.** *Measured*, *Derived*, *Estimate*, *Best effort*. "Best effort" marks values read through a101 public API from a property whose name Apple does not document; they can be switched off in one place.1024. **Unknown is not zero.** A process whose statistics macOS withholds shows "—", not 0 %. The first sample after sleep has103 no rate rather than one giant rate.1045. **A monitor must be light.** One sampling loop, tiered intervals, buffered writes, and its own CPU and memory are105 measured and shown like any other process ([§26](#26-performance-overhead)).1066. **Nothing leaves the Mac.** No telemetry, no advertising, no update check. See [§27](#27-privacy).107108## 3. Application preview109110<table>111<tr>112<td width="50%"><img src="docs/screenshots/dashboard-dark.png" alt="Dashboard, Dark Mode"><br><sub><b>Dark Mode</b> — the Overview layout.</sub></td>113<td width="50%"><img src="docs/screenshots/dashboard-light.png" alt="Dashboard, Light Mode"><br><sub><b>Light Mode</b> — same layout, text colours tuned to at least 4.5:1 contrast.</sub></td>114</tr>115<tr>116<td><img src="docs/screenshots/cpu.png" alt="CPU page, Dark Mode"><br><sub>CPU, Dark Mode.</sub></td>117<td><img src="docs/screenshots/cpu-light.png" alt="CPU page, Light Mode"><br><sub>CPU, Light Mode.</sub></td>118</tr>119<tr>120<td><img src="docs/screenshots/dashboard-performance.png" alt="Performance dashboard preset"><br><sub>The built-in <b>Performance</b> layout.</sub></td>121<td><img src="docs/screenshots/dashboard-fr-CA.png" alt="Dashboard in French (Canada)"><br><sub><b>Français (Canada)</b>, with locale-aware numbers and units.</sub></td>122</tr>123</table>124125Screenshots are produced by [`Scripts/screenshots.sh`](Scripts/screenshots.sh) from an isolated instance of the signed126Release app. The privacy mask is on, so addresses, host and user names appear as "•••". How each image was made, and the127two that are not window captures, is stated in [`docs/screenshots/README.md`](docs/screenshots/README.md).128129## 4. System dashboard130131<img src="docs/screenshots/dashboard-dark.png" alt="System dashboard" width="900">132133- **14 widgets**: CPU, CPU cores, GPU, memory, storage, disk activity, network, battery, thermal state, top processes by134 CPU, top processes by memory, system (uptime, process count, load), alerts, ORIX Monitor's own overhead.135- **Customisable**: *Edit* shows controls to add, remove, resize (small, wide, full width) and reorder widgets, by menu or136 by drag and drop.137- **Layouts**: three built-in presets (Overview, Performance, Compact), "Save Layout As…", reset to default, delete.138- **Several displays**: *Monitor › New Dashboard Window* (⇧⌘D) opens any layout in its own window.139- The grid reflows from four columns to one as the window narrows.140141## 5. CPU monitoring142143<img src="docs/screenshots/cpu.png" alt="CPU page: total usage, user and system time, per-core bars, core activity heatmap" width="900">144145| Metric | Source | Notes |146|---|---|---|147| Total, user, system, idle | `host_processor_info(PROCESSOR_CPU_LOAD_INFO)` | Tick deltas summed over all cores; **100 % = every core busy** |148| Per-core usage | same | Bars and a core × time heatmap of the live window |149| Load average (1, 5, 15 min) | `getloadavg` | As reported |150| Peak and average of the live window | derived | Last 150 samples |151| Sampling interval | measured | Configured interval and the interval actually measured for the last sample |152| Process contribution | `proc_pid_rusage` | **100 % = one core**, as in Activity Monitor |153| Core groups | `sysctl hw.perflevelN` | Count per performance level ("6 Super · 12 Performance" on an M5 Max) |154155Cores are shown by number, unlabelled: macOS publishes how many cores each performance level has, not which core index156belongs to which level, so ORIX Monitor does not guess. CPU frequency is not published on Apple Silicon and is listed as157unavailable. Details: [`docs/metrics/cpu.md`](docs/metrics/cpu.md).158159## 6. GPU monitoring160161<img src="docs/screenshots/gpu.png" alt="GPU page: best-effort utilization, explanation of the figure, Metal device capabilities" width="900">162163macOS has **no supported API for system-wide GPU utilization**. ORIX Monitor therefore splits the page in two:164165- **Documented (Metal)**: device name, unified memory, recommended working set, largest buffer, ray tracing support,166 low-power / removable / headless flags.167- **Best effort (IORegistry)**: device, renderer and tiler utilization, GPU core count and driver memory figures, read with168 a public IOKit call from the `IOAccelerator` service's `PerformanceStatistics` property — a name Apple does not document.169 The values are shown exactly as published, carry a "Best effort" badge everywhere, and disappear when *Settings ›170 Sampling › Read undocumented system properties* is off.171172Per-process GPU usage, GPU temperature and GPU power are listed as not available. Details:173[`docs/metrics/gpu.md`](docs/metrics/gpu.md).174175## 7. Memory monitoring176177<table><tr>178<td width="50%"><img src="docs/screenshots/memory.png" alt="Memory page, Dark Mode"></td>179<td width="50%"><img src="docs/screenshots/memory-light.png" alt="Memory page, Light Mode"></td>180</tr></table>181182| Term | What ORIX Monitor shows |183|---|---|184| Physical memory | Installed RAM (`hw.memsize`). *Used + cached files + free* always equals it |185| Used | App memory + wired + compressed (Activity Monitor's convention) |186| App memory | (internal − purgeable pages) × page size |187| Compressed | RAM occupied by the compressor — not the size of the data before compression |188| Cached files | File-backed and purgeable memory the system can reclaim |189| Pressure | The kernel's own level: normal, warning, critical |190| Swap | Used and allocated (`vm.swapusage`); it is disk space, not part of physical memory |191| Paging | Page-ins, page-outs, swap-ins, swap-outs per second |192| Virtual memory | Deliberately not shown: reserved address space says nothing about RAM in use |193194Details and formulas: [`docs/metrics/memory.md`](docs/metrics/memory.md).195196## 8. Disk monitoring197198<img src="docs/screenshots/disk.png" alt="Disk page: volumes, throughput, available-space trend, block devices" width="900">199200- **Volumes** (logical): name, format, capacity, space available including what macOS can purge, space free without201 purging, startup / read-only / removable tags, BSD name and the container it lives in.202- **Block devices** (physical): model, connection, size, read and write throughput, totals since boot, from203 `IOBlockStorageDriver` statistics. Disk images are listed but excluded from totals, since their I/O already appears on the204 device that holds them.205- **Trend** of available space on the startup volume, which also feeds the "volume is filling up" finding.206- **Not shown**: SSD health, wear and temperature. NVMe SMART data is reachable only through privileged or private207 interfaces, so ORIX Monitor shows none.208209Details: [`docs/metrics/disk.md`](docs/metrics/disk.md).210211## 9. Network monitoring212213<img src="docs/screenshots/network.png" alt="Network page: throughput, Wi-Fi link, DNS and routing, interfaces" width="900">214215- **Throughput** from 64-bit interface counters (`sysctl NET_RT_IFLIST2`). Totals add Wi-Fi, Ethernet and cellular; VPN216 tunnels are listed but not added, because their traffic already crosses one of those links.217- **Interfaces**: Wi-Fi, Ethernet, VPN / tunnel, bridge, loopback and others, with status, addresses, rates, totals, errors.218- **Wi-Fi link**: RSSI, noise, signal-to-noise, link rate, channel, band, PHY mode (CoreWLAN). The network name is not219 read: it requires Location Services, which ORIX Monitor never requests.220- **DNS and routing**: primary interface, router, DNS servers, search domains (SystemConfiguration).221- **Latency test**: five TCP handshakes to a host you type, only when you press the button. It is the only network traffic222 the app ever creates.223- **Change log**: connected / disconnected events from `NWPathMonitor`.224- **Not shown**: per-process traffic. It needs a network extension or a private framework; ORIX Monitor intercepts nothing.225226Details: [`docs/metrics/network.md`](docs/metrics/network.md).227228## 10. Process explorer229230<img src="docs/screenshots/processes.png" alt="Process explorer: sortable table with CPU, memory, threads, CPU time, power, and the inspector" width="900">231232- Sortable table: name, PID, CPU, memory (physical footprint), threads, CPU time, power, user, start time.233- Filters (my processes, apps, other users, all) and search by name, PID or path.234- Inspector for the selected process with a live CPU and memory history kept **only while it is selected**, disk bytes read235 and written, parent process and executable path.236- Actions: Reveal in Finder, Bring to Front, Copy PID, **Quit…** and **Force Quit…** — only for your own processes, always237 behind a confirmation that names the process and explains the consequence. ORIX Monitor never ends a process on its own.238- Processes of other users (root and system accounts) are listed with their identity only. macOS refuses their statistics239 to an unprivileged app, and ORIX Monitor installs no privileged helper to get around that.240241## 11. Power and battery242243<img src="docs/screenshots/power.png" alt="Power page: battery charge, health, power flow, energy by process" width="900">244245| Value | Source | Label |246|---|---|---|247| Charge, charging state, power source | IOKit power sources | Measured |248| Time remaining / until full | IOKit power sources | Estimate (the system's own) |249| Low Power Mode | `ProcessInfo` | Measured |250| Adapter wattage | `IOPSCopyExternalPowerAdapterDetails` | Measured |251| Cycle count, full-charge and design capacity | `AppleSmartBattery` registry entry | Best effort |252| Battery flow (V × A), system load | same | Best effort |253| Power by process | kernel energy accounting (`ri_billed_energy`) | An accounting figure for comparing processes |254255Battery flow is the power entering or leaving the battery, not what the Mac draws from the wall. Desktop Macs expose no256power figure through supported interfaces; on a Mac without a battery the page says so. Details:257[`docs/metrics/power.md`](docs/metrics/power.md).258259## 12. Thermal monitoring260261<img src="docs/screenshots/thermal.png" alt="Thermal page: thermal state, unavailable sensors, availability matrix for this Mac" width="900">262263- **Thermal state** (nominal, fair, serious, critical) from `ProcessInfo.thermalState`, with its history.264- **CPU temperature, GPU temperature, fan speed**: shown as **"Not available through supported system interfaces."** They265 exist only behind the System Management Controller and private sensor services, which differ between models and break266 between releases. ORIX Monitor does not use them.267- **Battery temperature**: shown as best effort when the battery gauge publishes it. On macOS 27 on the test Mac it does268 not, and the page says so.269- **Availability matrix**: a table, probed on *this* Mac at launch, of every metric with its access class and whether it270 could actually be read.271272Details: [`docs/metrics/thermal.md`](docs/metrics/thermal.md).273274## 13. Menu bar275276<table><tr>277<td width="42%" align="center"><img src="docs/screenshots/menubar-panel.png" alt="Menu bar panel" width="330"></td>278<td>279<img src="docs/screenshots/menubar-item.png" alt="Menu bar item with CPU, memory, network, disk and battery indicators" width="460"><br><br>280281- Indicators: CPU, memory, network, disk activity, battery — each can be hidden. With all of them off, the ORIX pulse mark282 remains alone.283- Mini charts (optional), and a dot when an alert is active.284- Drawn as a single template image, so macOS tints it for light, dark and highlighted menu bars.285- The panel shows live tiles, active alerts, top processes, pause / resume, and opens the full window.286- While only the menu bar is showing, sampling drops to the slower background interval.287288<sub>The capture Mac hides the status item behind its notch, so the panel above is the real panel shown in a plain window,289and the item strip is the image the app draws for the menu bar, written to a file. See290<a href="docs/screenshots/README.md">docs/screenshots/README.md</a>.</sub>291</td>292</tr></table>293294## 14. Historical telemetry295296<img src="docs/screenshots/history.png" alt="History page: stored CPU usage over an hour with minimum, average, maximum, sample count and gaps" width="900">297298| Tier | Holds | Default retention |299|---|---|---|300| Raw | Every sample | 6 hours |301| Minute | Minimum, average, maximum, count per minute | 14 days |302| Hour | Same, per hour | 2 years |303304- Ranges from 1 hour to 1 year; the store answers from the finest tier that covers the range and downsamples to the chart305 width while keeping minima and maxima.306- Compare two metrics, read any point with the pointer, export the chart as PNG or the data as CSV.307- **Gaps are shaded, never filled.** History exists only while ORIX Monitor runs; sleep, pauses and quits appear as holes,308 and lines are not drawn across them.309- Bookmarks mark a moment so it can be found again.310- Retention is adjustable; history can be erased or recording turned off in Settings.311312Details: [`docs/architecture/storage.md`](docs/architecture/storage.md).313314## 15. Alerts315316<img src="docs/screenshots/alerts.png" alt="Alerts page: active alerts, notifications and snooze, rule list, history" width="900">317318- Rules on CPU, memory pressure, memory, swap, available space, disk and network throughput, battery, thermal state, GPU.319- Each rule has a threshold, a **hold time** (how long the condition must last), a **cooldown** (how long before it may fire320 again) and a severity.321- **Snooze** for 15 minutes, 1 hour or 8 hours; alert history; alerts in the menu bar; Notification Center only if you322 enable it. One sustained problem produces one alert.323- Time spent asleep or paused never counts toward a hold time.324325Details: [`docs/architecture/alerts.md`](docs/architecture/alerts.md).326327## 16. Performance intelligence328329<img src="docs/screenshots/insights.png" alt="Insights page: findings with their evidence, and the list of checks" width="900">330331Findings are computed from the last 24 hours of stored history. Each carries the metric, start, duration, threshold, peak,332mean and number of samples behind it, an explanation and a suggested action.333334| Finding | Evidence required |335|---|---|336| Sustained high CPU | Average above 85 % for 10 minutes or more |337| Elevated memory pressure | Warning or critical for 5 minutes or more |338| Swap growth | 2 GB or more within the window |339| Startup volume filling up | A consistent decline over at least 6 hours projecting a full volume within 30 days — labelled as an estimate |340| Unusual network volume | Minutes far above the series' own typical level and above an absolute floor |341| Repeated process spikes | A process holding a full core for 30 s, three times or more |342| Thermal pressure | Serious or critical for a minute or more |343344A single unusual reading never produces a finding, a hole in the data ends an episode instead of extending it, and no345finding claims a hardware fault.346347## 17. Reports348349<img src="docs/screenshots/reports.png" alt="Reports page: report type, period, export formats, comparison, preview" width="900">350351Seven report types (system overview, CPU, memory, storage, network, process activity, performance incident) in four352formats:353354| Format | Contains |355|---|---|356| PDF | Tables plus a chart per metric with its min–max band, gaps shaded |357| Markdown | The full report as text |358| CSV | Every stored bucket in long format, dot decimals, ISO 8601 timestamps |359| JSON | The complete report; two JSON reports can be **compared** side by side |360361Every report lists measurement units, collection methods, timestamps, the sampling interval, data gaps and limitations.362The host name is excluded unless you opt in; reports never contain a serial number, IP addresses or user names. Details:363[`docs/architecture/reporting.md`](docs/architecture/reporting.md).364365## 18. Metric sources366367| Area | Interfaces |368|---|---|369| CPU | `host_processor_info`, `getloadavg`, `sysctl hw.*` |370| Memory | `host_statistics64(HOST_VM_INFO64)`, `sysctl vm.swapusage`, `kern.memorystatus_vm_pressure_level` |371| Disk | `FileManager` / `URLResourceValues`, DiskArbitration, IOKit `IOBlockStorageDriver` statistics |372| Network | `sysctl NET_RT_IFLIST2`, `getifaddrs`, SystemConfiguration, CoreWLAN, Network framework |373| Processes | libproc: `proc_listallpids`, `proc_pidinfo`, `proc_pid_rusage`, `proc_pidpath` |374| Power | IOKit power sources, `ProcessInfo`; best effort: `AppleSmartBattery` registry entry |375| Thermal | `ProcessInfo.thermalState` |376| GPU | Metal; best effort: `IOAccelerator` registry entry |377378No private framework, no SMC access, no kernel extension, no `powermetrics`, no shell command at run time. The formula of379every stored metric is in [`docs/metrics/`](docs/metrics) and in the app at the bottom of each page.380381## 19. Metric availability382383Condensed from [`docs/research/macos-capability-matrix.md`](docs/research/macos-capability-matrix.md):384385| Class | Examples | What ORIX Monitor does |386|---|---|---|387| Public API | CPU load, memory accounting, volumes, disk and network throughput, thermal state, battery charge | Shows it |388| Estimate | Time remaining, projected date a volume fills | Shows it with an "Estimate" badge |389| Best effort | GPU utilization, cycle count, capacities, battery flow, system load | Shows it with a "Best effort" badge; one switch turns all of it off |390| Needs your permission | Wi-Fi network name (Location Services) | Does not ask |391| Needs a privileged helper | CPU and memory of other users' processes | Installs none; shows "—" |392| Not exposed | CPU / GPU temperature, fan speed, SSD health, per-process network and GPU use, CPU frequency | Says "Not available through supported system interfaces." |393394## 20. Technology stack395396| Layer | Technology | Role |397|---|---|---|398| Language | Swift 6, strict concurrency | Everything |399| UI | SwiftUI, AppKit where needed (`NSImage` for the status item, `NSSavePanel`, Core Text for PDF) | 13 pages, settings, menu bar extra |400| Charts | SwiftUI `Canvas` (live charts, heatmap, sparklines), Swift Charts (stored history) | Live charts redraw once per sample, with no animation |401| Telemetry core | Swift package `ORIXMonitorCore`, no SwiftUI | Collectors, scheduler, store, alerts, findings, reports |402| Storage | SQLite (system library), WAL | Time series and events |403| System | Mach, libproc, IOKit, DiskArbitration, SystemConfiguration, CoreWLAN, Network, Metal, UserNotifications, ServiceManagement | Sources |404| Project | XcodeGen (`project.yml`) | The `.xcodeproj` is generated, not committed |405| Third-party code | None | — |406407Metal is used to describe GPU devices, not to draw: a few hundred points per chart do not justify a custom renderer. Live408charts were first built with Swift Charts; measured on the signed app, the animation between samples cost about 10 % of a409core on the CPU page, so they were rewritten on `Canvas` and redraw once per sample ([§26](#26-performance-overhead)).410411## 21. Architecture412413```mermaid414flowchart LR415 subgraph SYS["macOS interfaces"]416 A1["Mach host statistics"]417 A2["libproc"]418 A3["IOKit registry"]419 A4["sysctl and getifaddrs"]420 A5["ProcessInfo, CoreWLAN, Metal"]421 end422 subgraph CORE["ORIXMonitorCore (no SwiftUI)"]423 C["Collectors"]424 N["Normalizer"]425 E["TelemetryEngine (actor)"]426 S[("TimeSeriesStore (SQLite)")]427 AL["AlertEngine"]428 IN["IntelligenceEngine"]429 R["ReportGenerator"]430 end431 subgraph APP["App (SwiftUI, main actor)"]432 M["MonitorModel"]433 UI["Pages and dashboard"]434 MB["Menu bar extra"]435 NO["Notification Center"]436 EX["PDF, Markdown, CSV, JSON"]437 end438 SYS --> C --> N --> E439 E -->|"values"| S440 E --> AL -->|"transitions"| S441 S --> IN442 E -->|"snapshot stream"| M443 M --> UI444 M --> MB445 AL --> NO446 S --> R --> EX447 IN --> UI448```449450**One sample, end to end:**451452```mermaid453sequenceDiagram454 participant T as TelemetryEngine455 participant C as Collectors456 participant A as AlertEngine457 participant S as TimeSeriesStore458 participant M as MonitorModel459 T->>T: effective interval (window visible, on battery, Low Power Mode)460 T->>C: sample CPU, memory, disk, network, GPU461 C-->>T: counters and rates (no rate without a baseline)462 T->>T: normalize to stored metrics463 T->>A: evaluate rules464 A-->>T: fired or resolved465 T->>S: append (buffered, flushed every 30 s)466 T-->>M: snapshot (one-slot stream)467 M->>M: update the 150-sample live window468```469470**Alert rule life cycle:**471472```mermaid473stateDiagram-v2474 [*] --> Idle475 Idle --> Holding: condition true476 Holding --> Idle: condition false or gap in sampling477 Holding --> Firing: held long enough, cooled down, not snoozed478 Firing --> Idle: condition false (resolved)479```480481More diagrams and the reasoning behind each choice: [overview](docs/architecture/overview.md) ·482[telemetry](docs/architecture/telemetry.md) · [collectors](docs/architecture/collectors.md) ·483[storage](docs/architecture/storage.md) · [alerts](docs/architecture/alerts.md) · [reporting](docs/architecture/reporting.md).484485**Repository layout**486487```text488ORIXMonitor/489├── App/Sources/490│ ├── App/ entry point, MonitorModel, settings491│ ├── DesignSystem/ tokens, components492│ ├── Features/ dashboard, hardware pages, processes, history, analysis, reports, settings, menu bar493│ └── Reporting/ PDF renderer494├── App/Resources/ asset catalogue (icon, accent), string catalogue (en, fr-CA)495├── Packages/ORIXMonitorCore/496│ ├── Sources/ORIXMonitorCore/ Metrics, Collectors, Scheduler, Storage, Analysis, Reporting497│ ├── Sources/orix-probe/ command-line probe and micro-benchmarks498│ └── Tests/ 81 tests499├── UITests/ end-to-end interface tests500├── Scripts/ build, sign, notarize, package, release, bench, screenshots, localize, check501├── design/icon/ icon concepts and master artwork502├── docs/ research, architecture, metrics, design, development, release, reports, screenshots503└── project.yml XcodeGen definition504```505506## 22. Installation507508**Requirements**: a Mac with Apple Silicon and macOS 15 or later.5095101. Download [`ORIX-Monitor-1.0.0.dmg`](https://git.spboucher.ai/releases/orix-monitor/v1.0.0/ORIX-Monitor-1.0.0.dmg) and open it.5112. Drag **ORIX Monitor** to **Applications**.5123. Open it. It appears in the Dock and in the menu bar; closing the window leaves the menu bar item running.513514The disk image and the app are signed with a Developer ID and notarized by Apple, so Gatekeeper opens them without a515warning. Verify a download with:516517```bash518shasum -a 256 ORIX-Monitor-1.0.0.dmg # compare with the value in §31519spctl --assess --type open --context context:primary-signature -v ORIX-Monitor-1.0.0.dmg520```521522ORIX Monitor asks for no permission at launch. To uninstall, quit it and delete the app; its data is in523`~/Library/Application Support/ORIX Monitor/` and its preferences under `ai.spboucher.orix.monitor`.524525> Published on 2026-11-21. The downloads were fetched back from the forge and matched the checksums in [§31](#31-release-status).526527## 23. Build instructions528529```bash530brew install xcodegen create-dmg # Xcode 16 or later is required531Scripts/build.sh debug # generate the project, build Debug532Scripts/build.sh test # core test suite (swift test)533Scripts/build.sh uitest # interface tests (drives the real app; needs the screen)534Scripts/build.sh release # Release build, signed with the Developer ID identity in the keychain535Scripts/release.sh # tests, build, signature check, notarization, DMG, ZIP, checksums, Gatekeeper536```537538Other tools: `Scripts/bench.sh` (overhead), `Scripts/screenshots.sh`, `Scripts/localize.py` (string catalogue),539`Scripts/check.sh` (author headers and secret scan), `swift run orix-probe` (prints one reading of every collector).540Setup details and launch arguments: [`docs/development/setup.md`](docs/development/setup.md).541542## 24. Testing543544| Suite | Count | Result on 2026-11-21 | What it covers |545|---|---|---|---|546| Core (`swift test`) | 81 tests, 16 suites | **81 passed** | Tick and counter arithmetic with wraparound and resets, memory accounting, disk and network rates, process CPU and the Mach time conversion (checked against `getrusage`), battery registry layouts, scheduler intervals, store tiers, downsampling, gaps, retention, relaunch, alert state machine, detectors, findings, report renderers, and the real collectors and engine on the test Mac |547| Interface (XCUITest) | 13 tests | **12 passed, 1 skipped** | First launch, every page, unavailable sensors declared, dashboard editing, process explorer, alert rule and snooze, report preview, settings, appearance, window resizing, the narrow-window regression, history across relaunch |548| Accessibility audit | 12 pages | recorded, see [§28](#28-accessibility) | Apple's `performAccessibilityAudit` on every page |549550The skipped test clicks the menu bar item; the test Mac hides that item behind its notch, so the test verifies that the item551exists and carries live readings, then skips the click. The panel behind it has therefore **not** been exercised by an552automated click.553554The interface tests found a real crash before release: on the Processes page a narrow window sent SwiftUI's split view into555a constraint loop that aborted the app. It was fixed and is now covered by `testProcessesPageSurvivesANarrowWindow`.556557Per-test descriptions: [`docs/development/testing.md`](docs/development/testing.md).558559## 25. Benchmarks560561Measured on the test Mac with `swift run -c release orix-probe --bench` (Mac17,6, Apple M5 Max, macOS 27.0), while other562work was running on the machine. Median of repeated calls.563564| Operation | Median | 95th percentile | Calls |565|---|---|---|---|566| CPU sample (all cores) | 0.005 ms | 0.008 ms | 200 |567| Memory sample | 0.006 ms | 0.007 ms | 200 |568| Disk activity (block devices) | 0.13 ms | 0.15 ms | 100 |569| Power and battery | 0.37 ms | 0.44 ms | 50 |570| GPU statistics (best effort) | 0.78 ms | 0.87 ms | 100 |571| Network interfaces and addresses | 1.02 ms | 1.22 ms | 100 |572| Volumes (every 30 s in the app) | 16.4 ms | 19.7 ms | 30 |573| Process table, **5,007 processes** | 22.3 ms | 39.7 ms | 20 |574575| Store operation (in-memory database) | Result |576|---|---|577| Ingest one simulated day: 43,200 ticks × 27 metrics = 1,166,400 values, flushed every 15 ticks | 1.22 s in total, 28 µs per tick |578| Query 1 hour of raw samples, downsampled to 450 points | 0.29 ms |579| Query 24 hours from the minute tier, 480 points | 0.32 ms |580| Query 24 hours from the hour tier, 24 points | 0.06 ms |581582The process table is by far the most expensive collector, which is why it is sampled half as often as the rest. The test583Mac was running about 5,000 processes at the time (simulators and builds); a typical Mac runs several hundred.584585## 26. Performance overhead586587`Scripts/bench.sh` starts an isolated instance of the signed Release app, lets it settle for 10 s, measures it for the stated588time, and reads two independent sources: `ps` / `footprint` from outside, and the app's own `self.cpu` / `self.memory`589metrics from its database.590591| Page shown | Sampling interval | Measured for | CPU, share of one core (`ps`) | CPU, self-reported (avg / max) | Footprint at the end (`footprint`) | Footprint, self-reported (avg / max) |592|---|---|---|---|---|---|---|593| Dashboard | 5 s | 90 s | **0.87 %** | 0.85 % / 1.58 % | 269 MB | 102 MB / 246 MB |594| Dashboard | 2 s (default) | 120 s | **2.32 %** | 2.32 % / 5.86 % | 80 MB | 82 MB / 248 MB |595| CPU | 2 s (default) | 90 s | **2.47 %** | 2.42 % / 5.01 % | 240 MB | 90 MB / 240 MB |596| Processes (Apps filter) | 2 s (default) | 90 s | **2.14 %** | 2.18 % / 5.02 % | 63 MB | 72 MB / 75 MB |597| CPU | 1 s | 90 s | **4.13 %** | 4.26 % / 8.17 % | 254 MB | 243 MB / 255 MB |598599Conditions: signed Release build 1.0.0 (1), MacBook Pro `Mac17,6` (M5 Max, 18 cores), macOS 27.0, on AC power, window on600screen, **while other builds and simulators were running on the same Mac** (about 5,000 processes), which raises the cost601of the process table. One run per row; these are single measurements, not averages over several runs.602603- **CPU.** Roughly 2.1–2.5 % of one core at the default 2 s interval, under 1 % at 5 s, about 4 % at 1 s. On an 18-core Mac,604 2.3 % of one core is about 0.13 % of total capacity. The two methods agree to within 0.15 points.605- **Memory.** The footprint is not steady: it moves between about 60 MB and about 270 MB during a run. A breakdown with606 `footprint` taken at a high point shows about 185 MB of *graphics* memory owned by the window's layers and about 41 MB of607 heap; the graphics part is allocated and released by the system and was seen falling back to under 80 MB with nothing608 changed in the app. Replacing Swift Charts with Canvas drawing did not change it, so it is not the charts. **Its cause is609 not established**; it is listed as an open item.610- **Disk.** 1,575 samples in the 120 s run produced a 276 kB database (including its write-ahead log); writes happen once611 every 30 s. Extrapolated linearly, that is about 7.6 MB per hour of raw samples, capped by the 6-hour raw retention;612 the extrapolation is an estimate.613- **Collection time** per sample is shown live in *Settings › About*; the collectors themselves are timed in §25.614- **A defect found by this benchmark and fixed before release:** with Swift Charts animating between samples, the CPU page615 at 1 s measured **10.1 % of one core**. Live charts now redraw once per sample on a Canvas; the same measurement is 4.1 %.616- **Not measured:** energy impact, the menu-bar-only state (window closed), and behaviour on battery (where the default617 interval doubles).618619What keeps it low: one sampling loop; process table sampled half as often as the fast tier; volumes and battery every 30 s;620writes buffered and flushed every 30 s in one transaction; a one-slot snapshot stream so the interface never queues stale621samples; a 150-sample live window; a slower interval when only the menu bar is showing; half the rate on battery and in Low622Power Mode. **Energy impact was not measured**: it needs `powermetrics` (root) or Instruments, neither of which was run.623Method and design notes: [`docs/development/performance.md`](docs/development/performance.md).624625## 27. Privacy626627- **Local only.** Measurements, history, alerts and reports stay in `~/Library/Application Support/ORIX Monitor/`.628- **No account, no analytics, no advertising, no update check, no third-party code.**629- **One network action, on demand**: the latency test, to the host you type, when you press the button.630- **No permission requested**, except Notification Center if you enable alerts there. No Location Services, no Full Disk631 Access, no Accessibility, no administrator password, no privileged helper.632- **Not sandboxed**, because the sandbox blocks the process table and registry statistics the app exists to show; it carries633 **no entitlement** at all.634- **Privacy mask**: one switch replaces addresses, host and user names by "•••" for screenshots and screen sharing.635- **Reports** leave out the host name unless you opt in, and never contain a serial number, addresses or user names.636637## 28. Accessibility638639- **VoiceOver**: every chart exposes a text summary (latest value, minimum and maximum per series); per-core bars read each640 core's value; rows combine label and value; page headers are headers.641- **Never colour alone**: severity, pressure, thermal state and data quality always carry a word and a symbol.642- **Contrast**: text colour tokens are computed to reach at least 4.5:1 on every background in both appearances. Apple's643 automated audit still reports contrast notes it does not attribute to an element; they are unresolved (see the report).644- **Colour-blind-safe palette**: an Okabe–Ito based option for chart colours.645- **Reduce Motion**: readout and dashboard animations are disabled when the system setting is on; live charts never animate.646- **Keyboard**: standard navigation, ⇧⌘P pause, ⇧⌘B bookmark, ⇧⌘R refresh insights, ⇧⌘D new dashboard window.647- **Density**: compact, regular, comfortable.648649Apple's automated audit was run on all twelve pages; its raw output and a reading of it are in650[`docs/reports/accessibility.md`](docs/reports/accessibility.md). **No person has reviewed the app with VoiceOver**, and651macOS has no Dynamic Type; text does not scale beyond the density setting.652653## 29. Localization654655English and **Français (Canada)**, 747 strings, in a string catalogue rebuilt by [`Scripts/localize.py`](Scripts/localize.py)656from compiler-extracted keys, run-time keys and [`Scripts/translations-fr-CA.json`](Scripts/translations-fr-CA.json).657Numbers, percentages, byte counts, durations and dates follow the system locale (`52,5 %`, `39,9 Go`). The French text was658machine-translated and spot-checked; it has **not been proofread by a French-speaking reviewer**, and only the dashboard and659history pages were looked at in French.660661## 30. Roadmap662663Not implemented in 1.0.0, in rough order of value:664665- Automatic updates (Sparkle was evaluated and deliberately left out until a signed release feed exists).666- An editor for the insight thresholds (they are fixed defaults today).667- Per-core history in the store (per-core data is live only).668- An Intel build, once it can be tested on an Intel Mac.669- A4 paper for PDF reports; scheduled reports.670- A widget or Control Center presence.671672## 31. Release status673674| Item | Value |675|---|---|676| Version | 1.0.0 (build 1) |677| Minimum macOS | 15.0 |678| Architecture | arm64 (Apple Silicon) |679| Signature | Developer ID Application: Simon-Pierre Boucher (3YM54G49SN), Hardened Runtime, secure timestamp, no entitlements |680| Notarization — app | Accepted, submission `4f0026aa-6755-471b-9392-b06671e90083` |681| Notarization — disk image | Accepted, submission `13bf43c8-e0e8-4c84-acfc-8e74bc3f6f23` |682| Stapled | App and DMG |683| Gatekeeper | `accepted`, source = Notarized Developer ID (app and DMG) |684| `ORIX-Monitor-1.0.0.dmg` | 3,455,660 bytes · SHA-256 `76ae76570e2c7654cdf377922bc85967d04eb20eedeaabd7675791f5b84e3be2` |685| `ORIX-Monitor-1.0.0.zip` | 2,515,813 bytes · SHA-256 `3b91a67ff51dd880bc1250491b1abc6591a95349717318139571023bcf1ad752` |686| Source repository | Public, <https://git.spboucher.ai/orix-monitor> |687| Release | <https://git.spboucher.ai/orix-monitor/releases>, tag `v1.0.0`, published 2026-11-21 |688| Downloads | [DMG](https://git.spboucher.ai/releases/orix-monitor/v1.0.0/ORIX-Monitor-1.0.0.dmg) · [ZIP](https://git.spboucher.ai/releases/orix-monitor/v1.0.0/ORIX-Monitor-1.0.0.zip) · [SHA256SUMS.txt](https://git.spboucher.ai/releases/orix-monitor/v1.0.0/SHA256SUMS.txt) · [Release notes](https://git.spboucher.ai/releases/orix-monitor/v1.0.0/RELEASE-NOTES.md) |689690The repository started private, as the brief required, and was made public with its release on 2026-11-21 at the owner's691request. After upload, the DMG and ZIP were downloaded from the public URLs: sizes and SHA-256 matched, the stapled ticket692validated and Gatekeeper accepted the downloaded disk image. Full evidence: [`RELEASE-REPORT.md`](RELEASE-REPORT.md).693694## 32. Known limitations695696- **Tested hardware**: developed and fully tested on one MacBook Pro (M5 Max, macOS 27.0). The notarized DMG was also697 installed and run for 45 seconds on an M4 Mac mini (macOS 26.7) and an M2 Mac mini (macOS 26.5.1), where it passed698 Gatekeeper and collected metrics. macOS 15 itself, Intel Macs, external GPUs and Macs with several batteries or a UPS699 were not tested.700- **No temperatures, no fan speeds, no SSD health, no per-process network or GPU usage** — by design, see §19.701- **Other users' processes** show identity only.702- **Best-effort values can vanish** with a system update; the app is built to show "—" when they do, and that path is703 covered by tests on synthetic data only.704- **History has holes** whenever the app is not running, and a crash or force quit can lose up to 30 seconds of samples.705- **Menu bar item**: on a Mac whose menu bar is full, macOS hides it; the app cannot prevent that.706- **Multi-display**: detached dashboard windows exist, but were not tried on a second physical display.707- **Sleep and wake**: handled in code and covered by engine tests with simulated time; a real sleep cycle was not part of708 the automated runs.709- **Notifications**: the permission prompt and delivery were not exercised by the automated tests.710- **Energy impact** of the app was not measured.711712## 33. ORIX ecosystem713714ORIX is a family of premium Apple utilities that share a design language, work without an account and keep their715processing on the device.716717| App | Platform | Purpose |718|---|---|---|719| ORIX Scan | iOS, iPadOS | Document scanning, on-device OCR, searchable PDF |720| ORIX Calc | iOS, iPadOS | Universal calculator |721| ORIX Audio | iOS, iPadOS | Recorder, analysis, on-device transcription |722| ORIX Secure · ORIX Camera | iOS, iPadOS | In development |723| **ORIX Monitor** | **macOS** | **System monitoring, diagnostics and performance intelligence** |724725ORIX Monitor reuses the family palette (canvas, surfaces, text roles, semantic colours) and brings its own accent, the cyan726pulse. It shares no code and has no run-time dependency on the other apps. See727[`docs/design/brand-guidelines.md`](docs/design/brand-guidelines.md) and728[`docs/design/icon-design.md`](docs/design/icon-design.md).729730<div align="center"><img src="docs/assets/icon-concepts.png" alt="The five icon concepts, each shown at 128, 64, 32 and 16 pixels" width="820"><br>731<sub>The five icon concepts explored; the first, the ORIX "O" crossed by a pulse, was chosen.</sub></div>732733## Author734735**Simon-Pierre Boucher** — [www.spboucher.ai](https://www.spboucher.ai) · contact@spboucher.ai736737## 34. License738739All rights reserved © 2026 Simon-Pierre Boucher. See [`LICENSE`](LICENSE).740