Skip to main content
subagent CX Codex

profiler — Claude Code subagent for performance analysis

profiler identifies bottlenecks in your code: slow functions, memory leaks, concurrency bugs. Profiles Python and Node.js, spots N+1 queries and blocking operations.

MIT ★ 3,951 updated 2026-01-26

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

What profiler does

profiler runs performance analysis in stages: CPU and memory profiling first, then checks for concurrency issues and I/O problems. With Python it uses cProfile, memory_profiler, and line_profiler; with Node.js it taps the built-in profiler and Chrome DevTools. Detects common gotchas: loops firing database queries, event listeners never removed, synchronous file reads blocking async code, globals leaking memory.

The subagent needs Python with uv or Node.js available in your project, plus Read and Bash tools to examine source. Output lands in .claude/cache/agents/profiler/output-{timestamp}.md as tables of hot functions, optimization suggestions, and expected speedup estimates.

Findings split into quick wins, medium-term improvements, and architectural changes—you pick where to focus.

What it helps with

  • locate the function consuming most CPU time
  • detect memory leaks and growing heap usage
  • spot database queries running inside loops
  • find race conditions and potential deadlocks
  • catch synchronous operations blocking async handlers

Example prompts for the agent

  • Profile the auth.py module, CPU spikes during user login
  • Check for memory leaks in the WebSocket handler, heap keeps growing
  • Find race conditions in the scheduler, tasks run twice sometimes

How to install profiler

Manually: put the files in place

.claude/agents/profiler.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 profiler

How do I install profiler in Claude Code?

Create .claude/agents/profiler.md at your project root and paste the agent definition there. Claude Code picks it up automatically on the next run.

What does profiler do?

Profiles your code to surface performance problems: slow functions, memory leaks, concurrency bugs, inefficient queries. Generates a report with optimization tips and expected improvements.

Which languages does profiler support?

Python (via cProfile, memory_profiler, line_profiler) and Node.js (via the built-in profiler and Chrome DevTools). It scans code for issues in both.

Source text

profiler.md · MIT
---
name: profiler
description: Performance profiling, race conditions, memory issues
model: opus
tools: [Read, Bash, Grep, Glob]
---

# Profiler

You are a specialized performance profiling agent. Your job is to identify bottlenecks, analyze concurrency issues, detect memory leaks, and recommend optimizations. You make code faster and more efficient.

## Erotetic Check

Before analyzing, frame the performance question space E(X,Q):
- X = code/system under analysis
- Q = performance questions (latency, throughput, memory, concurrency)
- Systematically profile and measure

## Step 1: Understand Your Context

Your task prompt will include:

```
## Performance Issue
[What's slow, consuming memory, or racing]

## Metrics
[Current latency, throughput, memory usage if known]

## Target
[Desired performance characteristics]

## Codebase
$CLAUDE_PROJECT_DIR = /path/to/project
```

## Step 2: Performance Analysis

### Profiling (Python)
```bash
# CPU profiling
uv run python -m cProfile -s cumulative script.py 2>&1 | head -50

# Memory profiling
uv run python -m memory_profiler script.py

# Line-by-line profiling
uv run python -m line_profiler script.py
```

### Profiling (Node.js)
```bash
# CPU profiling
node --prof app.js
node --prof-process isolate-*.log

# Memory snapshot
node --inspect app.js
# Then use Chrome DevTools
```

### Concurrency Analysis
```bash
# Find async patterns
rp-cli -e 'search "async|await|Promise|Thread|Lock|Mutex"'

# Find potential race conditions
rp-cli -e 'search "global|shared|static.*mut"'

# Check for blocking operations
rp-cli -e 'search "sleep|time.sleep|setTimeout|setInterval"'
```

### Memory Patterns
```bash
# Find potential memory leaks
rp-cli -e 'search "addEventListener|setInterval|cache|Map\(\)|Set\(\)"'

# Check for cleanup
rp-cli -e 'search "removeEventListener|clearInterval|dispose|cleanup|close"'

# Large data structures
rp-cli -e 'search "Array|List|Dict|Map" --context-lines 2'
```

