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

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

Converted and distributed by TomeVault — claim your Tome and manage your conversions.