claude-monitor

## Overview

Performance monitor for Claude Code and the local system. Diagnoses slowness, measures CPU/RAM/disk, checks API latency and generates system-health reports.

## When to Use This Skill

- When the user mentions "slow" or related topics
- When the user mentions "slowness" or related topics
- When the user mentions "lag" or related topics
- When the user mentions "laggy" or related topics
- When the user mentions "freezing" or related topics
- When the user mentions "claude is slow" or related topics

## Do Not Use This Skill When

- The task is unrelated to claude monitor
- A simpler, more specific tool can handle the request
- The user needs general-purpose assistance without domain expertise

## How It Works

A skill to diagnose and fix slowness problems in Claude Code and the system.
It determines whether the bottleneck is local (PC) or remote (Claude API) and suggests corrective actions.

## When To Use

- The user complains that Claude Code is slow or freezing
- Switching between conversation sessions takes a while to load
- Claude's responses take too long
- The PC feels slow while using Claude Code
- Any mention of performance, lag, or slowness

## 1. Quick Diagnosis (Health_Check.Py)

ALWAYS run this as the first step:

```bash
python C:\Users\renat\skills\claude-monitor\scripts\health_check.py
```

The script analyzes in ~3 seconds:
- **CPU**: Current usage and per core. >80% = likely bottleneck
- **RAM**: Total, used, available. >85% = memory pressure
- **Browsers**: Processes and RAM per browser. >5GB total = too many tabs
- **Claude Code**: Processes and RAM consumed
- **Disk**: Free space. <10% = impacts swap/performance
- **Network**: Latency to the Claude API endpoint
- **Diagnosis**: Automatic classification of the problem with suggestions

## 2. Interpret The Result

The script returns a JSON with `diagnosis` containing:

- `bottleneck`: "cpu" | "ram" | "browsers" | "disk" | "network" | "claude_api" | "ok"
- `severity`: "critical" | "warning" | "ok"
- `suggestions`: List of recommended actions
- `summary`: A summary to show the user

**Show the `summary` to the user** and offer to run the suggestions.

## 3. Automatic Corrective Actions

Based on the diagnosis, offer the user:

#### If CPU is high (>80%):
- List the processes consuming the most CPU
- Suggest closing unnecessary heavy processes
- Check whether Windows Update is running in the background

#### If browsers are heavy (>5GB RAM or >40 processes):
```bash
python C:\Users\renat\skills\claude-monitor\scripts\health_check.py --browsers-detail
```
Shows RAM per browser and suggests which to close. **Never close processes without the user's explicit permission.**

#### If the disk is full (>85%):
- Show the largest folders
- Suggest cleaning Temp, browser caches, the recycle bin

#### If the network is slow (latency >500ms):
- Test the connection to api.anthropic.com
- Suggest checking the VPN, proxy, or WiFi connection

## 4. Continuous Monitoring (Optional)

If the user wants background monitoring:

```bash
python C:\Users\renat\skills\claude-monitor\scripts\monitor.py --interval 30 --duration 300
```

Parameters:
- `--interval`: Seconds between each sample (default: 30)
- `--duration`: Total duration in seconds (default: 300 = 5 min)
- `--output`: Log file path (default: monitor_log.json)
- `--alert-cpu`: CPU threshold for an alert (default: 80)
- `--alert-ram`: RAM % threshold for an alert (default: 85)

The monitor saves periodic snapshots and generates a report at the end with:
- CPU and RAM peaks
- Trend (improving/worsening/stable)
- Alert events detected
- Final recommendation

## 5. Claude Api Benchmark (Optional)

To test whether the slowness comes from the API:

```bash
python C:\Users\renat\skills\claude-monitor\scripts\api_bench.py
```

Measures the response time of the local Claude Code process (it does not make API calls).
Compares it with typical times and indicates whether it's within the expected range.

## Reference Thresholds

| Metric | OK | Warning | Critical |
|---------|-----|---------|----------|
| CPU % | <60% | 60-85% | >85% |
| RAM used % | <70% | 70-85% | >85% |
| Browser RAM | <3 GB | 3-6 GB | >6 GB |
| Browser processes | <30 | 30-60 | >60 |
| Free disk | >15% | 10-15% | <10% |
| Network latency | <200ms | 200-500ms | >500ms |

## Tips For The User

When presenting the diagnosis, include these contextual tips:

- **Many tabs = a lot of CPU/RAM**: Each browser tab is a separate process.
  50 tabs = 50 processes competing for resources.
- **Claude Code is heavy**: It runs several Electron processes. Consuming 3-5 GB is normal.
  But if it's using >6 GB with several sessions, consider closing old sessions.
- **Slow session switching**: Usually caused by high CPU or too many competing processes.
  The session needs to load the conversation history, and if the CPU is busy, it takes time.
- **Nearly full disk**: Affects swap (virtual memory) speed and can cause
  general slowness.

## Dependencies

- Python 3.10+
- psutil (installed automatically by the script if not available)
- No API key required

## Best Practices

- Provide clear, specific context about your project and requirements
- Review all suggestions before applying them to production code
- Combine with other complementary skills for comprehensive analysis

## Common Pitfalls

- Using this skill for tasks outside its domain expertise
- Applying recommendations without understanding your specific context
- Not providing enough project context for accurate analysis