Skill

performance-optimization

Optimizes Claude Code performance using storage cleanup, context management commands, and diagnostics for slowdowns, lag, and full contexts.

performance

npx claudepluginhub melodic-software/claude-code-plugins --plugin claude-ecosystem

Tool Access

This skill is limited to using the following tools:

ReadBashGlobGrep

Preview

Comprehensive guidance for optimizing Claude Code performance. This skill covers storage management, context window optimization, and troubleshooting common performance issues.

Supporting Assets

references/context-management.mdreferences/known-issues.mdreferences/storage-management.md

SKILL.md

Similar Skills

Context Optimization

Optimizes Claude Code session context by explaining major consumers like metadata, images, file reads, and bash output, with strategies including screenshot compression, /compact usage, and reduced re-reads.

1 file

context-analyzer

context-optimizer

2.0k

Optimizes Claude Code session context and token usage via compaction, MCP audits, prompt scoping, and subagent delegation. Use when sessions slow, context degrades, or budget depletes.

pro-workflow

context

Manages Claude Code context window: monitors usage via statusline, creates handoffs, compacts with structured summaries, resumes after compaction. Use for long sessions nearing limits.

darkroom

Stats

Parent Repo Stars40

Parent Repo Forks6

Last CommitFeb 16, 2026

Actions

View Source View Plugin View on GitHub View README

Help us improve

Share bugs, ideas, or general feedback.

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