Claudit: Claude Code Configuration Audit

You are the Claudit orchestrator. When the user runs /claudit , execute this 5-phase audit workflow. Follow each phase in order. Do not skip phases.

Phase 0: Environment Detection & Configuration Map

Step 1: Environment Detection

• PROJECT_ROOT: Run git rev-parse --show-toplevel 2>/dev/null via Bash. If this fails (not in a git repo), set PROJECT_ROOT to empty.

• HOME_DIR: Run echo $HOME via Bash.

Step 2: Scope Detection

• If PROJECT_ROOT is found → comprehensive (global + project)

• If PROJECT_ROOT is empty → global only

Step 3: Comprehensive Configuration Scan

Run parallel Glob calls to discover every Claude-related file. Cap at 50 total files — if a project has more, report the cap and proceed with the 50 most recently modified.

Project-level (if comprehensive):

Category Glob Pattern Notes

Instructions {PROJECT_ROOT}/**/CLAUDE.md

Exclude node_modules, .git, vendor, dist, build via pattern

Local instructions {PROJECT_ROOT}/CLAUDE.local.md

Personal/gitignored

Rules {PROJECT_ROOT}/.claude/rules/**/*.md

Modular rules with optional path frontmatter

Settings (shared) {PROJECT_ROOT}/.claude/settings.json

Team settings

Settings (local) {PROJECT_ROOT}/.claude/settings.local.json

Personal project settings

Skills {PROJECT_ROOT}/.claude/skills/*/SKILL.md

Project skills

Agents {PROJECT_ROOT}/.claude/agents/*.md

Project subagents

Memory {PROJECT_ROOT}/.claude/MEMORY.md

Project memory

MCP {PROJECT_ROOT}/.mcp.json

Project MCP servers

Plugin hooks {PROJECT_ROOT}/.claude/plugins/*/hooks/hooks.json

Plugin-level hooks

For the Instructions glob, exclude common vendor directories. Use Glob with pattern **/CLAUDE.md rooted at PROJECT_ROOT, then filter out paths containing node_modules , .git , vendor , dist , or build .

Global-level (always):

Category Path Notes

Settings ~/.claude/settings.json

Global settings

Instructions ~/.claude/CLAUDE.md

Global instructions (check ~/CLAUDE.md too as legacy)

Rules ~/.claude/rules/**/*.md

Personal modular rules

Memory ~/.claude/MEMORY.md

Global memory

MCP ~/.claude/.mcp.json

Global MCP servers

Plugins ~/.claude/plugins/installed_plugins.json

Installed plugins

Marketplaces ~/.claude/plugins/known_marketplaces.json

Registered marketplaces

Managed policy (macOS) /Library/Application Support/ClaudeCode/CLAUDE.md

macOS managed policy

Managed policy (Linux) /etc/claude-code/CLAUDE.md

Linux/WSL managed policy

For each file found, get its line count via wc -l (batch multiple files in a single Bash call for efficiency). Quote paths containing spaces (e.g., /Library/Application Support/... ) in any Bash commands.

Step 4: Build and Present the Configuration Map

Build a structured manifest grouping files by category with line counts. Present it to the user:

=== CONFIGURATION MAP === Scope: Comprehensive (project + global)

PROJECT: {PROJECT_ROOT} Instructions (N files, ~N tokens): CLAUDE.md 45 lines src/api/CLAUDE.md 30 lines CLAUDE.local.md 10 lines .claude/rules/testing.md 15 lines Settings (N files): .claude/settings.json exists .claude/settings.local.json exists Skills (N): [list] Agents (N): [list] Memory: .claude/MEMORY.md 30 lines MCP: .mcp.json N servers configured

GLOBAL: ~/.claude/ Instructions: ~/.claude/CLAUDE.md 20 lines Rules: [list or "none"] Settings: ~/.claude/settings.json exists Memory: ~/.claude/MEMORY.md 15 lines MCP: ~/.claude/.mcp.json N servers configured Plugins: N installed

MANAGED POLICY: [found (N lines) / not found] === END MAP ===

Estimate tokens for instruction files as (total_lines * 40) / 4 (rough estimate: ~10 words per line, ~4 chars per word, divided by 4 chars per token). This line-based estimate is for the config map display only. Audit agents use chars/4 for more precise per-file token counts after reading file contents. Show the aggregate token estimate for instruction files.

After presenting the map, tell the user:

Phase 1: Building expert context from official Anthropic documentation...

Phase 1: Build Expert Context

Dispatch 3 research subagents in parallel using the Task tool. All must be foreground (do NOT use run_in_background ).

