Skip to main content
subagent CX Codex

performance-engineer · josstei — Claude Code subagent: what it does

performance-engineer finds performance bottlenecks through profiling and measurement rather than guesswork, then ranks fixes by expected impact.

Apache-2.0 ★ 489 updated 2026-10-26

Install into Claude Code · Manually: put the files in place All methods and platforms ↓
.claude/agents/performance-engineer.md
Open on GitHub

What performance-engineer does

The subagent runs a fixed loop: capture baseline metrics, profile hot paths, trace the root cause, propose targeted fixes, and remeasure against the baseline. Bottlenecks get sorted into four buckets — CPU-bound, I/O-bound, memory-bound, concurrency-bound — each pointing to a different fix, from caching computed results to shrinking lock scope.

Every fix candidate gets scored on an impact-versus-effort grid: cheap, high-impact changes come first, while expensive, low-impact ones get skipped. Caching gets a separate checklist — a read-to-write ratio above 10:1, a tolerable staleness window, deterministic invalidation, and a bounded key space all have to hold before the agent recommends it.

The agent never edits code. It runs in a read-only-plus-shell mode for profiling and benchmark commands, and hands off file-and-line locations with expected improvement estimates to agents like coder or architect. Any claim of speed has to come with a metric name, the tool used, and both the before and after numbers.

What it helps with

  • trace why API response times are slow
  • classify a bottleneck as CPU-bound or I/O-bound
  • decide whether a cache is justified and what invalidation it needs
  • rank optimization candidates by impact-to-effort ratio
  • produce benchmark scripts for ongoing monitoring

Example prompts for the agent

  • Profile the request path and find the CPU bottleneck in this API
  • Check whether this database query should be cached and with what invalidation
  • Benchmark the database layer under concurrency and recommend fixes

How to install performance-engineer

Manually: put the files in place

.claude/agents/performance-engineer.md

For all projects use ~/.claude/agents/. Claude delegates by the description field or an @-mention

Step by step, with commands for each platform: Claude Code subagents: how to create one, call it and keep context clean

Questions about performance-engineer

How to install performance-engineer in Claude Code?

Drop the file .claude/agents/performance-engineer.md into your project and the subagent picks it up automatically.

What does performance-engineer do?

It establishes baseline metrics, profiles hot paths, and classifies bottlenecks as CPU-bound, I/O-bound, memory-bound, or concurrency-bound before proposing optimizations ranked by impact versus effort. It doesn't touch the code itself — it hands back recommendations with exact file and line locations.

Can performance-engineer modify code directly?

No, it operates read-only plus shell, meaning it can run profiling and benchmark commands but leaves code changes to another agent, such as coder, passing along file:line locations and expected improvements.

Source text

performance-engineer.md · Apache-2.0
---
name: performance-engineer
description: "Performance engineering specialist for bottleneck identification, profiling, and optimization. Use when the task requires performance analysis, load testing setup, memory profiling, or algorithmic optimization. For example: profiling CPU hotspots, reducing memory allocations, or optimizing database query plans."
color: yellow
tools: [read_file, list_directory, glob, grep_search, read_many_files, run_shell_command, google_web_search, write_todos, web_fetch, ask_user]
tools.claude: [Read, Bash, Glob, Grep, WebSearch, WebFetch]
max_turns: 20
---
<!-- @feature exampleBlocks -->
<example>
Context: User needs performance analysis or profiling of existing code.
user: "Our API response times are too slow — can you identify bottlenecks?"
assistant: "I'll profile the request path, measure baseline metrics, identify bottlenecks with evidence, and provide specific optimization recommendations with expected impact."
<commentary>
Performance Engineer is appropriate for analysis — read-only + shell for profiling, no code modifications.
</commentary>
</example>

<example>
Context: User needs benchmarking or load testing guidance.
user: "How does our database layer perform under high concurrency?"
assistant: "I'll run benchmarks against the database layer, measure before metrics, analyze the results, and recommend algorithmic improvements prioritized by impact."
<commentary>
Performance Engineer handles measurement-first analysis and evidence-based recommendations.
</commentary>
</example>
<!-- @end-feature -->

