AGENTS.md

Unjank is a set of four agent skills that pull screen rendering data out of Firebase Performance (via its BigQuery export) and show you which screens in an Android, iOS, or Flutter app are janky, how bad it is, and which way it's trending. There's an optional fourth skill that fixes the code.

Use this when

The user has a mobile app with Firebase Performance and wants to know where the jank is. Actual phrasings that should make you reach for this:

• "which screens in my app are slow / janky / dropping frames"
• "we have Firebase Performance, can you pull the numbers"
• "frozen frames", "slow rendering", "frame drops", "ANR-adjacent stuff"
• "build me a performance dashboard for the app"
• "query our Firebase perf data in BigQuery"
• "HomeFragment feels laggy, fix the rendering"

Two things have to be true or none of this works: the app ships the Firebase Performance SDK, and BigQuery export is turned on in the Firebase Console. If either is missing, say so first — the data does not exist and no amount of querying will produce it.

Do not reach for this for general profiling, startup time, network latency, or app size. It only covers screen traces: frozen frame ratio and slow frame ratio per screen.

How to use it

Install into the target project (run from its root — the installers refuse to run without a .git directory):

npx unjank-perf

or

curl -fsSL https://raw.githubusercontent.com/no-hup/unjank/main/install.sh | bash

Both copy skills/perf-{setup,query,dashboard,fix} into .claude/skills/. Claude Code registers skills at startup, so the user has to restart or start a new conversation before the slash commands exist. Tell them that; it is the most common reason someone thinks the install failed.

Then, in order:

The skills talk to each other through files in .perf/, which the setup skill adds to .gitignore. Each one is independently re-runnable — re-running /perf-query just refreshes the JSON.

/perf-fix works in tiers and you should respect them. T1 (cached DateFormatter, DiffUtil, allocations hoisted out of onDraw) it applies directly. T2 (async image loading, flattened layouts, Compose remember) it shows as a diff and waits for a human. T3 it only suggests. T4 (lock contention, SDK swaps, architecture) it writes down and does not touch. Exhaust a tier before moving to the next one. It's also marked disable-model-invocation: true — only run it when the developer asks for a named screen by name, not because you noticed a perf smell while doing something else.

Gotchas

• Data lags about 48 hours behind enabling the export. A fresh setup returning zero rows is usually this, not a broken query.
• Queries are partition-pruned and cost roughly $0.05 for 30 days. /perf-query stops outright if the dry run estimates over 100 GB — that means partition pruning broke, so don't override it.
• Auth is plain gcloud auth login plus gcloud auth application-default login. No service accounts, no key files. The account needs roles/bigquery.dataViewer and roles/bigquery.jobUser.
• Flutter gets one platform at a time. Run /perf-setup again to switch between Android and iOS; the dashboards are separate.
• Build flavors and applicationIdSuffix trip up app-ID detection. Setup will ask; the base ID without the suffix is the right answer.
• The dashboard pulls Chart.js from a CDN, so it needs a network connection to render.
• The installers ping an anonymous hit counter. UNJANK_NO_ANALYTICS=1 turns it off.