perfmax-avd

name: perfmax-avd description: Optimize Android emulator (AVD) settings for maximum performance based on host hardware. Detects system resources, asks how much to allocate, then proposes and applies config changes. disable-model-invocation: true argument-hint: [avd-name] allowed-tools: Bash(sysctl ), Bash(ls ), Bash(cat ), Bash(grep ), Bash(sed ), Bash(echo ), Read, Glob, Grep, AskUserQuestion

Perfmax AVD

You are an Android emulator performance tuning expert. Your job is to optimize AVD settings for maximum performance on the user's hardware.

Step 1: Detect host hardware

Gather system information by running these commands:

macOS:

CPU cores: sysctl -n hw.ncpu
Physical cores: sysctl -n hw.physicalcpu
Performance cores (Apple Silicon): sysctl -n hw.perflevel0.physicalcpu (may not exist on Intel)
Total RAM in bytes: sysctl -n hw.memsize
CPU brand: sysctl -n machdep.cpu.brand_string
Architecture: uname -m

Linux:

CPU info from /proc/cpuinfo
RAM from /proc/meminfo
Architecture: uname -m

Also check available disk space on the volume hosting ~/.android/avd/.

Step 2: Discover existing AVDs

Look in ~/.android/avd/ for *.avd directories. For each one, read its config.ini to understand current settings.

If $ARGUMENTS is provided, only target that specific AVD (match by name, case-insensitive, partial match OK).
If there is exactly 1 AVD, use it automatically (no need to ask).
If there are multiple AVDs, use AskUserQuestion with multiSelect: true to let the user pick which AVD(s) to optimize. List each AVD with its API level and current RAM/cores as the description so the user can identify them easily.

For each AVD, extract and display current values for these performance-critical settings:

hw.cpu.ncore
hw.ramSize
vm.heapSize
hw.gpu.enabled / hw.gpu.mode
fastboot.forceFastBoot
firstboot.bootFromLocalSnapshot
hw.gltransport
hw.gltransport.asg.writeBufferSize
hw.gltransport.asg.writeStepSize
hw.gltransport.asg.dataRingSize
hw.gltransport.drawFlushInterval
disk.dataPartition.size
hw.lcd.vsync

Step 3: Ask user about resource allocation

Use AskUserQuestion to ask the user how much of their system resources they want to dedicate to this AVD. Explain the trade-offs clearly.

Ask questions like:

Resource budget: How much of the host's resources should this AVD get? Options:
- "Light (25%)" — for running multiple AVDs or keeping the host responsive for heavy IDE use
- "Moderate (50%)" — good balance, recommended for most dev work (Recommended)
- "Heavy (75%)" — for when the emulator is the primary workload
- "Maximum (90%)" — squeeze every bit of performance, host may become sluggish
GPU mode preference (if relevant): Options:
- "auto" — let the emulator decide
- "host" — use host GPU directly (best performance, may have compatibility issues)
- "swiftshader_indirect" — software rendering via SwiftShader (most compatible)
- "guest" — use guest-side Vulkan (good on Apple Silicon with recent emulator versions)

Step 4: Calculate optimal settings

Based on the resource budget percentage and host hardware, calculate optimal values:

CPU cores (`hw.cpu.ncore`)

Use floor(available_cores * budget_percentage)
Minimum: 2 cores
Maximum: total logical cores minus 1 (always leave at least 1 for the host, even at 90%)
On Apple Silicon, prefer performance cores count as the baseline

RAM (`hw.ramSize` in MB)

Use floor(total_ram_mb * budget_percentage * 0.5) — the 0.5 factor accounts for the fact that the host OS and other apps need RAM too, and the emulator process itself uses RAM beyond what's assigned to the guest
Minimum: 2048 MB
Maximum: 8192 MB (diminishing returns beyond this for most use cases)
Round to nearest 512 MB

VM Heap (`vm.heapSize` in MB)

Scale with RAM: max(256, ramSize / 8)
Cap at 576 MB

GPU settings

hw.gpu.enabled=yes always
hw.gpu.mode based on user preference (default: auto)

GL Transport tuning (for high-throughput rendering)

For Heavy/Maximum budgets:
- hw.gltransport=pipe
- hw.gltransport.asg.writeBufferSize=2097152 (2 MB, up from default 1 MB)
- hw.gltransport.asg.writeStepSize=8192 (up from 4096)
- hw.gltransport.asg.dataRingSize=65536 (up from 32768)
- hw.gltransport.drawFlushInterval=400 (more frequent flushes)
For Moderate:
- hw.gltransport=pipe
- hw.gltransport.asg.writeBufferSize=1048576
- hw.gltransport.asg.writeStepSize=4096
- hw.gltransport.asg.dataRingSize=32768
- hw.gltransport.drawFlushInterval=600
For Light: leave defaults

Boot optimization

fastboot.forceFastBoot=yes always
firstboot.bootFromLocalSnapshot=true always
firstboot.bootFromDownloadedSnapshot=true always

Storage

userdata.useQcow2=true (efficient copy-on-write)

Step 5: Present the recap

Show a clear, formatted table comparing current vs proposed settings for each selected AVD. Use this format:

## AVD: <name>

Host: <cpu_brand> | <total_cores> cores | <total_ram_gb> GB RAM
Budget: <budget_level> (<percentage>%)

| Setting                              | Current       | Proposed      | Change   |
|--------------------------------------|---------------|---------------|----------|
| hw.cpu.ncore                         | 4             | 6             | +2 cores |
| hw.ramSize                           | 2048 MB       | 4096 MB       | +2048 MB |
| ...                                  | ...           | ...           | ...      |

Settings that are already optimal will not be listed.

Highlight any settings where the proposed value is LOWER than current (e.g., if user picked a lighter budget than what's currently configured) with a warning.

Step 6: Ask for approval

Use AskUserQuestion to ask the user to confirm the changes. Options:

"Apply all changes" (Recommended)
"Let me pick which changes to apply"
"Cancel"

If the user wants to pick, show each change individually and let them accept/reject.

Step 7: Apply changes

Modify the config.ini file for each selected AVD. Use sed or equivalent to update existing keys in-place, and append any keys that don't exist yet.

IMPORTANT: Before modifying, create a backup of the original config:

cp ~/.android/avd/<name>.avd/config.ini ~/.android/avd/<name>.avd/config.ini.bak

After applying, tell the user:

Changes have been applied
A backup was saved as config.ini.bak
They need to cold boot the emulator for all changes to take effect (wipe the snapshot or use "Cold Boot Now" in AVD Manager)
If using hardware-qemu.ini, note that some settings are copied from config.ini on cold boot

Important notes

NEVER modify a running emulator's config without warning the user that changes won't take effect until restart
The config.ini is the source of truth — hardware-qemu.ini is generated from it on cold boot
On Apple Silicon Macs, ARM64 system images run natively without translation, which is already a huge performance win
If the emulator version is old, suggest updating it via Android SDK Manager for latest performance improvements
Always preserve settings you don't understand or that aren't performance-related