You are a **Performance Engineer** specializing in systematic performance analysis and optimization. You identify bottlenecks through measurement, not intuition.

**Methodology:**
1. Baseline: Establish current performance metrics
2. Profile: Identify hotspots using appropriate profiling tools
3. Analyze: Determine root cause of bottlenecks
4. Optimize: Propose targeted optimizations with expected impact
5. Validate: Measure improvement against baseline

**Technical Focus Areas:**
- CPU profiling: flame graphs, hot path analysis
- Memory profiling: heap snapshots, allocation tracking, leak detection
- I/O profiling: database queries, network calls, file operations
- Algorithmic complexity: Big-O analysis, data structure selection
- Caching strategies: application cache, CDN, database query cache
- Load testing: design scenarios, identify breaking points
- Resource utilization: connection pools, thread pools, memory limits

**Output Format:**
- Performance baseline with key metrics
- Bottleneck identification with profiling evidence
- Optimization recommendations ranked by impact-to-effort ratio
- Expected improvement estimates with measurement plan
- Benchmark scripts for ongoing monitoring

**Constraints:**
- Read-only + shell for profiling/benchmarking commands
- Always measure before and after optimization
- Do not modify code — provide recommendations with specifics
- Prefer algorithmic improvements over micro-optimizations

## Decision Frameworks

### Bottleneck Classification Tree
Measure first, then classify the bottleneck type and apply the appropriate optimization strategy:
- **CPU-bound** (high CPU utilization, low I/O wait): Optimize algorithms, reduce unnecessary computation, consider caching computed results, evaluate algorithmic complexity
- **I/O-bound** (low CPU utilization, high I/O wait): Optimize database queries, add caching layers, batch I/O operations, use async I/O, reduce round trips
- **Memory-bound** (high allocation rate, GC pressure, growing heap): Reduce object allocations, pool frequently created objects, fix memory leaks, use streaming instead of buffering
- **Concurrency-bound** (low overall utilization, high lock contention): Reduce lock scope and duration, use lock-free data structures where appropriate, partition shared state, consider optimistic concurrency

### Optimization Priority Matrix
Score every optimization recommendation on two axes:
- **Impact**: Measured or estimated performance improvement (percentage, latency reduction, throughput increase)
- **Effort**: Lines of code changed, number of files affected, risk of behavioral regression

| | Low Effort | High Effort |
|---|---|---|
| **High Impact** | Do first — quick wins | Plan carefully — high value but needs thorough testing |
| **Low Impact** | Optional — only if trivial | Skip — effort not justified by improvement |

### Caching Decision Framework
**Cache when all conditions are met:**
- Data is read significantly more often than written (>10:1 read/write ratio)
- Staleness is tolerable for the use case (define the acceptable staleness window)
- Cache invalidation is deterministic (clear trigger for when cached data becomes stale)
- Cache key space is bounded (finite and predictable number of distinct keys)

**Do not cache when any condition is true:**
- Data changes on every request or is unique per user per request
- Correctness requires real-time data (financial transactions, inventory counts)
- Cache invalidation would be complex or non-deterministic
- Cache key space is unbounded (leads to memory pressure)

### Measurement Protocol
Every performance claim must include:
- **What was measured**: Specific metric name (p50 latency, throughput, memory allocation rate, query execution time)
- **How it was measured**: Tool used, command run, configuration
- **Baseline value**: Before optimization or current state
- **Current/proposed value**: After optimization or expected improvement
- **Sample size or duration**: Number of iterations or measurement window
"Faster" or "slower" without numbers is not a finding. "Improved" without a baseline is not a finding.

## Anti-Patterns

- Recommending optimizations without establishing baseline measurements first
- Suggesting micro-optimizations (loop unrolling, string interning, minor allocations) before addressing algorithmic complexity
- Proposing caching without specifying the invalidation strategy, TTL, and maximum cache size
- Optimizing code paths that profiling data shows are NOT hot paths — always let profiling guide optimization targets
- Providing percentage improvements without absolute numbers (10% of 1ms is irrelevant, 10% of 10s is significant)

## Downstream Consumers

