cc-profiler

External performance profiling harness for Claude Code TUI.

Measures UI responsiveness and correlates latency with system resource usage — without modifying Claude Code itself.

Installation

# Global install
npm install -g cc-profiler

# Or use npx (no install required)
npx cc-profiler claude

Requirements: Node.js 22+

Quick Start

# Profile a Claude Code session
cc-profiler claude

# When done, quit Claude normally (Ctrl+C or /exit)
# Output:
#   cc-profiler session complete
#   - Output: ./cc-profiler-session-2026-02-04-135044
#   - Data:   ./cc-profiler-session-2026-02-04-135044/data.json
#   - Report: ./cc-profiler-session-2026-02-04-135044/report.html

# Open report.html in a browser to view results

Examples

# Basic profiling
npx cc-profiler claude

# With correlation (extracts tool/token metadata)
npx cc-profiler --correlate-jsonl claude

# Fixed 5-minute session
npx cc-profiler --duration 5m claude

# Pass flags to Claude (note the --)
npx cc-profiler -- claude --resume abc123

# Both cc-profiler and Claude flags
npx cc-profiler --correlate-jsonl --duration 10m -- claude --dangerously-skip-permissions

CLI Reference

cc-profiler [options] [--] <command...>

Options

Flag	Default	Description
--output <dir>	Auto-generated	Output directory for session data
--duration <time>	None	Auto-stop after duration (e.g., 5m, 30s)
--binary <path>	—	Path to claude binary (overrides first arg)
--disable-mcps	false	Run with MCP servers disabled (A/B testing)
--correlate-jsonl	false	Parse Claude session JSONL to extract metadata (tool names/counts, record sizes, token counts if present)
--turn-hotkey <spec>	alt+t	Manual turn marker hotkey (alt+t or off)
--burst-idle-ms <ms>	30	Idle gap to end output burst detection
--sample-interval-ms <ms>	100	Process sampling interval
--interaction-timeout-ms <ms>	2000	Timeout for interactions with no output

Privacy Flags (opt-in, makes output NOT shareable)

Flag	Description
--unsafe-store-paths	Store plaintext paths in data.json
--unsafe-store-command	Store plaintext command + args
--unsafe-store-errors	Store full error messages (may contain paths)

Subcommands

# Generate report from existing data
cc-profiler report <data.json> [--out <path>]

# Add marker to active session (from another terminal)
cc-profiler mark [label] [--unsafe-plaintext-label]

Passing Flags to Claude

Use -- to separate cc-profiler flags from the target command:

cc-profiler --duration 5m -- claude --dangerously-skip-permissions

Understanding the Output

Session Bundle

Each session creates a directory containing:

File	Description
data.json	Raw metrics (machine-readable)
report.html	Interactive charts (open in browser)
markers.jsonl	Timeline annotations

Latency Metrics (T1/T2/T3)

Metric	Description
T1	Time from keystroke to first output byte
T2	Time from keystroke to end of output burst (response complete)
T3	Total output bytes in the burst

Turn = a user message (detected when Enter is pressed, or manually via Alt+T)

Process Metrics

Metric	Platforms
RSS (memory)	All
CPU %	All
Page faults	Linux
Context switches	Linux
File descriptors	Linux
Thread count	Linux

Report Charts

The HTML report includes:

• RSS + CPU over time — Memory and CPU usage throughout the session
• Turn latency over time — Response time trends (are later turns slower?)
• Turn latency vs turn index — Scatter plot of latency per turn

Privacy

By default, cc-profiler produces shareable output:

• No plaintext I/O — Only timestamps and byte counts, never what you typed or received
• Hashed paths — File paths stored as SHA-256 hashes
• Redacted errors — Only error class/code, not full messages
• Names only — MCP server and plugin names (no URLs or secrets)

Optional metadata correlation:

• --correlate-jsonl reads the JSONL locally and stores metadata only in data.json (no plaintext prompts/responses).

Use --unsafe-* flags only for local debugging.

A/B Testing

Compare performance with/without MCP servers:

# Control: MCPs enabled (normal)
cc-profiler --output ./with-mcps claude

# Treatment: MCPs disabled
cc-profiler --output ./no-mcps --disable-mcps claude

The --disable-mcps flag uses a temporary settings overlay. Your real ~/.claude/settings.json is never modified.

Contributing

See CONTRIBUTING.md for development setup and guidelines.

License

MIT