name: performance-optimization description: Best practices for Claude Code performance optimization, context management, storage cleanup, and troubleshooting slowdowns allowed-tools: Read, Bash, Glob, Grep

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

Performance Commands

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:

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.

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

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