NestRay

Your read-only Mac health doctor.

NestRay turns hidden macOS system information into concise diagnoses, meaningful changes, and safe next steps—without deleting or modifying system content.

Visit the NestRay product website

Website · Download v0.1.0 · Source code

Download v0.1.0

The first public preview includes both a portable app archive and a system-level installer:

File	Purpose
NestRay-v0.1.0-macOS.zip	Extract and move NestRay.app to /Applications
NestRay-v0.1.0-macOS.pkg	Install NestRay directly into /Applications
SHA256SUMS-v0.1.0.txt	Verify downloaded release artifacts

Preview signing notice: v0.1.0 is ad-hoc signed and not Apple-notarized. macOS may require explicit approval before opening it. A Developer ID signed and notarized distribution is planned.

Read the complete v0.1.0 release notes or review the changelog.

What NestRay does

NestRay scans system metadata that is readable by the current macOS account and answers three practical questions:

1. Is something wrong?
2. Why does it matter?
3. What should I review next?

The local health engine can identify conditions involving storage pressure, rapid cache growth, inactive applications, missing background executables, repeated crashes or hangs, repeated process pressure, battery capacity, package relationships, and scan-coverage limitations.

Product experience

• Today — the current diagnosis, top actions, healthy areas, and changes since the previous check.
• Health — findings grouped into Performance, Storage, Battery, Stability, Background, and Software.
• Timeline — meaningful application, package, service, storage, and finding changes across scans.
• Ask NestRay — concise answers grounded in relevant scanner evidence using your own OpenRouter key.
• Advanced — applications, storage, background items, packages, dependencies, shell profiles, dotfolders, and raw evidence.
• Menu bar — current health, first recommended action, and a quick health-check command.

Read-only by design

NestRay does not:

• Delete, move, repair, update, or uninstall system content
• Disable launch agents or background services
• Execute AI-generated shell commands
• Read personal documents for AI analysis
• Upload scanner data automatically

NestRay writes only its own preferences, finding dispositions, and local scan history. Full Disk Access is optional and only expands read-only metadata coverage.

See PRIVACY.md for the complete data-flow summary.

Optional AI assistant

The application works without AI. Users can optionally provide an OpenRouter API key, which is stored in macOS Keychain.

When the user asks a question, NestRay sends a compact, query-relevant context rather than the complete system inventory. Home-directory paths are redacted by default, and raw file contents, personal documents, and API keys are not included.

AI answers are advisory. The deterministic local scanner remains the source of system evidence.

Supported metadata sources

• /Applications, /System/Applications, and the user Applications directory
• Homebrew formulae and casks
• Global npm packages
• pipx environments
• Cargo-installed binaries
• User and system launch agents and daemons
• Visible cache and log footprints
• Recent Diagnostic Reports metadata
• Battery-controller metadata where available
• Process CPU and memory samples
• Common shell profiles, developer configuration, and hidden tooling directories

A source that is unavailable or permission-protected is reported as unknown, not healthy or absent.

Requirements

• macOS 14 or later
• Apple Silicon or Intel Mac
• Swift 6 toolchain / Xcode Command Line Tools for local builds
• OpenRouter account and API key only if AI features are used

The UI currently ships in English, but scanning does not impose a country or region restriction and uses locale-aware macOS date and size formatting.

Build locally

git clone https://github.com/imhimansu28/NextRay.git
cd NextRay
swift test
./Scripts/package_app.sh
open dist/NestRay.app

Create all local v0.1.0 release artifacts with:

./Scripts/make_release.sh 0.1.0

The packaging scripts create ad-hoc signed local builds. Public distribution should use an Apple Developer ID signature and Apple notarization. The current downloadable binary is built for Apple Silicon; source builds can be produced on supported Intel Macs as well.

Project structure

Sources/NestRay/
├── App/        Application state, navigation, monitoring, and menu bar
├── Models/     Scanner, health, history, and AI data models
├── Services/   System scanner, persistence, Keychain, and OpenRouter
└── Views/      Today, Health, Timeline, Ask, and Advanced interfaces

Tests/NestRayTests/
└── HealthModelTests.swift

Privacy and security

• OpenRouter keys are stored using the macOS Keychain API.
• Scanner history stays in the user's Application Support directory.
• Sensitive configuration files are metadata-only and their contents are not inspected.
• Shell-profile analysis is local and limited to non-sensitive startup metadata.
• Network requests are made only to OpenRouter and only for model loading or a user-initiated AI question.

Please review SECURITY.md before reporting a potential vulnerability.

Status

NestRay is an early-stage independent macOS utility. Scanner conclusions are intentionally cautious and should be verified before making manual system changes.

A dedicated product website and signed release distribution are planned, but are intentionally outside the current repository audit.