claude-workspace-optimizer 0.1.0

Analyze and optimize your Claude Code workspace. Reduce context bloat, improve memory visibility, and get a detailed report.

Oaken AI Workspace Optimizer

Analyze and optimize your Claude Code workspace. Reduce context bloat, improve memory visibility, and get a detailed health report.

Built by Oaken AI based on patterns from Claude Code's internal architecture.

What It Does

Scans your Claude Code workspace and generates a visual HTML report showing:

• Health Score (0-100) based on context efficiency
• Memory Analysis - index size, visibility percentage, inline bloat detection
• Rules Audit - always-on context lines, reference tiering candidates
• Prioritized Recommendations - what to fix first, estimated time, expected impact

Why This Matters

Claude Code loads your MEMORY.md and rules on every turn change. Bloated context doesn't just waste tokens - it degrades the model's ability to follow the instructions that actually matter.

Common problems this tool catches:

• Silent truncation: MEMORY.md over 200 lines means Claude silently ignores everything after line 200
• Context bloat: Reference material (SQL guides, API docs) loaded on every session even when irrelevant
• Missing topic files: All memory inline instead of using the three-layer pattern (index -> topics -> raw data)

Requirements

• Python 3.10+
• Zero dependencies (pure Python stdlib)
• Does NOT need to be installed inside your Claude Code workspace
• Read-only analysis. Never modifies your files.

Install

pip install claude-workspace-optimizer

Usage

Run from anywhere. Point it at any Claude Code project directory.

# Scan current directory (if it has a .claude/ folder)
claude-workspace-optimizer

# Scan a specific project (recommended)
claude-workspace-optimizer /path/to/your/project

# Generate report and open in browser
claude-workspace-optimizer /path/to/your/project --open

# Also export raw metrics as JSON
claude-workspace-optimizer --json

# Save reports to a custom directory
claude-workspace-optimizer --output ./my-reports/

The tool looks for .claude/ in the target directory (and ~/.claude/ for global rules). It scans MEMORY.md, rules, hooks, skills, and settings. The report is saved to workspace-report/ inside the target directory by default.

Pro tip: After reviewing the report, feed it to your Claude Code instance:

"Read workspace-report/assessment.html and implement the P0 and P1 recommendations"

Claude can self-modify your MEMORY.md, rules, and file structure based on the findings. Always review the changes before accepting.

Example Output

  Scanning: /home/user/my-project
  Output:   /home/user/my-project/workspace-report/

  Health Score: 42/100
  Total Context: 4,129 lines loaded per session
  Memory Visibility: 54% (373 lines, cap 200)
  Rules: 40 files, 3,756 lines always-on
  Issues: 4
  Recommendations: 3

Before Optimization (Score: 36/100)

After Optimization (Score: 85/100)

Full Assessment Report

The Patterns

This tool checks your workspace against patterns from Claude Code's own internal architecture:

1. Three-Layer Memory - Lightweight index (always loaded) pointing to topic files (on-demand)
2. Reference Tiering - Core behavior rules always-on, reference material loaded when needed
3. Memory Budget - 200-line index cap, 25KB max size, entries under 150 characters
4. Skeptical Verification - Memory as hints, not facts. Stale reference detection.

Read the full analysis: How We Applied Claude Code Patterns to Cut Context by 66%

About Oaken AI

Oaken AI builds AI automation systems for businesses. From workspace optimization to full production AI pipelines.

• Free AI Assessment
• AI Tools
• Book a Strategy Call

Disclaimer

This tool is provided as-is with no warranty. Oaken AI and its contributors accept zero responsibility for any changes made to your workspace based on this tool's output. The report contains recommendations, not instructions. Always review changes before applying them. Back up your workspace before making modifications.

Pro tip: You can feed the generated report to your Claude Code instance and ask it to implement the recommendations. Claude can read the HTML and self-modify your MEMORY.md, rules, and file structure. You are responsible for reviewing and approving all changes.

Author

Built by Benjamin Brown at Oaken AI.

License

MIT