performance-profiler — Claude Code subagent: profile and optimize
A Claude subagent that hunts down performance bottlenecks, memory leaks and load problems. Useful when an app is slow and the cause is not obvious.
npx claude-code-templates@latest --agent development-tools/performance-profilerWhat performance-profiler does
The subagent covers several areas at once: response times and throughput, memory leaks and garbage collection, CPU load, API latency, database queries and frontend metrics like bundle size. It starts by capturing a baseline, then compares later runs against it.
Bundled Node.js profiling scripts rely on perf_hooks, v8-profiler-next and @airbnb/node-memwatch, so those packages need to be present in your project. Reports land in ./performance-reports: a CPU profile as .cpuprofile and a heap snapshot as .heapsnapshot. There is also event loop delay monitoring that warns when the mean delay goes above 10 ms.
The agent is meant to be invoked proactively, stepping in whenever a task touches performance. Its toolset is limited to reading, writing, editing files and Bash, so it will not wire up an external APM service for you. CPU analysis works on a profile the script has already saved, so nothing gets reviewed until the profiler actually runs against your app.
What it helps with
- find the function eating the most CPU
- catch a memory leak and capture a heap snapshot
- measure event loop delay under load
- compare performance before and after a change
- break down slow database queries and API responses
Example prompts for the agent
- profile the CPU of this Node.js service and list the hottest functions
- check the queue handler for a memory leak
- compare metrics before and after the database query change
How to install performance-profiler
1claude-code-templates
npx claude-code-templates@latest --agent development-tools/performance-profiler2Manually: put the files in place
.claude/agents/performance-profiler.mdFor all projects use ~/.claude/agents/. Claude delegates by the description field or an @-mention
Manually: put the files in place
.codex/agents/performance-profiler.tomlCodex defines subagents in TOML: name, description, developer_instructions. Move the Markdown text into developer_instructions by hand. For all projects use ~/.codex/agents/
Manually: put the files in place
.cursor/agents/performance-profiler.mdCursor also reads .claude/agents/
Step by step, with commands for each platform: Claude Code subagents: how to create one, call it and keep context clean
Questions about performance-profiler
How do I install performance-profiler in Claude?
Use the templates CLI: npx claude-code-templates@latest --agent development-tools/performance-profiler. The subagent file lands at .claude/agents/performance-profiler.md.
What does performance-profiler do?
It profiles an application: response times, CPU load, memory leaks, event loop delay and database work. Then it points at what to optimize.
What do the profiling scripts need?
The Node.js scripts depend on v8-profiler-next and @airbnb/node-memwatch, plus the built-in perf_hooks. Reports are written to ./performance-reports.