claude-code-optimizer

# 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:

1. **Full audit**: Invoke `audit-orchestrator` agent for comprehensive review
2. **Specific audit**: Invoke specialized agent directly (see Agents below)
3. **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:

```
~/.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`