profile-memory

Memory Profiling for Sidecar

Quick Triage

Symptom	Tool	Action
High RSS / memory growth	vmmap, pprof heap	Check system memory, then heap profile
Too many open files	lsof	Check FD count and breakdown
High CPU	pprof cpu, ps	Capture CPU profile
Goroutine leak	pprof goroutines	Check goroutine count and stacks
Plugin unresponsive	lsof + goroutines	Check SQLite locks, blocked goroutines

Triage flow: Is RSS high? -> Check FD count -> Check vmmap -> Check heap profile

System-Level Profiling (No pprof Required)

Find the Process

pgrep -f sidecar
ps aux | grep sidecar

Basic Stats

# RSS, VSZ, CPU%, thread count
ps -o pid,rss,vsz,%cpu,nlwp -p <PID>

# Human-readable RSS
ps -o pid,rss -p <PID> | awk 'NR>1{printf "%d MB\n", $2/1024}'

# Watch over time
while true; do ps -o rss,%cpu -p <PID> | tail -1; sleep 5; done

System Memory

macOS (vmmap):

vmmap --summary <PID>

Key sections: VM_ALLOCATE (Go heap), MALLOC (C heap/SQLite), Physical footprint, Swapped.

Red flags:

• RESIDENT SIZE >500MB for idle sidecar
• REGION COUNT in thousands for VM_ALLOCATE = mmap leak
• SWAPPED SIZE growing = memory pressure

Linux:

cat /proc/<PID>/status | grep -E 'VmRSS|VmSize|Threads'
pmap -x <PID> | tail -5
ls /proc/<PID>/fd | wc -l

File Descriptor Analysis

# Count and breakdown
lsof -p <PID> | wc -l
lsof -p <PID> | awk '{print $5}' | sort | uniq -c | sort -rn

# Find leaked files
lsof -p <PID> | grep REG | awk '{print $9}' | sort | uniq -c | sort -rn | head -20

# Check session file leaks
lsof -p <PID> | grep -c '\.claude/projects'
lsof -p <PID> | grep -c '\.codex/sessions'

# Watch FD count
while true; do echo "$(date): $(lsof -p <PID> 2>/dev/null | wc -l) FDs"; sleep 30; done

Healthy baselines: Total FDs 50-150, REG files 10-30, PIPEs 10-30, DIRs 5-15.

Red flags: 1000+ total FDs, same file opened 4+ times, growing count over time.