our-claude-skills/custom-skills/00-claude-code-setting/code/scripts/run_audit.py

#!/usr/bin/env python3
"""
Claude Code Settings Audit - Main Orchestrator
Analyzes configuration for token efficiency and optimization.
"""

import json
import sys
import subprocess
from pathlib import Path
from datetime import datetime

SCRIPT_DIR = Path(__file__).parent
CONTEXT_LIMIT = 200_000


def run_analyzer(script_name: str) -> dict:
    """Run an analyzer script and return its output."""
    script_path = SCRIPT_DIR / script_name

    if not script_path.exists():
        return {"error": f"Script not found: {script_path}"}

    try:
        result = subprocess.run(
            [sys.executable, str(script_path)],
            capture_output=True,
            text=True,
            timeout=60
        )

        if result.returncode != 0 and not result.stdout:
            return {"error": result.stderr or "Unknown error"}

        return json.loads(result.stdout)
    except subprocess.TimeoutExpired:
        return {"error": "Analysis timed out"}
    except json.JSONDecodeError as e:
        return {"error": f"Invalid JSON: {e}"}
    except Exception as e:
        return {"error": str(e)}


def calculate_health(token_report: dict, extensions_report: dict) -> str:
    """Determine overall health status."""
    total_tokens = token_report.get("total_tokens", 0)
    usage_pct = (total_tokens / CONTEXT_LIMIT) * 100

    critical_issues = len(token_report.get("findings", {}).get("critical", []))
    critical_issues += len(extensions_report.get("findings", {}).get("critical", []))

    if usage_pct > 30 or critical_issues > 2:
        return "Critical"
    elif usage_pct > 20 or critical_issues > 0:
        return "Needs Attention"
    return "Good"


