# Claude Settings Optimizer

Self-audit and optimize Claude configuration for maximum token efficiency.

**Supports both Claude Code (CLI) and Claude Desktop (App).**

## Purpose

- **Diagnose all Claude errors** (8 categories covered)
- Analyze token usage across MCP servers, CLAUDE.md, and extensions
- Troubleshoot MCP connection issues
- Identify optimization opportunities
- Auto-fix common issues with backup safety (Code version)
- Keep working context at 70%+ of 200K limit

## Platform Versions

| Version | Path | Use Case |
|---------|------|----------|
| **Claude Code** | `code/` | CLI with automated scripts |
| **Claude Desktop** | `desktop/` | App-based manual guidance |

## Claude Code Quick Start

```bash
# Install
cd custom-skills/00-our-settings-audit/code
chmod +x install.sh
./install.sh

# Run audit
python3 scripts/run_audit.py

# Apply fixes
python3 scripts/auto_fix.py --apply
```

## Claude Desktop Quick Start

Covers **8 error categories**:

| Category | Example Errors |
|----------|----------------|
| Context/Input | "Exceed response limit" |
| Output | "Response could not be fully generated" |
| Length/File | "Message will exceed length limit", "Files larger than 10mb" |
| Usage Limits | "5-hour limit reached", "X messages left" |
| Server/Capacity | "Unexpected capacity constraints" |
| MCP Connection | "Error connecting to [ServerName]" |
| Account | "Account has been disabled", login errors |
| Output Quality | Output cutoff, gibberish, mixed languages |

**When encountering any error:**

1. Use the Quick Diagnosis Tree in `desktop/SKILL.md`
2. Follow category-specific troubleshooting steps
3. Apply prevention checklist recommendations

**For MCP issues**, share your config file:
- macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
- Windows: `%APPDATA%\Claude\claude_desktop_config.json`

## What Gets Analyzed

| Component | Checks |
|-----------|--------|
| **MCP Servers** | serverInstructions presence, token estimates, load strategy |
| **CLAUDE.md** | Line count, token estimate, structure quality |
| **Commands** | Frontmatter, description, size limits |
| **Skills** | SKILL.md presence, size limits |
| **Agents** | Tool restrictions |

## Target Metrics

| Metric | Target | Max |
|--------|--------|-----|
| CLAUDE.md tokens | 2,000 | 3,000 |
| MCP tokens (with Tool Search) | 5,000 | 10,000 |
| Baseline total | <30% | <40% |
| Available for work | >70% | — |

## Files

```
00-our-settings-audit/
├── README.md
├── code/                          # Claude Code (CLI)
│   ├── CLAUDE.md                  # Skill directive
│   ├── install.sh                 # Installation script
│   ├── commands/
│   │   └── settings-audit.md      # /settings-audit command
│   ├── scripts/
│   │   ├── run_audit.py           # Main orchestrator
│   │   ├── analyze_tokens.py      # Token analysis
│   │   ├── analyze_extensions.py
│   │   └── auto_fix.py            # Auto-fix with backup
│   └── references/
│       └── token-optimization.md
│
└── desktop/                       # Claude Desktop (App)
    ├── skill.yaml                 # Skill metadata
    ├── SKILL.md                   # Diagnosis workflow (8 error categories)
    ├── references/
    │   ├── config-locations.md    # Config file paths
    │   ├── mcp-token-estimates.md # Token budget guide
    │   └── our-settings-audit.md  # Claude.ai project reference
    └── examples/
        └── sample-audit-report.md # Example output
```

## Auto-Fix Capabilities

**Safe (automatic with backup):**
- Add serverInstructions to MCP servers
- Add frontmatter to commands

**Manual review required:**
- Disabling MCP servers
- Restructuring CLAUDE.md
- Removing extensions

## Requirements

- Python 3.8+
- PyYAML (optional, for better frontmatter parsing)