Best practices for Claude Code performance optimization, context management, storage cleanup, and troubleshooting slowdowns
Provides commands to diagnose and fix Claude Code slowdowns, including storage cleanup, context management, and performance troubleshooting. Use when experiencing lag, high storage usage, or slow response times.
/plugin marketplace add melodic-software/claude-code-plugins/plugin install claude-code-observability@melodic-softwareThis skill is limited to using the following tools:
references/context-management.mdreferences/known-issues.mdreferences/storage-management.mdComprehensive guidance for optimizing Claude Code performance. This skill covers storage management, context window optimization, and troubleshooting common performance issues.
Keywords: slow, performance, lag, storage, cleanup, cache, context, compact, clear, sessions, agents, bloat, optimization, speed
Use this skill when:
| Symptom | Quick Fix | Command |
|---|---|---|
| General slowness | Clean storage | /cleanup-sessions 7 |
| Input lag | Reset context | /clear |
| API errors | Check status | /check-api-status |
| Unknown cause | Full diagnostic | /diagnose-performance |
| Command | Purpose |
|---|---|
/check-claude-storage | Analyze storage usage |
/cleanup-sessions [days] | Remove old session files |
/cleanup-agents [days] | Remove old agent files |
/prune-cache [days] | Comprehensive cleanup |
/diagnose-performance | Full diagnostic |
/list-sessions | View recent sessions |
/session-stats | Session statistics |
/check-api-status | API status check |
/check-context | Context window analysis |
Claude Code stores conversation history in ~/.claude/:
~/.claude/
├── projects/ # Session history (can grow large!)
│ └── {project-hash}/
│ ├── {session-id}.jsonl # Conversation transcripts
│ └── agent-{id}.jsonl # Subagent transcripts
├── todos/ # Todo state
├── statsig/ # Analytics cache
└── history.jsonl # Command history
Key insight: The projects/ folder grows indefinitely with usage. Heavy users can accumulate 1GB+ of session data.
See: references/storage-management.md for detailed guidance.
Claude Code uses a 200K token context window. Performance degrades as it fills:
| Usage | Status | Action |
|---|---|---|
| < 50% | Healthy | No action |
| 50-75% | Monitor | Consider compacting |
| 75-85% | Warning | Run /compact or /clear |
| > 85% | Critical | Immediate action |
Key commands:
/clear - Complete context reset/compact - Intelligent summarization/cost - View token usageSee: references/context-management.md for detailed guidance.
Several GitHub issues document known performance problems:
| Issue | Description | Workaround |
|---|---|---|
| #10881 | Performance degrades in long sessions | Restart periodically |
| #14552 | Input lag at high context | Use /clear at 75% |
| #14476 | Regression even at 30k tokens | Update to latest version |
| #1497 | Keyboard responsiveness issues | Restart Claude Code |
See: references/known-issues.md for detailed tracking.
/check-claude-storage weekly/cleanup-sessions 7Claude Code is slow
│
├─> Check storage: /check-claude-storage
│ └─> If >500MB: /cleanup-sessions 7
│
├─> Check context: /check-context
│ └─> If WARNING+: /clear or /compact
│
├─> Check API: /check-api-status
│ └─> If degraded: Wait or reduce load
│
└─> Full diagnostic: /diagnose-performance
└─> Follow recommendations
| Skill | Relationship |
|---|---|
docs-management | For official Claude Code documentation |
memory-management | For CLAUDE.md optimization |
Load these for detailed guidance:
references/context-management.md - Context window optimizationreferences/storage-management.md - Storage cleanup strategiesreferences/known-issues.md - GitHub issues and workaroundsDate: 2025-12-26 Model: claude-opus-4-5-20251101
This skill should be used when the user asks to "create a slash command", "add a command", "write a custom command", "define command arguments", "use command frontmatter", "organize commands", "create command with file references", "interactive command", "use AskUserQuestion in command", or needs guidance on slash command structure, YAML frontmatter fields, dynamic arguments, bash execution in commands, user interaction patterns, or command development best practices for Claude Code.
This skill should be used when the user asks to "create an agent", "add an agent", "write a subagent", "agent frontmatter", "when to use description", "agent examples", "agent tools", "agent colors", "autonomous agent", or needs guidance on agent structure, system prompts, triggering conditions, or agent development best practices for Claude Code plugins.
This skill should be used when the user asks to "create a hook", "add a PreToolUse/PostToolUse/Stop hook", "validate tool use", "implement prompt-based hooks", "use ${CLAUDE_PLUGIN_ROOT}", "set up event-driven automation", "block dangerous commands", or mentions hook events (PreToolUse, PostToolUse, Stop, SubagentStop, SessionStart, SessionEnd, UserPromptSubmit, PreCompact, Notification). Provides comprehensive guidance for creating and implementing Claude Code plugin hooks with focus on advanced prompt-based hooks API.