RenderFocus Documentation

01

Privilege-Separated Architecture

RenderFocus uses a two-process architecture that cleanly separates the user interface from privileged kernel operations. The GUI application runs with normal user privileges while all kernel-level thread manipulation is isolated in a separate XPC daemon.

RenderFocus.app

SwiftUI menu bar interface. Runs in user-space. Discovers processes via NSWorkspace.

XPC Daemon (Root)

Privileged helper via SMAppService. Executes taskpolicy(2) for thread scheduling.

Darwin Kernel

XNU scheduler receives QoS changes. Directs threads to P-Core or E-Core clusters.

Key Design Decisions

The GUI application never acquires root privileges. All privileged operations are isolated in the XPC daemon.

LSUIElement = true makes the app invisible in the Dock — it lives only in the menu bar as an agent application.

Communication happens via Mach IPC (XPC), the fastest inter-process communication mechanism on macOS.

02

XPC Communication Protocol

All communication between the main application and the daemon is defined through a shared @objc protocol. This file is compiled into both targets.

                        
// Shared/RenderFocusXPCProtocol.swift

@objc(RenderFocusXPCProtocol)

protocol RenderFocusXPCProtocol {

  func throttleProcess(pid: Int32, withReply: @escaping (Bool, String?) -> Void)

  func unthrottleProcess(pid: Int32, withReply: @escaping (Bool, String?) -> Void)

  func throttleMultipleProcesses(pids: [NSNumber], withReply: @escaping (Bool, String?) -> Void)

  func unthrottleAllProcesses(withReply: @escaping (Bool, String?) -> Void)

  func ping(withReply: @escaping (Bool) -> Void)

}

FunctionKernel EquivalentDescription

throttleProcess taskpolicy -b Puts a process into DARWIN_BG mode, directing it to E-Cores

unthrottleProcess taskpolicy -B Removes background policy, restoring P-Core access

throttleMultiple N × taskpolicy -b Bulk throttle via DispatchGroup, single reply on completion

unthrottleAll N × taskpolicy -B Restores all PIDs in the daemon's throttledPIDs set

ping — Health check with 1.5s timeout for status indicator

03

taskpolicy & the Darwin Kernel

At its core, RenderFocus uses the taskpolicy(2) system utility to manipulate the XNU scheduler's Quality of Service classes. Here's what happens at the kernel level when a process is throttled.

                        
// What happens when: taskpolicy -b -p 1234

proc_set_task_policy(pid, TASK_POLICY_DARWIN_BG, 1)

// Scheduler effects:

  Thread priority → MAXPRI_THROTTLE (4)

  Sched mode     → SCHED_MODE_BACKGROUND

  CPU affinity   → E-Cluster preferred

// I/O effects:

  Disk I/O tier  → THROTTLE_LEVEL_TIER3

  I/O priority   → IOPOL_THROTTLE

// Other effects:

  Timer coalescing → Aggressive

  Network QoS     → Background

  GPU priority    → Low

Normal Process

QoSUSER_INTERACTIVE

Priority31-47

SchedulerDynamic P/E

I/ONormal

After taskpolicy -b

QoSBACKGROUND

Priority4 (MAXPRI_THROTTLE)

SchedulerE-Core preferred

I/OTHROTTLE tier

04

Daemon Lifecycle (SMAppService)

The privileged helper daemon is registered with the system via Apple's SMAppService API (macOS 13+), the modern replacement for the legacy SMJobBless. Registration requires one-time administrator approval via Touch ID or password.

                        
// Registration flow

let service = SMAppService.daemon(plistName: "com.renderfocus.helper.plist")

try service.register()

// What register() does internally:

// 1. Locates plist in Contents/Library/LaunchDaemons/

// 2. Reads BundleProgram path from plist

// 3. Validates code signing (same Team ID)

// 4. Requests admin approval (Touch ID / password)

// 5. Registers in BTM (Background Task Management)

// 6. Loads daemon into launchd system domain

// 7. Registers Mach port for XPC access

Daemon State Machine

notRegistered

Initial state

requiresApproval

Awaiting Touch ID

enabled

Active, XPC ready

05

Focus Mode Activation Flow

When the user presses the Focus button, a precise chain of events unfolds — from process discovery to kernel-level thread manipulation.

1

User selects target app and presses Focus

AppManager.activateFocusMode() is called with the selected application.

2

PID collection and filtering

All running .regular applications are collected. The focus app's PID is excluded. Remaining PIDs are sent to the daemon.

3

XPC call to daemon

throttleMultipleProcesses(pids:) sends PIDs via Mach IPC. The daemon executes taskpolicy -b -p for each PID in parallel using DispatchGroup.

