Skip to main content
Generalmelodic-software

performance-optimization

Best practices for Claude Code performance optimization, context management, storage cleanup, and troubleshooting slowdowns

Stars
74
Source
melodic-software/claude-code-plugins
Updated
2026-04-07
Slug
melodic-software--claude-code-plugins--performance-optimization
View on GitHubRaw SKILL.md

// install — copy + paste into any project

mkdir -p .claude/skills && curl -fsSL https://raw.githubusercontent.com/melodic-software/claude-code-plugins/HEAD/plugins/claude-ecosystem/skills/performance-optimization/SKILL.md -o .claude/skills/performance-optimization.md

Drops the SKILL.md into .claude/skills/performance-optimization.md. Works with Claude Code, Cursor, and any agent that loads SKILL.md files from .claude/skills/.

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 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.

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 the claude-code-issue-researcher agent or query docs-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

  1. Start fresh when possible - New session = fresh context
  2. Use /clear between major tasks - Don't let context rot
  3. Monitor storage periodically - Run /check-claude-storage weekly

Heavy Usage Patterns

  1. Use subagents for large operations - Isolates context bloat
  2. Break large tasks into sessions - Smaller = faster
  3. Clean storage weekly - /cleanup-sessions 7

Performance Optimization

  1. Keep CLAUDE.md lean - Large memory files slow startup
  2. Use progressive disclosure - Load context on-demand
  3. 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 recommendations

Related 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 optimization
  • references/storage-management.md - Storage cleanup strategies
  • references/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