Performance
Fast means two numbers: the first frame after a key press shows in under
100 ms, and nothing on the main thread blocks for more than 50 ms. Every
change in this skill starts and ends with a measurement, so you know it
helped. Symptom-by-symptom fixes are in recipes.md. For
video, audio, camera, Metal, or large image pipelines, also read
gpu-media.md.
The loop
reproduce -> measure (release build) -> find the line -> fix -> measure again -> commit with the numbers
Reproduce. Write the exact steps, or add a probe command to the
debug bridge (test-mac-app skill) that runs the slow action and logs
the time of each step.
Measure the release build. Debug Swift is 3 to 10 times slower and
points at the wrong code.
Find the line. Pick the tool for the symptom:
| Symptom |
Tool |
| App freezes, spinning pointer |
sample <App> 5, then read the main thread stack |
| Slow action |
Time Profiler: xcrun xctrace record --template 'Time Profiler' --attach <App> --time-limit 10s |
| Short freezes while typing or dragging |
--template 'Hangs' |
| Stutter while moving or animating |
--template 'Animation Hitches' |
| Memory grows |
footprint <App>, leaks <App>, --template 'Allocations' |
| Fan, battery |
--template 'Energy Log', look for timers and polling |
Read traces as text, not in the Instruments GUI: see "Measuring" in
recipes.md. Delete every .trace after reading. A trace
stores the app's full environment, and an app opened from an agent's
shell inherits that shell's tokens. Never commit or share one.
Fix with the matching recipe.
Measure again with the same steps. Put before and after in the
commit message: "Picker opens in 40 ms, was 600 ms".
The rules that fix most problems
- Main thread does UI only. File, network, database, image decoding,
Accessibility calls, and audio go elsewhere. A main-thread call that waits
on another process (CoreAudio, AX) can freeze the app for minutes.
- Show first, work after. Put the window or panel on screen in the same
frame as the key press, then load. Never make the UI wait for the work.
- Let the GPU composite. Large images go in a
CALayer once. Pointer
movement changes only small layers. Never redraw a full-screen picture per
mouse event.
- Decode at display size. ImageIO thumbnails, cached in
NSCache.
- Do not animate what must be fast. Search results and switchers
update in place.
- No polling without a reason. Timers get a tolerance and stop when
nothing on screen needs them.
Apple silicon notes
- Core Animation, Core Image (one shared
CIContext), Vision, and
AVFoundation already run on the GPU or the Neural Engine. Hand them the
work instead of looping over pixels in Swift.
- Write Metal (
MTKView, compute shaders) only when a measurement shows
Core Animation or Core Image is too slow. Most apps never need it.
- Unified memory means a
CGImage from ScreenCaptureKit passes to a layer
without a copy. Keep it as a CGImage or IOSurface. Converting to
NSImage and back costs copies.
Done when the slow action has a measured before and after, the after meets
the two numbers at the top, and the commit message names both.
1---2name: performance-23description: Make a macOS app fast by measuring hangs, stutter, CPU, memory, and energy, then moving work off the main thread and onto the GPU. Use when the app freezes, a shortcut feels slow, dragging stutters, the fan spins, memory grows, or the user asks to optimize or profile.4metadata:5 source: https://skillmd.com/skills/tuyv/performance-26---78# Performance910Fast means two numbers: the first frame after a key press shows in under11100 ms, and nothing on the main thread blocks for more than 50 ms. Every12change in this skill starts and ends with a **measurement**, so you know it13helped. Symptom-by-symptom fixes are in [recipes.md](recipes.md). For14video, audio, camera, Metal, or large image pipelines, also read15[gpu-media.md](gpu-media.md).1617## The loop1819```text20reproduce -> measure (release build) -> find the line -> fix -> measure again -> commit with the numbers21```22231. **Reproduce.** Write the exact steps, or add a probe command to the24 debug bridge (`test-mac-app` skill) that runs the slow action and logs25 the time of each step.262. **Measure the release build.** Debug Swift is 3 to 10 times slower and27 points at the wrong code.283. **Find the line.** Pick the tool for the symptom:2930 | Symptom | Tool |31 | --- | --- |32 | App freezes, spinning pointer | `sample <App> 5`, then read the main thread stack |33 | Slow action | Time Profiler: `xcrun xctrace record --template 'Time Profiler' --attach <App> --time-limit 10s` |34 | Short freezes while typing or dragging | `--template 'Hangs'` |35 | Stutter while moving or animating | `--template 'Animation Hitches'` |36 | Memory grows | `footprint <App>`, `leaks <App>`, `--template 'Allocations'` |37 | Fan, battery | `--template 'Energy Log'`, look for timers and polling |3839 Read traces as text, not in the Instruments GUI: see "Measuring" in40 [recipes.md](recipes.md). Delete every `.trace` after reading. A trace41 stores the app's full environment, and an app opened from an agent's42 shell inherits that shell's tokens. Never commit or share one.43444. **Fix** with the matching recipe.455. **Measure again** with the same steps. Put before and after in the46 commit message: "Picker opens in 40 ms, was 600 ms".4748## The rules that fix most problems4950- **Main thread does UI only.** File, network, database, image decoding,51 Accessibility calls, and audio go elsewhere. A main-thread call that waits52 on another process (CoreAudio, AX) can freeze the app for minutes.53- **Show first, work after.** Put the window or panel on screen in the same54 frame as the key press, then load. Never make the UI wait for the work.55- **Let the GPU composite.** Large images go in a `CALayer` once. Pointer56 movement changes only small layers. Never redraw a full-screen picture per57 mouse event.58- **Decode at display size.** ImageIO thumbnails, cached in `NSCache`.59- **Do not animate what must be fast.** Search results and switchers60 update in place.61- **No polling without a reason.** Timers get a tolerance and stop when62 nothing on screen needs them.6364## Apple silicon notes6566- Core Animation, Core Image (one shared `CIContext`), Vision, and67 AVFoundation already run on the GPU or the Neural Engine. Hand them the68 work instead of looping over pixels in Swift.69- Write Metal (`MTKView`, compute shaders) only when a measurement shows70 Core Animation or Core Image is too slow. Most apps never need it.71- Unified memory means a `CGImage` from ScreenCaptureKit passes to a layer72 without a copy. Keep it as a `CGImage` or `IOSurface`. Converting to73 `NSImage` and back costs copies.7475Done when the slow action has a measured before and after, the after meets76the two numbers at the top, and the commit message names both.