Claude Code Optimizer

Audit and optimize Claude Code installations. Requires Claude Code 2.1.3 or later.

Quick Start

Run the appropriate audit based on user request:

•Full audit: Invoke audit-orchestrator agent for comprehensive review
•Specific audit: Invoke specialized agent directly (see Agents below)
•Quick check: Run inline checks from Audit Checklist

Agents

Invoke via Task tool with appropriate subagent_type:

Agent	Purpose
`audit-orchestrator`	Coordinates full audit across all areas
`config-auditor`	Audits settings.json and CLAUDE.md files
`hooks-auditor`	Audits hook configurations
`permissions-auditor`	Audits permission patterns
`workflow-auditor`	Audits commands, agents, and skills
`mcp-auditor`	Audits MCP server configurations

Agent definitions are in agents/ directory. Install to ~/.claude/agents/ or .claude/agents/.

Audit Checklist

Configuration Files

Check these locations exist and are properly configured:

code

~/.claude/settings.json          # User settings
.claude/settings.json            # Project settings
CLAUDE.md                        # Project memory (root)
.claude/CLAUDE.md               # Alternative location
CLAUDE.local.md                 # Local overrides (gitignored)
~/.claude/CLAUDE.md             # User-level memory

Settings.json Structure

Valid top-level keys (2.1.3+):

•hooks - Event handlers
•permissions - Tool permissions (allow/deny arrays)
•env - Environment variables
•mcpServers - MCP server configurations
•model - Default model
•theme - UI theme
•respectGitignore - File picker behavior
•language - Response language
•fileSuggestion - Custom @ file search command
•releaseChannel - stable or latest channel toggle

Hook Events (2.1.0+)

Valid event names:

•PreToolUse, PostToolUse, PostToolUseFailure, PermissionRequest
•Notification, UserPromptSubmit
•SessionStart, SessionEnd
•Stop, SubagentStart, SubagentStop, PreCompact

Tool Names for Matchers

•Bash, Read, Write, Edit
•Grep, Glob, Task, TaskOutput
•WebFetch, WebSearch
•NotebookEdit, TodoWrite, KillShell
•LSP (Language Server Protocol, 2.0.74+)
•mcp__* for MCP tools (wildcard: mcp__server__*)

Permission Patterns

json

{
  "permissions": {
    "allow": ["Read", "Grep", "Glob"],
    "deny": ["Bash(rm -rf:*)"]
  }
}

Wildcard syntax: Bash(git *:*) allows all git commands.

Common Issues

Issue	Fix
Hooks not firing	Check event name spelling (case-sensitive)
Skills not loading	Verify `~/.claude/skills/` or `.claude/skills/` path
Permissions ignored	Check allow/deny order; deny takes precedence
CLAUDE.md not read	Must be in project root or `.claude/`

References

For detailed audit procedures, see:

•references/config-guide.md - Configuration deep-dive
•references/hooks-guide.md - Hook patterns and examples
•references/permissions-guide.md - Permission strategies
•references/security-guide.md - Security audit procedures
•references/troubleshooting.md - Common problems and solutions

Version Compatibility

This skill targets Claude Code 2.1.3+ features:

•Skill hot-reload
•Forked sub-agent context (context: fork)
•Hook frontmatter in skills/agents with once: true option
•YAML-style allowed-tools
•Unreachable permission rule detection
•MCP wildcard permissions (mcp__server__*)
•Named sessions (/rename, /resume <name>)
•Release channel configuration

Check version: claude --version Update: claude update