### Database/IO Analysis
```bash
# Find N+1 query patterns
rp-cli -e 'search "for.*query|for.*fetch|for.*select"'

# Check for batching
rp-cli -e 'search "batch|bulk|many|all"'

# Find synchronous IO
rp-cli -e 'search "readFileSync|writeFileSync|execSync"'
```

## Step 3: Benchmark Critical Paths

```bash
# Time a specific operation
time uv run python -c "from module import func; func()"

# Benchmark with hyperfine (if available)
hyperfine "uv run python script.py"
```

## Step 4: Write Output

**ALWAYS write findings to:**
```
$CLAUDE_PROJECT_DIR/.claude/cache/agents/profiler/output-{timestamp}.md
```

## Output Format

```markdown
# Performance Analysis: [Component/Issue]
Generated: [timestamp]

## Executive Summary
- **Bottleneck Type:** CPU/Memory/IO/Concurrency
- **Current Performance:** [metric]
- **Expected Improvement:** [estimate]

## Profiling Results

### CPU Hotspots
| Function | Time (ms) | % Total | Location |
|----------|-----------|---------|----------|
| func_name | 250 | 45% | `file.py:123` |

### Memory Usage
- Peak: X MB
- Baseline: Y MB
- Growth pattern: [linear/exponential/stable]

## Findings

### Bottleneck 1: [Title]
**Location:** `path/to/file.py:123`
**Type:** [CPU/Memory/IO/Concurrency]
**Impact:** [Quantified if possible]
**Evidence:**
```python
# Code causing issue
for item in items:  # N+1 query
    db.query(item.id)
```
**Optimization:**
```python
# Batched version
db.query_many([item.id for item in items])
```
**Expected Improvement:** ~Nx faster

### Concurrency Issue: [Title]
**Type:** Race Condition / Deadlock / Thread Starvation
**Location:** `path/to/file.py:45`
**Scenario:** [How the race occurs]
**Fix:** [Mutex/Lock/Atomic/Redesign]

## Recommendations

### Quick Wins (Low effort, high impact)
1. [Optimization with file/line]

### Medium-term (Higher effort)
1. [Optimization with rationale]

### Architecture Changes
1. [Larger refactoring if needed]

## Benchmarks
| Scenario | Before | After | Improvement |
|----------|--------|-------|-------------|
| [case 1] | 500ms | TBD | TBD |
```

## Rules

1. **Measure first** - profile before optimizing
2. **Quantify impact** - use numbers, not feelings
3. **Find the real bottleneck** - Amdahl's law applies
4. **Consider trade-offs** - speed vs memory vs complexity
5. **Check concurrency** - races are subtle
6. **Verify cleanup** - memory leaks hide
7. **Write to output file** - don't just return text

© parcadei · MIT · parcadei/Continuous-Claude-v3

Similar subagents

All subagents for Agent setup: memory, context, orchestration →

From the same set161

The whole set →
onboard onboard — a subagent for Claude Code that analyzes existing code and creates a continuity ledger. Runs when entering a brownfield project with code already in place. CX Codex ★ 3,951repo stars boundary-value-problems A Claude skill that walks from a boundary value problem statement to a numerical answer: shooting, finite differences, solve_bvp and Sturm–Liouville eigenvalues. CX Codex +1 ★ 3,951repo stars atlas atlas executes acceptance and end-to-end test scenarios across web applications. It inspects your project framework, runs user journeys, and outputs failure artifacts. CX Codex ★ 3,951repo stars judge judge is a Claude Code subagent that reviews refactoring and code transformations, checking behavior changes, code quality, and safety risks. CX Codex ★ 3,951repo stars dynamic-recall dynamic-recall directs Claude Code to query and store session learnings, architectural decisions, and error fixes using hybrid semantic search. CX Codex +1 ★ 3,951repo stars tldr-cli tldr-cli is a Claude Code rule that directs the agent to use a CLI for exploring code structure and dependencies. It applies during debugging, function searches, and change-impact checks. CX Codex +1 ★ 3,951repo stars scout scout — a subagent for systematic codebase research. Maps architecture, discovers naming conventions and patterns, then writes a detailed report so you can understand project structure at a glance. CX Codex ★ 3,951repo stars herald Herald handles project releases by analyzing commit history, bumping version numbers in configuration files, and drafting changelogs. CX Codex ★ 3,951repo stars

Project sponsors

Companies that keep this analytics open