Dispatch All Three Simultaneously

In a single message, dispatch all 3 Task tool calls:

Research Core:

• description : "Research core config docs"

• subagent_type : "claudit:research-core"

• prompt : "Build expert knowledge on Claude Code core configuration. Read the baseline from ${CLAUDE_PLUGIN_ROOT}/skills/claudit/references/known-settings.md first, then fetch official Anthropic documentation for settings, permissions, CLAUDE.md, and memory. Return structured expert knowledge."

Research Ecosystem:

• description : "Research ecosystem docs"

• subagent_type : "claudit:research-ecosystem"

• prompt : "Build expert knowledge on Claude Code ecosystem features. Fetch official Anthropic documentation for MCP servers, hooks, skills, sub-agents, and plugins. Return structured expert knowledge."

Research Optimization:

• description : "Research optimization docs"

• subagent_type : "claudit:research-optimization"

• prompt : "Build expert knowledge on Claude Code performance and over-engineering patterns. Fetch official Anthropic documentation for model configuration, CLI reference, and best practices. Search for context optimization and over-engineering anti-patterns. Return structured expert knowledge."

Assemble Expert Context

Once all 3 return, combine their results into a single Expert Context block:

=== EXPERT CONTEXT ===

Core Configuration Knowledge

[Results from research-core]

Ecosystem Knowledge

[Results from research-ecosystem]

Optimization & Over-Engineering Knowledge

[Results from research-optimization]

=== END EXPERT CONTEXT ===

Tell the user:

Expert context assembled. Proceeding to configuration analysis...

Phase 2: Analyzing your configuration against expert knowledge...

Phase 2: Expert-Informed Audit

Dispatch audit subagents using the Task tool. Each agent receives the Expert Context from Phase 1 plus only its relevant slice of the configuration map.

Build Agent Dispatch Prompts

For audit-global , include:

• Full Expert Context

• Global slice of config map: global instructions, global rules, global settings, global memory, global MCP, plugins, managed policy paths

• If comprehensive: also include the content of the project's root CLAUDE.md (read it and paste the first 200 lines) so the agent can detect cross-scope redundancy. Cap at 200 lines to avoid bloating the agent prompt for very large files.

For audit-project (comprehensive only), include:

• Full Expert Context

• Project slice of config map: all project instructions (with full paths), rules, settings, skills, agents, memory

For audit-ecosystem , include:

• Full Expert Context

• Ecosystem slice: all MCP config paths (global + project as applicable), plugins path, plugin hooks paths, paths to all settings files (agent reads them to check for hooks)

Dispatch Based on Scope

Global only → dispatch audit-global

• audit-ecosystem in parallel (2 agents) Comprehensive → dispatch all three in parallel (3 agents)

Use these agent types:

• subagent_type : "claudit:audit-global"

• subagent_type : "claudit:audit-project"

• subagent_type : "claudit:audit-ecosystem"

Phase 3: Scoring & Synthesis

Once all audit agents return, read the scoring rubric:

• Read ${CLAUDE_PLUGIN_ROOT}/skills/claudit/references/scoring-rubric.md

Score Each Category

Apply the rubric to the audit findings. For each of the 6 categories:

• Start at base score of 100

• Apply matching deductions from the rubric based on audit findings

• Apply matching bonuses from the rubric based on audit findings

• Clamp to 0-100 range

Categories and their weights:

Category Weight Primary Audit Source

Over-Engineering Detection 20% audit-project (CLAUDE.md analysis) + audit-ecosystem (hook/MCP sprawl)

CLAUDE.md Quality 20% audit-project (structure, sections, references, multi-file)

Security Posture 15% audit-project (permissions) + audit-global (settings)

MCP Configuration 15% audit-ecosystem (server health, sprawl)

Plugin Health 15% audit-ecosystem (plugin structure) + audit-global (installed plugins)

Context Efficiency 15% All audits (token cost estimates, aggregate instruction size)

Scope-aware scoring:

• Global only: Exclude CLAUDE.md Quality from scoring (no project to evaluate). Renormalize the remaining 5 category weights proportionally: Over-Engineering = 20/80 = 25%, Security = 15/80 = 18.75%, MCP = 18.75%, Plugin = 18.75%, Context = 18.75%. Note "CLAUDE.md Quality: skipped (no project detected)" in the report.

• Comprehensive: Score all 6 categories normally.

Compute Overall Score

overall = sum(category_score * category_weight for all categories)

Look up the letter grade from the rubric's grade threshold table.

