melodic-software/performance-optimization

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