Run a performance optimization pass with a cross-functional team.
/perf [scope] [--backend-only] [--frontend-only] [--audit-only] [--deep]
--deep--audit-only)/lighthouse is lighter; or general code cruft, that’s /tech-debt/perf
What you’ll see: a quick codebase scan, a mode prompt (audit / targeted / deep), then a prioritized performance audit, findings classified CRITICAL/HIGH/MEDIUM/LOW with file:line citations, followed by fixes and a validation report if you picked a fixing mode.
/perf # full codebase audit, mode chosen interactively
/perf GET /api/products --backend-only # one endpoint: queries, caching, serialization
/perf --frontend-only # bundle size, code splitting, images, Web Vitals
/perf src/api/routes/ --audit-only # read-only report, no code changes — fast and cheap
/perf --deep # full team + load tests/benchmarks, most thorough
| Flag | Values | Default | What it does |
|---|---|---|---|
scope |
file, directory, feature, endpoint, all |
all |
What to audit/optimize |
--backend-only |
: | off | Limit to backend optimizations |
--frontend-only |
: | off | Limit to frontend optimizations |
--audit-only |
: | off | Report findings only: read-only, no code changes |
--deep |
: | off | Deep profiling: benchmarks and load tests if configured |
--audit-only or --deep.[1] fix remaining items, [2] run /qa commit, [3] create PR (/pr), [4] deeper analysis (/perf {scope} --deep), [5] done for now. The pass isn’t “finished” until you pick one, the report alone doesn’t close it out. (Skipped if autopilot is active.)completion-verifier agent runs a separate spec/plan-compliance check (only meaningful if a plan/spec file exists for the scope) and prints PASS, GAPS FOUND, or INCONCLUSIVE. This does not re-measure performance, that validation already happened in the QA phase above.| Agent | Model tier | Role |
|---|---|---|
| explore-light | haiku | Cheap hotspot scan before the team spins up |
| performance | sonnet | Leads the audit, prioritizes findings |
| architect | sonnet | Scalability assessment, stage-appropriate recommendations |
| backend | sonnet | Implements backend fixes (Targeted/Deep) |
| frontend | sonnet | Implements frontend fixes (Targeted/Deep) |
| qa | sonnet | Regression validation after optimization |
Models shown are defaults, loaded from model-policy.yml. A project with a custom model-policy override will use different models for some or all of these roles.
After the continuation menu, a separate completion-verifier agent (sonnet) runs a spec/plan-compliance check, it’s not part of the main team and doesn’t validate performance itself.
--audit-only.claude/knowledge/agents/performance.md; decisions and patterns to .claude/knowledge/shared/decisions.md and patterns.md| Problem | Fix |
|---|---|
| Run is expensive/slow for a quick question | Use --audit-only or narrow the scope to a file or endpoint |
| Optimizations broke a test | The QA validation phase reports it: fix before shipping, or revert the specific change |
| No load-test comparison in the report | Load tests only run in Deep mode, and only if a load-test tool (k6, locust, etc.) is already set up in the project: /perf does not install or configure one for you |
| Findings ignore project-specific known-slow patterns | Run /calibrate first so the team inherits project knowledge |
/perf can accumulate a lot of context, profiling output, benchmark data, and optimization proposals from multiple agents, especially after a --deep or full-codebase run. After the report, the skill prints a tip block to help you decide what to do next:
/compact with a summary of what was optimized so the what-changed context survives for the PR body.--audit-only), no changes made? Context pressure is low, either continue straight to planning fixes, or /clear and start a new session with a short prompt describing the audit’s key findings.