Skip to content

vbonk/claude-code-optimizer

BranchesTags

Repository files navigation

Claude Code Optimizer

Audit and optimize your Claude Code installation to current best practices

Claude Code 2.1.3+ Version License Validation

What Is This? • Features • Installation • Usage • Architecture

What Is This?

Claude Code is Anthropic's AI-powered coding assistant that runs in your terminal. It can read your codebase, write and edit files, run commands, and help you build software through natural conversation.

Claude Code Optimizer is a skill — a plugin that extends Claude Code's capabilities. When installed, it gives Claude the ability to audit your Claude Code setup, find misconfigurations, identify security issues, and recommend optimizations.

Think of it as a health check for your Claude Code installation:

You: "Audit my Claude Code setup"

Claude: Analyzing your configuration...

## Audit Report

| Severity | Area | Issue | Fix |
|----------|------|-------|-----|
| 🔴 High | Hooks | Invalid event `postToolUse` | Use `PostToolUse` (case-sensitive) |
| 🟡 Medium | Permissions | Overly broad `Bash(*)` | Scope to specific commands |
| 🟢 Info | MCP | Unused server configured | Remove or configure |

Recommendations:
1. Fix hook event name — hooks won't fire with wrong casing
2. Tighten permissions to reduce security surface

Who is this for?

  • Developers who want to verify their Claude Code setup is optimal
  • Teams standardizing Claude Code configurations
  • Power users exploring advanced features (hooks, MCP, custom agents)
  • Anyone troubleshooting why something isn't working

Why This Exists

Claude Code is powerful, but it's also complex. With hooks, permissions, MCP servers, custom agents, slash commands, and multiple configuration files, there's a lot that can go wrong — and a lot of potential that goes untapped.

Claude Code is evolving rapidly—2.1.0 alone shipped with 1,096 commits. Configuration options are scattered across multiple files, best practices aren't always obvious, and it's easy to miss features that could dramatically improve your workflow.

Claude Code Optimizer is a skill that audits your setup, identifies issues, and guides you to an optimized configuration.

Features

The optimizer doesn't just check if your files exist — it validates every configuration option, catches subtle mistakes, and explains exactly how to fix them.

  • 🔍 Comprehensive Auditing — Analyzes settings, hooks, permissions, MCP servers, commands, agents, and skills
  • 🎯 Six Specialized Agents — Focused auditors for config, hooks, permissions, MCP, workflows, plus orchestrator
  • 🔒 Security Analysis — Detects hardcoded secrets, dangerous patterns, data exfiltration risks
  • 📊 Context Optimization — Identifies bloated configs causing context exhaustion
  • ✅ Pattern Validation — Catches permission patterns that won't match as expected
  • 📋 Actionable Reports — Every finding includes severity, impact, and specific fix instructions
  • 📚 Built-in References — Five detailed guides including security audit procedures
  • ⚡ Current — Targets Claude Code 2.1.3+ with all 12 hook events and latest settings schema

Installation

Installation takes about 30 seconds. The skill installs to your Claude Code skills directory, and the specialized agents install alongside it. Once installed, Claude automatically loads the optimizer when you ask for an audit.

Quick Install (Recommended)

# Clone the repository
git clone https://github.com/vbonk/claude-code-optimizer.git
cd claude-code-optimizer

# Run the installer
./scripts/install.sh

Manual Install

# Install skill
mkdir -p ~/.claude/skills/claude-code-optimizer
cp -r SKILL.md references ~/.claude/skills/claude-code-optimizer/

