Energy Optimization

Overview

Energy issues manifest as battery drain, hot devices, and poor App Store reviews. Core principle: Measure before optimizing. Use Power Profiler to identify the dominant subsystem (CPU/GPU/Network/Location/Display), then apply targeted fixes.

Key insight: Developers often don't know where to START auditing. This skill provides systematic diagnosis, not guesswork.

Requirements: iOS 26+, Xcode 26+, Power Profiler in Instruments

Example Prompts

Real questions developers ask that this skill answers:

1. "My app is always at the top of Battery Settings. How do I find what's draining power?"

→ The skill covers Power Profiler workflow to identify dominant subsystem and targeted fixes

2. "Users report my app makes their phone hot. Where do I start debugging?"

→ The skill provides decision tree: CPU vs GPU vs Network diagnosis with specific patterns

3. "I have timers and location updates. Are they causing battery drain?"

→ The skill covers timer tolerance, location accuracy trade-offs, and audit checklists

4. "My app drains battery in the background even when users aren't using it."

→ The skill covers background execution patterns, BGTasks, and EMRCA principles

5. "How do I measure if my optimization actually improved battery life?"

→ The skill demonstrates before/after Power Profiler comparison workflow

---

Red Flags — High Energy Likely

If you see ANY of these, suspect energy inefficiency:

• Battery Settings: Your app consistently at top of battery consumers
• Device temperature: Phone gets warm during normal app use
• User reviews: Mentions of "battery drain", "hot phone", "kills my battery"
• Xcode Energy Gauge: Shows sustained high or very high impact
• Background runtime: App runs longer than expected when not visible
• Network activity: Frequent small requests instead of batched operations
• Location icon: Appears in status bar when app shouldn't need location

Difference from normal energy use

• Normal: App uses energy during active use, minimal when backgrounded
• Problem: App uses significant energy even when user isn't interacting

Mandatory First Steps

ALWAYS run Power Profiler FIRST before optimizing code:

Step 1: Record a Power Trace (5 minutes)

1. Connect iPhone wirelessly to Xcode (wireless debugging)
2. Xcode → Product → Profile (Cmd+I)
3. Select Blank template
4. Click "+" → Add "Power Profiler" instrument
5. Optional: Add "CPU Profiler" for correlation
6. Click Record
7. Use your app normally for 2-3 minutes
8. Click Stop

Why wireless: When device is charging via cable, power metrics show 0. Use wireless debugging for accurate readings.

Step 2: Identify Dominant Subsystem

Expand the Power Profiler track and examine per-app metrics:

Lane	Meaning	High Value Indicates
CPU Power Impact	Processor activity	Computation, timers, parsing
GPU Power Impact	Graphics rendering	Animations, blur, Metal
Display Power Impact	Screen usage	Brightness, always-on content
Network Power Impact	Radio activity	Requests, downloads, polling

Look for: Which subsystem shows highest sustained values during your app's usage.

Step 3: Branch to Subsystem-Specific Fixes

Once you identify the dominant subsystem, use the decision trees below.

What this tells you

• CPU dominant → Check timers, polling, JSON parsing, eager loading
• GPU dominant → Check animations, blur effects, frame rates
• Network dominant → Check request frequency, polling vs push
• Display dominant → Check Dark Mode, brightness, screen-on time
• Location (shown in CPU) → Check accuracy, update frequency

Why diagnostics first

• Finding root cause with Power Profiler: 15-20 minutes
• Guessing and testing random optimizations: 4+ hours, often wrong subsystem

---

Energy Decision Tree

User reports energy issue?
│
├─ CPU Power Impact dominant?
│  ├─ Continuous high impact?
│  │  ├─ Timers running? → Pattern 1: Timer Efficiency
│  │  ├─ Polling data? → Pattern 2: Push vs Poll
│  │  └─ Processing in loop? → Pattern 3: Lazy Loading
│  ├─ Spikes during specific actions?
│  │  ├─ JSON parsing? → Cache parsed results
│  │  ├─ Image processing? → Move to background, cache
│  │  └─ Database queries? → Index, batch, prefetch
│  └─ High background CPU?
│     ├─ Location updates? → Pattern 4: Location Efficiency
│     ├─ BGTasks running too long? → Pattern 5: Background Execution
│     └─ Audio session active? → Stop when not playing
│
├─ Network Power Impact dominant?
│  ├─ Many small requests?
│  │  └─ Batch into fewer large requests
│  ├─ Polling pattern detected?
│  │  └─ Convert to push notifications → Pattern 2
│  ├─ Downloads in foreground?
│  │  └─ Use discretionary background URLSession
│  └─ High cellular usage?
│     └─ Defer to WiFi when possible
│
├─ GPU Power Impact dominant?
│  ├─ Continuous animations?
│  │  └─ Stop when view not visible
│  ├─ Blur effects (UIVisualEffectView)?
│  │  └─ Reduce or remove, use solid colors
│  ├─ High frame rate animations?
│  │  └─ Audit secondary frame rates → Pattern 6
│  └─ Metal rendering?
│     └─ Implement frame limiting
│
├─ Display Power Impact dominant?
│  ├─ Light backgrounds on OLED?
│  │  └─ Implement Dark Mode (up to 70% savings)
│  ├─ High brightness content?
│  │  └─ Use darker UI elements
│  └─ Screen always on?
│     └─ Allow screen to sleep when appropriate
│
└─ Location causing drain? (check CPU lane + location icon)
   ├─ Continuous updates?
   │  └─ Switch to significant-change monitoring
   ├─ High accuracy (kCLLocationAccuracyBest)?
   │  └─ Reduce to kCLLocationAccuracyHundredMeters
   └─ Background location?
      └─ Evaluate if truly needed → Pattern 4