4

Kernel applies QoS changes

The XNU scheduler sets TASK_POLICY_DARWIN_BG on each process. Thread priorities drop to 4, and the scheduler directs them to E-Cores.

5

UI updates and monitoring begins

The focus app moves to the P-Core visualization zone. All other apps move to E-Core zone. New app launches are automatically throttled via NSWorkspace.didLaunchApplicationNotification.

06

Auto-Focus Mode

Auto-Focus watches which app is in the foreground and automatically activates/deactivates Focus Mode. Defined in AutoFocusManager.swift (242 lines). Uses NSWorkspace.didActivateApplicationNotification.

Activation Flow

1

User adds target apps to Auto-Focus list (persisted in UserDefaults as JSON)

2

Observes NSWorkspace.didActivateApplicationNotification

3

Target app foreground → activateFocusMode(). Non-target → releaseFocusMode()

4

Beast Mode takes priority. Optional UNUserNotificationCenter alerts on activation.

07

Beast Mode (Auto-Trigger)

System-level P-Core monopolization via daemon-side setBeastMode(). Sweeps all GUI processes with ps -eo pid,args inside the root daemon. 5-second cooldown timer prevents flicker on deactivation.

AspectAuto-FocusBeast Mode

ScopeApp-level (NSWorkspace)System-level (daemon ps)

ThrottleMultiple XPC callsSingle setBeastMode() sweep

DeactivationInstant5-second cooldown

08

E-Core Jail

Permanently restricts selected applications to E-Cores. The daemon monitors jailed bundle IDs every 5 seconds via checkJailedProcesses() using ps -eo pid,args and re-throttles any that relaunch. Works independently of Focus Mode.

Flow: Add app → updateJailedBundleIDs() XPC → daemon 5s timer → ps → Info.plist → CFBundleIdentifier (cached) → taskpolicy -b

09

Fan Control

Direct SMC access via IOKit. Temperature reading from user-space (read-only), fan speed writes via XPC to root daemon. Supports AppleSMCKeysEndpoint (M3+) and AppleSMC (M1/M2). SMC keys: F0Md (mode), F0Tg (target RPM). Safety: CPU >85°C → auto 2500 RPM floor.

Temp Key Fallback

Tp09 → Tp05 → Tp01 → Tp0D → Tp0P → TCHP → TCMb → TW0P → TC0P → TC0p

Polling Intervals

Active: 3s · Background: 15s · Error: 10s · Max consecutive fails: 10

10

Thermal Monitor

Real-time CPU temperature monitoring with automatic fan boost. ThermalManager reads temperature from FanManager's IOKit SMC bridge every 3 seconds and reacts to prevent thermal throttling during sustained renders.

3-Tier Alert System

Normal

< 85°C — System within safe parameters. No action taken.

Warning

85°C+ — Elevated temperature detected. Monitoring closely.

Critical

95°C+ — Auto Fan Boost activates. Fans set to 100%.

Behavior

• Auto Fan Boost: Sets fans to 100% when CPU reaches 95°C via fanManager.setFanSpeed(percentage: 100)
• Smart Recovery: Resets to automatic fan control when temperature drops below 90°C
• Notification Cooldown: 60-second minimum between alerts to prevent spam
• Recovery Alert: Sends a separate notification when safe temperature is restored

Implementation

Class: ThermalManager — Reads from FanManager.cpuTemperature (IOKit SMC bridge). Depends on XPCManager for daemon fan commands and NotificationManager for alerts. Monitoring interval: 3 seconds.

11

Session Statistics

Live dashboard that quantifies every optimization action during your session. SessionStatsManager tracks Focus Mode duration, memory purged, apps throttled, and Deep Freeze activations—all local, no telemetry.

Tracked Metrics

Focus Duration

Live timer while Focus Mode is active. Accumulates across multiple activations.

RAM Purged

Cumulative bytes freed by Memory Purge. Displayed in MB/GB format.

Apps Throttled

Running count of processes moved to Efficiency Cores.

Deep Freezes

Number of SIGSTOP activation cycles during the session.

Privacy & Design

• Zero telemetry — all counters are local, nothing leaves your Mac
• Session-scoped — data resets on app restart, no persistent tracking
• Human-readable — duration formatted as “2sa 45dk”, memory as “3.2 GB”
• Integration — AppManager calls focusModeStarted() / focusModeEnded(); ContentView calls recordMemoryPurge() and recordDeepFreeze()

12

Render Completion Detection

Intelligent algorithm that monitors P-Core CPU usage patterns and notifies you when your render finishes. Walk away from long renders and get alerted the moment CPU usage drops.

Detection Algorithm