# Install agents
mkdir -p ~/.claude/agents
cp agents/*.md ~/.claude/agents/

Project-Scoped Install

For project-specific installation (useful for teams):

./scripts/install.sh --project

This installs to .claude/skills/ and .claude/agents/ in your current directory.

Verify Installation

claude --version  # Should be 2.1.0+

Then in Claude Code:

What skills are available?

You should see claude-code-optimizer listed.

Usage

Just ask Claude naturally. The optimizer triggers on phrases like "audit", "check", "optimize", or "review" when you're talking about your Claude Code setup. You don't need to remember specific commands.

Full Audit

Ask Claude Code to audit your setup:

Audit my Claude Code setup

Or be specific:

Run a comprehensive Claude Code audit and show me what needs fixing

Targeted Audits

Run specific audits when you know what you're looking for:

Request What It Does
Check my Claude Code configuration Audits settings.json and CLAUDE.md files
Audit my hooks Validates hook events, matchers, and security
Review my permissions setup Analyzes allow/deny rules and pattern validity
Audit my MCP servers Checks MCP configs for secrets and security
Check my commands and agents Audits workflow components for best practices
Run a security audit Comprehensive security review across all areas

Example Output

## Claude Code Audit Report

**Version**: 2.1.2
**Health**: ✅ Pass

### Findings

| Severity | Area | Issue | Fix |
|----------|------|-------|-----|
| 🔴 High | Hooks | Invalid event name `postToolUse` | Change to `PostToolUse` (case-sensitive) |
| 🟡 Medium | Permissions | Overly broad `Bash(*)` allow rule | Scope to specific commands |
| 🟢 Info | Config | No CLAUDE.md in project root | Consider adding project context |

### Recommendations
1. Fix the hook event name immediately—hooks won't fire with incorrect casing
2. Tighten Bash permissions to reduce security surface
3. Add CLAUDE.md to improve Claude's understanding of your project

Architecture

Under the hood, the optimizer uses a team of specialized agents. Each agent is an expert in one area — hooks, permissions, MCP servers, etc. When you request an audit, the orchestrator coordinates them, collects their findings, and synthesizes a unified report.

┌──────────────────────────────────────────────────────────────────────┐
│                       Claude Code Optimizer                           │
├──────────────────────────────────────────────────────────────────────┤
│  SKILL.md                                                             │
│  ├── Trigger detection (audit, optimize, check, improve)             │
│  ├── Quick reference (settings keys, hook events, tool names)        │
│  └── Agent orchestration                                              │
├──────────────────────────────────────────────────────────────────────┤
│  Specialized Agents (6)                                               │
│  ┌────────────────┐  ┌────────────────┐  ┌────────────────┐          │
│  │ config-auditor │  │ hooks-auditor  │  │ permissions-   │          │
│  │                │  │                │  │ auditor        │          │
│  │ • settings.json│  │ • Event names  │  │ • Allow/deny   │          │
│  │ • CLAUDE.md    │  │ • Matchers     │  │ • Patterns     │          │
│  │ • Context size │  │ • Security     │  │ • Unreachable  │          │
│  └────────────────┘  └────────────────┘  └────────────────┘          │
│  ┌────────────────┐  ┌────────────────┐  ┌────────────────┐          │
│  │ mcp-auditor    │  │ workflow-      │  │ audit-         │          │
│  │                │  │ auditor        │  │ orchestrator   │          │
│  │ • MCP servers  │  │ • Commands     │  │ • Coordinates  │          │
│  │ • Secrets      │  │ • Agents       │  │ • Synthesizes  │          │
│  │ • Permissions  │  │ • Skills       │  │ • Prioritizes  │          │
│  └────────────────┘  └────────────────┘  └────────────────┘          │
├──────────────────────────────────────────────────────────────────────┤
│  References (5 guides, loaded on demand)                              │
│  • config-guide.md • hooks-guide.md • permissions-guide.md           │
│  • security-guide.md • troubleshooting.md                             │
└──────────────────────────────────────────────────────────────────────┘

Why Subagents?

  1. Separation of concerns — Each auditor is an expert in one domain
  2. Parallel execution — Multiple audits can run simultaneously
  3. Maintainability — Update one auditor without touching others
  4. Context efficiency — Only loads relevant expertise for each audit type
  5. Testability — Each agent can be validated independently

Documentation

The optimizer includes detailed reference guides that Claude loads on demand. These go deeper than the audit output — use them when you want to understand the "why" behind a recommendation or learn advanced configuration patterns.

Included References

Guide Contents
references/config-guide.md Settings.json schema, CLAUDE.md best practices, context optimization
references/hooks-guide.md All 12 hook events, matcher patterns, input/output schemas
references/permissions-guide.md Permission strategies, pattern validation, unreachable rule detection
references/security-guide.md Security audit procedures, threat model, incident response
references/troubleshooting.md Common issues, diagnostic commands, context optimization

Official Claude Code Documentation

What Gets Checked

Here's exactly what each auditor examines. This isn't just a surface-level scan — each check validates against the current Claude Code 2.1.3 specification and flags anything that's misconfigured, insecure, or suboptimal.

Configuration (config-auditor)

  • ~/.claude/settings.json — User settings
  • .claude/settings.json — Project settings
  • CLAUDE.md / .claude/CLAUDE.md — Project memory
  • CLAUDE.local.md — Local overrides
  • JSON validity and schema compliance
  • Context usage optimization (file sizes, bloat detection)

Hooks (hooks-auditor)

  • All 12 event names validated (case-sensitive)
  • Matcher patterns (regex validity, tool name accuracy)
  • Command security (injection risks, data exfiltration, dangerous patterns)
  • Timeout configurations
  • once: true and agent_type options

Permissions (permissions-auditor)

  • Allow/deny rule effectiveness
  • Pattern validation (catches common mistakes)
  • Unreachable rule detection (2.1.3+)
  • Conflicting rules and security recommendations

MCP Servers (mcp-auditor)

  • Server configurations in settings.json and .mcp.json
  • Hardcoded secret detection
  • Filesystem scope validation
  • Tool permission coverage
  • High-risk server identification

Workflow Components (workflow-auditor)

  • Custom slash commands (frontmatter, descriptions)
  • Subagents (valid schemas, appropriate tools)
  • Skills (trigger descriptions, file structure)
  • Named sessions and context: fork usage

Validation

We've tested this skill against our own QA process — the same rigorous checks the optimizer runs on your setup. Every claim has been verified against the official Claude Code documentation.

This skill has passed comprehensive validation:

✅ 38/38 checks passed

Installation
  ✅ Skill directory structure correct
  ✅ Agents installed to correct location
  ✅ Install script executes successfully

Schema Validation
  ✅ SKILL.md frontmatter valid
  ✅ All 6 agents have valid frontmatter
  ✅ All tool names correct (Bash, Read, Write, etc.)
  ✅ All model values valid (inherit)

Documentation
  ✅ All 12 hook events documented
  ✅ All 5 reference guides complete
  ✅ SKILL.md under 500 lines
  ✅ Descriptions under 1024 chars

Version Compatibility
  ✅ Targets Claude Code 2.1.3+
  ✅ Tested with Claude Code 2.1.3

Requirements

The optimizer works with any standard Claude Code installation. No additional dependencies required.

  • Claude Code: 2.1.3 or later
  • Subscription: Claude Pro, Claude Max, or API access
  • OS: macOS, Linux, or Windows (WSL)

File Structure

Everything is plain Markdown — no build step, no compilation. You can read and modify any file directly if you want to customize the optimizer's behavior.

claude-code-optimizer/
├── SKILL.md                 # Main skill (triggers on audit/optimize requests)
├── MANIFEST.md              # Human-readable installation guide
├── HANDOFF.md               # Development context for contributors
├── QA-PROCESS.md            # Validation framework
├── README.md                # This file
├── LICENSE                  # MIT License
├── agents/
│   ├── audit-orchestrator.md    # Coordinates comprehensive audits
│   ├── config-auditor.md        # Configuration specialist
│   ├── hooks-auditor.md         # Hooks specialist
│   ├── mcp-auditor.md           # MCP server specialist
│   ├── permissions-auditor.md   # Permissions specialist
│   └── workflow-auditor.md      # Commands/agents/skills specialist
├── references/
│   ├── config-guide.md          # Configuration deep-dive
│   ├── hooks-guide.md           # Hook patterns and examples
│   ├── permissions-guide.md     # Permission strategies
│   ├── security-guide.md        # Security audit procedures
│   └── troubleshooting.md       # Common issues and solutions
└── scripts/
    └── install.sh               # Installation script

Contributing

Found a bug? Have an idea for a new check? Contributions are welcome. The codebase is just Markdown files, so it's easy to understand and modify.

Please see HANDOFF.md for development context and QA-PROCESS.md for the validation framework.

Development Workflow

  1. Fork the repository
  2. Make your changes
  3. Run the QA process validation
  4. Submit a pull request

Areas for Contribution

  • Additional audit checks
  • New reference documentation
  • Edge case handling
  • Performance optimization
  • Bug fixes

License

MIT License — see LICENSE for details.

Attribution

Designed by Anthony Velte & Claude Opus 4.5

Built with care to help developers get the most out of Claude Code.

If this skill helped you, consider starring the repo ⭐

About

No description, website, or topics provided.

Resources

Readme

License

MIT license

Security policy

Security policy
Activity

Stars

2 stars

Watchers

0 watching

Forks

1 fork
Report repository

Releases

No releases published

Packages

 
 
 

Contributors

Languages