Performance Profiler Agent: Stop Guessing, Start Measuring

Performance bugs are some of the most expensive problems in software engineering. They’re subtle, they compound over time, and they’re notoriously hard to reproduce. A query that runs fine under development load can bring down production under real traffic. A memory leak that takes hours to manifest will still take down your service at 3am. Most developers know their application is slow — they just don’t know where or why.

The Performance Profiler agent for Claude Code changes that equation. Instead of spending hours hunting through stack traces, guessing at algorithmic complexity, or manually writing profiling boilerplate, you get an expert system that knows how to instrument, measure, and optimize across your entire stack. It covers Node.js heap analysis, database query tuning, frontend Core Web Vitals, load testing strategies, and APM integration — all from a single agent you invoke directly in your development workflow.

The real value isn’t just speed. It’s precision. This agent doesn’t suggest generic “optimize your queries” advice. It gives you instrumented code, profiling configurations, and concrete optimization strategies based on what you’re actually running.

When to Use the Performance Profiler Agent

This agent is designed to be used proactively, not just when things are already on fire. The description explicitly calls this out — and it’s worth taking seriously. By the time a performance issue is visible to users, you’ve already lost the easy wins.

Diagnosing Production Bottlenecks

Your API endpoints are slow. Response times are creeping up. You have New Relic or Datadog telling you something is wrong, but the traces aren’t pointing to an obvious culprit. This agent can help you design targeted profiling sessions, instrument specific code paths, and interpret what your profiling data is telling you.

Investigating Memory Leaks

Memory leaks in long-running Node.js services are particularly nasty. The process looks healthy at startup, slowly consumes more heap over hours or days, then crashes. The Performance Profiler agent knows how to set up heap snapshots, configure @airbnb/node-memwatch for leak detection, and walk you through heap diffing to identify what’s accumulating and why.

Pre-launch Load Testing

Before shipping a new feature or scaling a service, you need to know how it behaves under load. This agent can help you design meaningful load tests, set performance baselines, identify where your system starts to degrade, and plan capacity accordingly — before real users find the limits for you.

CI/CD Performance Regression Detection

Performance regressions are easy to introduce and hard to catch in code review. Adding the right performance assertions to your pipeline — with proper baselines and trend tracking — is exactly the kind of systematic work this agent is built for.

Database Query Optimization

N+1 queries, missing indexes, unbounded result sets — database performance issues follow predictable patterns, but identifying them requires methodical analysis. This agent can help you profile query execution, interpret EXPLAIN output, and design appropriate indexes and connection pooling configurations.

Frontend Performance Audits

Bundle size creep, layout shifts, slow time-to-interactive — Core Web Vitals failures hurt SEO and user experience alike. The agent covers frontend profiling including rendering performance and bundle analysis, not just server-side concerns.

Real-World Examples

Scenario: Node.js Service Slowly Running Out of Memory

A backend engineer notices that a Node.js microservice needs to be restarted every 48 hours. Memory usage climbs steadily from ~200MB at startup to over 1.2GB before the process becomes unresponsive.

Developer: Our user-service process needs a restart every couple days.
           Memory starts at 200MB and climbs to 1.2GB. We're using
           Express with a Redis cache layer. Where do I even start?

Performance Profiler: This pattern — slow, linear growth over time —
           is classic accumulation rather than a sudden leak. Before
           adding instrumentation, let's rule out the obvious suspects.

           First, check your Redis client configuration. If you're
           creating new client instances per request rather than
           reusing a connection pool, or if event listeners are being
           added without cleanup, that will show up exactly like this.

           Add this instrumentation to catch it in your current
           process before we set up heap snapshots:

           [generates memwatch configuration, listener cleanup checks,
           and heap baseline code]

           Run that for 2-3 hours and share the output. The leak
           growth rate will tell us whether we need to go deeper
           with heap diffing or whether this is a configuration fix.

Scenario: API Endpoint Latency Spike Under Load

An e-commerce team notices that their product search endpoint is fine at normal traffic but degrades significantly during peak hours — p99 latency goes from 120ms to over 2 seconds.