def generate_report(token_report: dict, extensions_report: dict) -> str:
    """Generate markdown report."""
    timestamp = datetime.now().strftime("%Y-%m-%d %H:%M:%S")

    total_tokens = token_report.get("total_tokens", 0)
    available = CONTEXT_LIMIT - total_tokens
    usage_pct = (total_tokens / CONTEXT_LIMIT) * 100
    available_pct = 100 - usage_pct

    health = calculate_health(token_report, extensions_report)
    health_emoji = {"Good": "🟢", "Needs Attention": "🟡", "Critical": "🔴"}[health]

    # Collect all findings
    all_critical = []
    all_warnings = []
    all_passing = []
    all_recommendations = []

    for report in [token_report, extensions_report]:
        findings = report.get("findings", {})
        all_critical.extend(findings.get("critical", []))
        all_warnings.extend(findings.get("warnings", []))
        all_passing.extend(findings.get("passing", []))
        all_recommendations.extend(findings.get("recommendations", []))

    report = f"""# Claude Code Settings Audit Report

**Generated:** {timestamp}

---

## Token Budget Summary

| Component | Tokens | % of 200K | Status |
|-----------|--------|-----------|--------|
| CLAUDE.md | {token_report.get('claude_md_tokens', 0):,} | {token_report.get('claude_md_tokens', 0)/CONTEXT_LIMIT*100:.1f}% | {'🟢' if token_report.get('claude_md_tokens', 0) < 3000 else '🔴'} |
| MCP Servers | {token_report.get('mcp_tokens', 0):,} | {token_report.get('mcp_tokens', 0)/CONTEXT_LIMIT*100:.1f}% | {'🟢' if token_report.get('mcp_tokens', 0) < 10000 else '🟡'} |
| **Baseline Total** | **{total_tokens:,}** | **{usage_pct:.1f}%** | {health_emoji} |
| **Available for Work** | **{available:,}** | **{available_pct:.1f}%** | — |

**Target:** Baseline under 30% (60,000 tokens), Available over 70%

---

## Overall Health: {health_emoji} {health}

- Critical Issues: {len(all_critical)}
- Warnings: {len(all_warnings)}
- Passing Checks: {len(all_passing)}

---

## MCP Server Analysis

**Servers:** {token_report.get('mcp_count', 0)} configured

"""

    # MCP server details
    mcp_servers = token_report.get("mcp_servers", {})
    if mcp_servers:
        report += "| Server | Tokens | Instructions | Strategy |\n"
        report += "|--------|--------|--------------|----------|\n"
        for name, info in mcp_servers.items():
            instr = "✅" if info.get("has_instructions") else "❌"
            tokens = info.get("tokens", 0)
            strategy = info.get("strategy", "unknown")
            report += f"| {name} | ~{tokens:,} | {instr} | {strategy} |\n"
        report += "\n"

    # CLAUDE.md analysis
    report += f"""---

## CLAUDE.md Analysis

"""
    claude_files = token_report.get("claude_md_files", [])
    for cf in claude_files:
        status = "🟢" if cf.get("tokens", 0) < 3000 else "🔴"
        report += f"- **{cf.get('path', 'Unknown')}**: {cf.get('lines', 0)} lines, ~{cf.get('tokens', 0):,} tokens {status}\n"

    if not claude_files:
        report += "*No CLAUDE.md files found*\n"

    # Extensions
    report += f"""
---

## Extensions Analysis

- Commands: {extensions_report.get('commands_count', 0)}
- Skills: {extensions_report.get('skills_count', 0)}
- Agents: {extensions_report.get('agents_count', 0)}

"""

    # Findings
    if all_critical:
        report += "---\n\n## ❌ Critical Issues\n\n"
        for issue in all_critical:
            report += f"- {issue}\n"
        report += "\n"

    if all_warnings:
        report += "---\n\n## ⚠️ Warnings\n\n"
        for warning in all_warnings[:10]:
            report += f"- {warning}\n"
        if len(all_warnings) > 10:
            report += f"- *...and {len(all_warnings) - 10} more*\n"
        report += "\n"

    if all_passing:
        report += "---\n\n## ✅ Passing\n\n"
        for item in all_passing[:5]:
            report += f"- {item}\n"
        if len(all_passing) > 5:
            report += f"- *...and {len(all_passing) - 5} more*\n"
        report += "\n"

    # Recommendations
    if all_recommendations or all_critical:
        report += "---\n\n## Recommendations\n\n"
        priority = 1
        for issue in all_critical[:3]:
            report += f"{priority}. **Fix:** {issue}\n"
            priority += 1
        for rec in all_recommendations[:5]:
            report += f"{priority}. {rec}\n"
            priority += 1
        report += "\n"

    report += f"""---

## Next Steps

1. Run `python3 scripts/auto_fix.py` to preview fixes
2. Run `python3 scripts/auto_fix.py --apply` to apply fixes
3. Re-run audit to verify improvements

---

*Generated by Claude Code Settings Optimizer*
"""

    return report


def main():
    print("🔍 Running Claude Code Settings Audit...\n", file=sys.stderr)

    print("  Analyzing tokens...", file=sys.stderr)
    token_report = run_analyzer("analyze_tokens.py")

    print("  Analyzing extensions...", file=sys.stderr)
    extensions_report = run_analyzer("analyze_extensions.py")

    print("  Generating report...\n", file=sys.stderr)

    markdown_report = generate_report(token_report, extensions_report)
    print(markdown_report)

    # Save reports
    output_dir = SCRIPT_DIR.parent if (SCRIPT_DIR.parent / "CLAUDE.md").exists() else Path.cwd()
    report_path = output_dir / "settings-audit-report.md"
    json_path = output_dir / "settings-audit-report.json"

    full_report = {
        "timestamp": datetime.now().isoformat(),
        "tokens": token_report,
        "extensions": extensions_report,
        "total_baseline_tokens": token_report.get("total_tokens", 0),
        "health": calculate_health(token_report, extensions_report)
    }

    try:
        report_path.write_text(markdown_report)
        json_path.write_text(json.dumps(full_report, indent=2, default=str))
        print(f"📄 Report: {report_path}", file=sys.stderr)
        print(f"📊 JSON: {json_path}", file=sys.stderr)
    except IOError as e:
        print(f"Warning: Could not save report: {e}", file=sys.stderr)

    return 1 if full_report["health"] == "Critical" else 0


if __name__ == "__main__":
    sys.exit(main())