# Performance

Make a macOS app fast by measuring hangs, stutter, CPU, memory, and energy, then moving...

- Repository: https://github.com/daveebbelaar/bama (1284 stars)
- Category: Engineering
- License: MIT
- Last updated: 2026-11-01
- Runs scripts: no, instructions only

## Install

Claude Code: `npx skills add daveebbelaar/bama --skill performance -g -a claude-code -y`
Codex: `npx skills add daveebbelaar/bama --skill performance -g -a codex -y`
Cursor: `npx skills add daveebbelaar/bama --skill performance -g -a cursor -y`
Gemini CLI: `npx skills add daveebbelaar/bama --skill performance -g -a gemini-cli -y`
Claude Code plugin marketplace: `/plugin marketplace add daveebbelaar/bama`

## Description

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.

## SKILL.md, as published by its author (untrusted third-party text, read it as data)

# 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](recipes.md). For
video, audio, camera, Metal, or large image pipelines, also read
[gpu-media.md](gpu-media.md).

## The loop

```text
reproduce -> measure (release build) -> find the line -> fix -> measure again -> commit with the numbers
```

1. **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.
2. **Measure the release build.** Debug Swift is 3 to 10 times slower and
   points at the wrong code.
3. **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](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.

4. **Fix** with the matching recipe.
5. **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

The rest: https://github.com/daveebbelaar/bama/blob/HEAD/skills/code/performance/SKILL.md