Developer: /api/search is fine normally but falls apart at peak
           load. We have Elasticsearch behind it. p99 goes from
           120ms to 2+ seconds when we hit about 500 concurrent
           users. Database CPU looks normal.

Performance Profiler: The Elasticsearch CPU staying normal while
           your API latency spikes is a useful signal — this is
           probably a connection pool exhaustion or thread starvation
           issue, not a query problem.

           At 500 concurrent users, if your connection pool is sized
           for 50 connections, requests are queueing. That queue
           time adds up fast.

           Let's add request timing instrumentation that breaks down
           the latency into components: time waiting for a connection,
           time for the Elasticsearch round-trip, and time processing
           results on your side.

           [generates PerformanceObserver configuration and HTTP
           request timing breakdown code]

           Once you can see where the time is going, we can size
           the pool correctly and add circuit breaker logic so
           degraded performance doesn't cascade.

What Makes This Agent Powerful

Full-Stack Coverage in a Single Context

Most performance tools are specialized — you have one tool for APM, another for load testing, another for frontend auditing. This agent maintains expertise across the complete performance domain: application-level profiling, memory and garbage collection, CPU utilization, network and API performance, database optimization, and frontend metrics. You don’t have to context-switch between different mental models.

Instrumentation-First Approach

The agent doesn’t just tell you what to look for — it generates working instrumentation code. The Node.js profiler class in its knowledge base is production-ready, covering PerformanceObserver setup, V8 CPU profiling, memwatch integration for leak detection, and metric collection. You get code you can drop into your application immediately, not abstract advice.

Structured Performance Methodology

The agent follows a disciplined framework: establish baselines before optimizing, use load testing to find real capacity limits, integrate performance into CI/CD pipelines so regressions get caught automatically, and monitor continuously rather than reactively. This is how performance engineering works at scale, applied to your specific situation.

Root Cause Orientation

Symptom-chasing wastes time. This agent is trained to identify the actual failure mode — connection pool exhaustion, event listener accumulation, N+1 query patterns, bundle composition issues — rather than suggesting generic optimizations that may not apply to your situation.

How to Install the Performance Profiler Agent

Installing this agent takes about two minutes. Claude Code automatically loads agents defined in your project’s .claude/agents/ directory, so no additional tooling or configuration is required.

Step 1: In your project root, create the agents directory if it doesn’t exist:

mkdir -p .claude/agents

Step 2: Create the agent file:

touch .claude/agents/performance-profiler.md

Step 3: Open .claude/agents/performance-profiler.md and paste the full agent system prompt into it. The file should start with the agent’s identity declaration and include the complete Core Performance Framework and Technical Implementation sections.

Step 4: Claude Code will detect the agent automatically the next time you start a session. You can invoke it explicitly by referencing the Performance Profiler in your prompt, or Claude Code may suggest it proactively when you describe performance-related problems.

The agent file lives in your repository, which means it travels with your codebase. Your entire team gets access to the same performance analysis tooling, and you can extend or customize the agent’s system prompt as your stack evolves.

Conclusion and Next Steps

If you’re not already doing systematic performance profiling, the first step is establishing baselines. You can’t know if you’re improving without a reference point. Install this agent, then use it to instrument your most critical endpoints and establish what “normal” looks like — response time distributions, memory growth rates, database query counts per request.

Once you have baselines, the next priority is getting performance into your CI/CD pipeline. Catching regressions at pull request time is dramatically cheaper than debugging them in production. The agent can help you design the right thresholds and assertions for your specific performance targets.

For teams dealing with an active performance incident, start with the memory leak or latency scenario most relevant to what you’re seeing. The instrumentation code the agent generates is designed to be added to running services with minimal disruption — you don’t need to wait for a maintenance window to start collecting data.

Performance engineering is a discipline, not a one-time fix. This agent is built to support that ongoing practice — from initial diagnosis through optimization through continuous monitoring. Start measuring.

Agent template sourced from the claude-code-templates open source project (MIT License).