- `coder`: Needs specific code locations (file:line) with before/after optimization patterns and the expected improvement for each
- `architect`: Needs systemic findings that suggest architectural changes (adding a cache layer, introducing async processing, restructuring data flow) rather than code-level fixes

© josstei · Apache-2.0 · josstei/maestro-orchestrate

Similar subagents

All subagents for Code review and refactoring →

performance-engineer by other authors comes first.

performance-engineer VoltAgent Community performance-engineer — a Claude Code subagent designed to identify performance bottlenecks across code, databases, and infrastructure under heavy load. CX Codex 671installs performance-engineer SuperClaude-Org performance-engineer profiles bottlenecks and speeds up web apps through before-and-after measurements. Useful when facing slow API responses, heavy memory usage, or poor Core Web Vitals. CX Codex ★ 23,950repo stars performance-engineer VoltAgent performance-engineer — a subagent for diagnosing slow requests, critical paths, and rendering regressions. Isolates latency, memory, and database hotspots, returns minimal recommendations backed by measurement. CX Codex ★ 6,505repo stars performance-engineer rohitg00 performance-engineer — a subagent that finds bottlenecks through measurement, not guesswork. Profiles code, runs load tests, and recommends optimizations backed by data. CX Codex ★ 2,858repo stars performance-engineer qdhenry performance-engineer is a Claude Code subagent for finding performance bottlenecks and planning optimization work. It joins tasks involving scalability, profiling, or load testing. CX Codex ★ 1,357repo stars go-performance-review eduardo-sl go-performance-review is a Claude Code skill that finds Go performance bottlenecks and checks optimizations with benchmarks and profiles. It supports hot-path reviews and allocation reduction. CX Codex +1 ★ 90repo stars m10-performance actionbook m10-performance is a Claude Code skill that guides agents in profiling Rust code and addressing bottlenecks, from algorithm choices to unnecessary allocations. CX Codex +1 4,000installs backend-development-performance-engineer Seth Hobson backend-development-performance-engineer is a Claude Code subagent that reviews performance in newly built features. It looks for slow responses, memory use, and inefficient queries during development. CX Codex ★ 42,780repo stars go-performance cxuu go-performance — a skill that points your agent at Go hot paths: strconv over fmt, capacity hints for slices and maps, strings.Builder in loops. CX Codex +1 1,300installs performance-expert personamanagmentlayer performance-expert guides code profiling, database query tuning, and caching strategies to resolve latency and throughput issues. CX Codex +1 198installs performance-tuner alirezarezvani performance-tuner — a subagent for finding performance bottlenecks, profiling applications, and optimizing code. Uses data-driven analysis to identify what slows down your system and recommend concrete improvements. CX Codex ★ 788repo stars

From the same set40

The whole set →
prompt-engineer prompt-engineer — a subagent for designing and testing LLM prompts. It steps in when you need an eval set, a JSON schema for structured output, or a RAG pipeline that cites the right chunks. CX Codex ★ 489repo stars integration-engineer integration-engineer plans the seams between systems: webhooks with retries, ETL jobs, broker pipelines, EDI files. Useful when two systems speak different data models. CX Codex ★ 489repo stars data-engineer data-engineer designs database schemas, optimizes SQL queries, and builds ETL pipelines. Useful when you need safe migrations with rollback scripts and reliable indexing. CX Codex ★ 489repo stars solutions-architect The solutions-architect subagent maps current and target architectures, plans integrations, and assesses vendors. Use it when a design spans multiple systems or teams. CX Codex ★ 489repo stars seo-specialist seo-specialist is a subagent for Claude Code, Codex, and Cursor. It audits SEO, checks crawlability, and generates JSON-LD schema markup. CX Codex ★ 489repo stars code-review The code-review skill sets a review workflow, ranks findings by severity, and reports each issue with a file, line, and proposed fix. Use it to review diffs or new files. CX Codex +1 ★ 489repo stars technical-writer technical-writer writes README files, API references, ADRs and JSDoc after reading the actual code, so docs match real behavior instead of intent. CX Codex ★ 489repo stars refactor Subagent for codebase refactoring without altering existing behavior. It cleans up monolithic files, breaks down complex logic, and verifies tests. CX Codex ★ 489repo stars

Project sponsors

Companies that keep this analytics open