Performance Optimization Skill
Comprehensive guidance for optimizing Claude Code performance. This skill covers storage management, context window optimization, and troubleshooting common performance issues.
When to Use This Skill
Keywords: slow, performance, lag, storage, cleanup, cache, context, compact, clear, sessions, agents, bloat, optimization, speed
Use this skill when:
- Claude Code is running slowly
- Storage is accumulating
- Context window is getting full
- Planning performance maintenance
- Learning best practices for efficient usage
Quick Reference
Immediate Actions for Slowdowns
| 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 |
Performance Commands
| Command | Purpose |
|---|---|
/user-config storage | Analyze storage usage |
/user-config cleanup-sessions [days] | Remove old session files |
/user-config cleanup-agents [days] | Remove old agent files |
/user-config prune-cache [days] | Comprehensive cleanup |
/diagnose-performance | Full diagnostic |
/list sessions | View recent sessions |
/user-config session-stats | Session statistics |
/check-api-status | API status check |
/check-context | Context window analysis |
Core Concepts
1. Storage Management
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 historyKey insight: The projects/ folder grows indefinitely with usage. Heavy users can accumulate 1GB+ of session data.
See: references/storage-management.md for detailed guidance.
2. Context Window Management
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 usage
See: references/context-management.md for detailed guidance.
3. Known Issues
Several GitHub issues document known performance problems:
Note: Issue numbers below are point-in-time references and may have been closed, merged, or superseded. For current issues, spawn theclaude-code-issue-researcheragent or querydocs-management: "performance issues"for updated tracking.
| 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.
Best Practices
Daily Maintenance
- Start fresh when possible - New session = fresh context
- Use /clear between major tasks - Don't let context rot
- Monitor storage periodically - Run
/check-claude-storageweekly
Heavy Usage Patterns
- Use subagents for large operations - Isolates context bloat
- Break large tasks into sessions - Smaller = faster
- Clean storage weekly -
/cleanup-sessions 7
Performance Optimization
- Keep CLAUDE.md lean - Large memory files slow startup
- Use progressive disclosure - Load context on-demand
- Prefer focused queries - Specific > broad
Troubleshooting Flowchart
Claude 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 recommendationsRelated Skills
| Skill | Relationship |
|---|---|
docs-management | For official Claude Code documentation |
memory-management | For CLAUDE.md optimization |
References
Load these for detailed guidance:
references/context-management.md- Context window optimizationreferences/storage-management.md- Storage cleanup strategiesreferences/known-issues.md- GitHub issues and workarounds
Version History
- v1.0.0 (2025-12-26): Initial release
- Core performance guidance - Command reference - Best practices - Reference documents
Last Updated
Date: 2025-12-26 Model: claude-opus-4-5-20251101