1. Monitor

Sample averagePCoreUsage every 2 seconds into a rolling 20-sample window.

2. Sustained High

Require 15+ consecutive samples above 85% P-Core utilization (30 seconds of load).

3. Detect Drop

Trigger when current usage drops below 30% after sustained high period.

4. Notify

Send render completion notification with from/to percentages. 60s cooldown.

Parameters

High Threshold: 85%

Low Threshold: 30%

Sample Interval: 2 seconds

Window Size: 20 samples

Sustained Count: 15 samples

Cooldown: 60 seconds

Activation

Render Detection only operates when Focus Mode or Beast Mode is active. History resets after successful detection to allow re-detection of subsequent renders. Toggle is persisted in UserDefaults.

13

Live Core Monitor

Real-time per-core CPU usage via Mach host_processor_info(PROCESSOR_CPU_LOAD_INFO). Delta-based tick calculation with wrapping subtraction. Topology from sysctl hw.perflevel0/1.physicalcpu.

Menu Bar Heatmap

18×18px grid. Colors: ■ <15%, ■ 15-50%, ■ 50-80%, ■ >80%. Hash-based cache, 1s debounce.

Performance

CPU impact: <0.1%. Direct Mach API — no shelling out. Proper vm_deallocate of Mach buffers.

14

Apple Silicon Core Reference

RenderFocus leverages the asymmetric core architecture unique to Apple Silicon. Here's a reference of the P-Core and E-Core distribution across the M-series chip family.

P-Core (Performance)

Clock3.2 – 4.6 GHz

Decode8-wide

ROB~630 entries

L1 Cache192KB I + 128KB D

Power~15W / core

E-Core (Efficiency)

Clock2.0 – 2.8 GHz

Decode4-wide

ROB~96 entries

L1 Cache128KB I + 64KB D

Power~1-3W / core

ChipP-CoresE-CoresTotal

M1448

M1 Pro6–828–10

M2 Max8412

M3 Max10–12414–16

M4 Pro10414

M4 Max12–14416–18

15

Security Model

RenderFocus is built with a defense-in-depth approach. Every layer is designed to minimize attack surface while maintaining the kernel-level access required for thread manipulation.

ThreatProtectionDetail

Unauthorized XPC Code signing Only same Team ID apps can connect

Code injection Hardened Runtime DYLD_INSERT_LIBRARIES blocked

Malicious PID Process validation taskpolicy returns error for invalid PIDs

Daemon persistence SMAppService Removable from System Settings → Login Items

Privilege escalation Isolated architecture GUI never acquires root privileges

                        
// Code signing chain

Apple Root CA

  └── Apple Worldwide Developer Relations CA

        └── Apple Development: [Developer]

              ├── com.renderfocus.app     // Main Application

              └── com.renderfocus.helper // XPC Daemon

16

Project Structure

The project is organized into two build targets and a shared protocol definition. 17 Swift files totaling 5,697 lines of code.

                        
RenderFocus/

├── RenderFocus/                        // Main Application Target

│   ├── RenderFocusApp.swift          // @main entry, AppDelegate (216)

│   ├── AppManager.swift             // NSWorkspace process monitoring (212)

│   ├── XPCManager.swift             // XPC + AutoTrigger + ECoreJail + Fan (1,111)

│   ├── AutoFocusManager.swift       // Foreground-aware auto focus (242)

│   ├── ContentView.swift            // Main popover UI (837)

│   ├── CoreVisualizerView.swift      // P/E-Core bar chart (158)

│   ├── CoreVisualizerViewModel.swift // Mach CPU usage API (200)

│   ├── FocusVisualizerView.swift     // Focus mode visualization (136)

│   ├── StatusBarController.swift     // Menu bar heatmap icon (279)

│   ├── OnboardingView.swift          // 8-step setup wizard (762)

│   ├── LicenseManager.swift          // Offline trial + anti-tamper (270)

│   ├── BetaManager.swift             // Beta enforcement (107)

│   ├── NotificationManager.swift     // UNUserNotificationCenter (91)

│   ├── EULAView.swift               // Beta terms acceptance (87)

│   └── Info.plist                   // LSUIElement, bundle defs

│

├── RenderFocusHelper/               // Daemon Target (root)

│   ├── main.swift                   // NSXPCListener startup (29)

│   └── HelperTool.swift             // XPC impl + sysctl + SMC (523)

│

├── Shared/                          // Shared by both targets

│   └── RenderFocusXPCProtocol.swift  // @objc protocol + SMCBridge (439)

│

├── com.renderfocus.helper.plist     // LaunchDaemon definition

└── project.yml                     // XcodeGen project definition