---

Common Energy Patterns (With Fixes)

Pattern 1: Timer Efficiency

Problem: Timers wake the CPU from idle states, consuming significant energy.

❌ Anti-Pattern — Timer without tolerance

// BAD: Timer fires exactly every 1.0 seconds
// Prevents system from batching with other timers
Timer.scheduledTimer(withTimeInterval: 1.0, repeats: true) { _ in
    self.updateUI()
}

✅ Fix — Set tolerance for timer batching

// GOOD: 10% tolerance allows system to batch timers
let timer = Timer.scheduledTimer(withTimeInterval: 1.0, repeats: true) { _ in
    self.updateUI()
}
timer.tolerance = 0.1  // 10% tolerance minimum

// BETTER: Use Combine Timer with tolerance
Timer.publish(every: 1.0, tolerance: 0.1, on: .main, in: .default)
    .autoconnect()
    .sink { [weak self] _ in
        self?.updateUI()
    }
    .store(in: &cancellables)

✅ Best — Use event-driven instead of polling

// BEST: Don't use timer at all — react to events
NotificationCenter.default.publisher(for: .dataDidUpdate)
    .sink { [weak self] _ in
        self?.updateUI()
    }
    .store(in: &cancellables)

Key points:

• Set tolerance to at least 10% of interval
• Timer tolerance allows system to batch multiple timers into single wake
• Prefer event-driven patterns over polling timers
• Always invalidate timers when no longer needed

---

Pattern 2: Push vs Poll

Problem: Polling (checking server every N seconds) keeps radios active and drains battery.

❌ Anti-Pattern — Polling every 5 seconds

// BAD: Polls server every 5 seconds
// Radio stays active, massive battery drain
Timer.scheduledTimer(withTimeInterval: 5.0, repeats: true) { [weak self] _ in
    self?.fetchLatestData()  // Network request every 5 seconds
}

✅ Fix — Use background push notifications

// GOOD: Server pushes when data changes
// Radio only active when there's actual new data

// 1. Register for remote notifications
UIApplication.shared.registerForRemoteNotifications()

// 2. Handle background notification
func application(_ application: UIApplication,
                 didReceiveRemoteNotification userInfo: [AnyHashable: Any],
                 fetchCompletionHandler completionHandler: @escaping (UIBackgroundFetchResult) -> Void) {

    guard let _ = userInfo["content-available"] else {
        completionHandler(.noData)
        return
    }

    Task {
        do {
            let hasNewData = try await fetchLatestData()
            completionHandler(hasNewData ? .newData : .noData)
        } catch {
            completionHandler(.failed)
        }
    }
}

Server payload for background push:

{
    "aps": {
        "content-available": 1
    },
    "custom-data": "your-payload"
}

Key points:

• Background pushes are discretionary — system delivers at optimal time
• Use apns-priority: 5 for non-urgent updates (energy efficient)
• Use apns-priority: 10 only for time-sensitive alerts
• Polling every 5 seconds uses 100x more energy than push

---

Pattern 3: Lazy Loading & Caching

Problem: Loading all data upfront causes CPU spikes and memory pressure.

❌ Anti-Pattern — Eager loading (from WWDC25-226)

// BAD: Creates and renders ALL views upfront
// From WWDC25-226: This caused CPU spike and hang
VStack {
how to use axiom-energy
CursorClaude CodeClineCodexWindsurfGooseGitHub CopilotVS CodeGemini CLIKiloOpencodeKimi CLIRoo ClineAiderContinueZedBolt.newLovablev0Replit AgentSweepSmol DeveloperDevinCavemanAmpAntigravity
How to use axiom-energy on Cursor
AI-first code editor with Composer
1
Prerequisites
Before installing skills in Cursor, ensure your development environment meets these requirements:
›Cursor installed and configured on your development machine
›Node.js version 16.0+ with npm package manager (verify with node --version)
›Active project directory or workspace where you want to add axiom-energy
2
Execute installation command
Execute the skills CLI command in your project's root directory to begin installation:
$npx skills add https://github.com/charleswiltgen/axiom --skill axiom-energycopy
The skills CLI fetches axiom-energy from GitHub repository charleswiltgen/axiom and configures it for Cursor.
3
Select Cursor when prompted
The CLI will show a list of available agents. Use arrow keys to navigate and space to select Cursor:
◆ Which agents do you want to install to?
│
│ ── Universal (.agents/skills) ── always included ────
│   • Amp
│   • Antigravity
│   • Cline
│   • Codex
│ ●Cursor(selected)
│   • Cursor
│   • Windsurf
4
Verify installation
Confirm successful installation by checking the skill directory location:
.cursor/skills/axiom-energy
Reload or restart Cursor to activate axiom-energy. Access the skill through slash commands (e.g., /axiom-energy) or your agent's skill management interface.
⚠
Security & Verification Notice
We perform automated surface-level scans (Gen AI Scanner, Socket, Snyk) during installation. These checks detect common vulnerabilities but do not guarantee complete security. Always review skill source code and verify the publisher's reputation before production use.
Skills execute code in your development environment. Always verify the publisher's identity, review recent commits, and test in isolated environments before production deployment.
Additional Resources
›View source code on GitHub›Skills CLI documentation›Learn more about Cursor›What are agent skills?