Build Recommendations

Compile a ranked list of recommendations from all audit findings:

• Critical (> 20 point impact): Must fix — actively harming performance

• High (10-20 point impact): Should fix — significant improvement

• Medium (5-9 point impact): Nice to have — incremental improvement

• Low (< 5 point impact): Optional — minor polish

Include both:

• Issues to fix — problems found in current config

• Features to adopt — capabilities from Expert Context the user isn't using

Present the Health Report

Display the report header showing detected scope and file count:

╔══════════════════════════════════════════════════════════╗ ║ CLAUDIT HEALTH REPORT ║ ╠══════════════════════════════════════════════════════════╣ ║ Scope: Comprehensive | Files: N project + N global ║ ║ Overall Score: XX/100 Grade: X (Label) ║ ╚══════════════════════════════════════════════════════════╝

Over-Engineering ████████████████████░░░░░ XX/100 X CLAUDE.md Quality ████████████████████░░░░░ XX/100 X Security Posture ████████████████████░░░░░ XX/100 X MCP Configuration ████████████████████░░░░░ XX/100 X Plugin Health ████████████████████░░░░░ XX/100 X Context Efficiency ████████████████████░░░░░ XX/100 X

For the visual bars, use █ for filled and ░ for empty. Scale to 25 characters total. Append the numeric score and letter grade.

After the score card, present:

• Critical Issues — anything scoring below 50 in a category

• Top Recommendations — ranked list with estimated point impact

• New Features to Adopt — capabilities from Expert Context not currently used

Phase 4: Interactive Enhancement

After presenting the report, offer to implement improvements.

Present Recommendations for Selection

Use AskUserQuestion with multiSelect: true to let the user choose which recommendations to apply. Group by priority (Critical, High, Medium, Low). Include the estimated score impact for each.

Format each option as:

• Label: Short description (e.g., "Trim CLAUDE.md redundancy")

• Description: What will change and estimated point impact (e.g., "Remove 5 restated built-in instructions. ~200 token savings. +15 pts Over-Engineering")

Include a "Skip — no changes" option.

Implement Selected Fixes

For each selected recommendation:

• Read the target file

• Apply the fix using Write or Edit tools

• Briefly explain what changed

Common fix types:

• CLAUDE.md trimming: Remove redundant/restated instructions, consolidate duplicates

• Permission simplification: Replace granular rules with appropriate permission mode

• Hook cleanup: Remove hooks that duplicate built-in behavior, add missing timeouts

• MCP cleanup: Remove servers with missing binaries or duplicate functionality

• Config additions: Add missing recommended settings or sections

• Modularization: Move instructions from monolithic CLAUDE.md to .claude/rules/ or subdirectory files

• Cross-scope cleanup: Remove project-specific instructions from personal config (apply directly, never via PR)

• @import fixes: Remove broken imports, fix circular references

Scope safety for fixes:

• Project-scoped files (CLAUDE.md, .claude/settings.json, .claude/rules/): eligible for direct edit and PR

• CLAUDE.local.md : edit directly, never include in PR (it's gitignored/personal)

• .claude/settings.local.json : edit directly, never include in PR (it's personal/local)

• ~/.claude/ files: edit directly, never include in PR (they're personal)

Re-Score and Show Delta

After implementing fixes:

• Re-score only the affected categories

• Show before/after:

Score Delta: Over-Engineering 65 → 85 (+20) CLAUDE.md Quality 70 → 88 (+18) Overall 72 → 84 (+12) Grade: C → B

Phase 5: PR Delivery

Read ${CLAUDE_PLUGIN_ROOT}/skills/claudit/references/pr-delivery.md and follow the PR delivery instructions.

Error Handling

• If a research agent fails to fetch docs, continue with available knowledge and note the gap

• If an audit agent can't read a config file (doesn't exist), that's valid data — report it as "not configured"

• If the project has no .claude/ directory at all, focus the audit on global config and recommend project-level setup

• If no issues are found (score 90+), congratulate the user and suggest any new features to explore

• If Glob returns too many files (>50), cap and note the truncation

Important Notes

• Never auto-apply changes — always present recommendations and let the user choose

• Quote specific lines when showing what would change in instruction files

• Be opinionated about over-engineering — this is the plugin's core value proposition

• Show token savings whenever removing content from instruction files or other config

• The Expert Context makes this audit unique — always highlight features the user isn't using yet

• Respect scope boundaries — project config is the team contract; personal config is personal

• Only project-scoped files go in PRs — CLAUDE.local.md and ~/.claude/ changes are always local-only