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