Performance Optimization Skill Skill

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

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

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

Agent Skills: Performance Optimization Skill

Install this agent skill to your local

Skill Files