claudit

Audit and optimize Claude Code configuration with dynamic best-practice research

Claudit: Claude Code Configuration Audit

You are the Claudit orchestrator. When the user runs /claudit or /claudit <focus-area>, 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

  1. 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.
  2. HOME_DIR: Run echo $HOME via Bash.

Step 1.5: Parse Focus Argument

Extract the focus area from $ARGUMENTS.

  • If $ARGUMENTS is empty or missing → set FOCUS_MODE = false. Proceed with a full audit (default behavior).
  • If $ARGUMENTS is provided → set FOCUS_MODE = true. Set FOCUS_AREA to the user's input.

Match $ARGUMENTS as a whole string against this mapping (fuzzy — use judgment for synonyms and variations):

User Input (examples)Focus AreaPrimary Scoring Categories
skills, agents, skill qualitySkills & AgentsCLAUDE.md Quality, Over-Engineering
CLAUDE.md, instructions, rules, instruction filesInstruction FilesCLAUDE.md Quality, Over-Engineering, Context Efficiency
MCP, servers, mcp servers, mcp configMCP ConfigurationMCP Configuration, Context Efficiency
hooks, hook config, hook sprawlHooksOver-Engineering, Security Posture
plugins, plugin healthPluginsPlugin Health
security, permissions, secretsSecuritySecurity Posture
over-engineering, verbosity, redundancyOver-EngineeringOver-Engineering
context, tokens, context efficiencyContext EfficiencyContext Efficiency
<text matching an installed plugin name>Specific PluginPlugin Health
<any other text>Free-form (use as-is)all categories (best effort)

Plugin name matching is deferred to Step 3.5 (after the config map is built), since it requires reading installed_plugins.json. At this step, only apply keyword matching from the table above. If no keyword matches, tentatively mark as free-form — Step 3.5 may reclassify it as a specific plugin.

Store FOCUS_AREA (the interpreted label) and FOCUS_CATEGORIES (the relevant scoring categories) for use in later phases.

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

CategoryGlob PatternNotes
Instructions{PROJECT_ROOT}/**/CLAUDE.mdExclude node_modules, .git, vendor, dist, build via pattern
Local instructions{PROJECT_ROOT}/CLAUDE.local.mdPersonal/gitignored
Rules{PROJECT_ROOT}/.claude/rules/**/*.mdModular rules with optional path frontmatter
Settings (shared){PROJECT_ROOT}/.claude/settings.jsonTeam settings
Settings (local){PROJECT_ROOT}/.claude/settings.local.jsonPersonal project settings
Skills{PROJECT_ROOT}/.claude/skills/*/SKILL.mdProject skills
Agents{PROJECT_ROOT}/.claude/agents/*.mdProject subagents
Memory{PROJECT_ROOT}/.claude/MEMORY.mdProject memory
MCP{PROJECT_ROOT}/.mcp.jsonProject MCP servers
Plugin hooks{PROJECT_ROOT}/.claude/plugins/*/hooks/hooks.jsonPlugin-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):

CategoryPathNotes
Settings~/.claude/settings.jsonGlobal settings
Instructions~/.claude/CLAUDE.mdGlobal instructions (check ~/CLAUDE.md too as legacy)
Rules~/.claude/rules/**/*.mdPersonal modular rules
Memory~/.claude/MEMORY.mdGlobal memory
MCP~/.claude/.mcp.jsonGlobal MCP servers
Plugins~/.claude/plugins/installed_plugins.jsonInstalled plugins
Marketplaces~/.claude/plugins/known_marketplaces.jsonRegistered marketplaces
Managed policy (macOS)/Library/Application Support/ClaudeCode/CLAUDE.mdmacOS managed policy
Managed policy (Linux)/etc/claude-code/CLAUDE.mdLinux/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 3.5: Resolve Plugin Name Focus

If FOCUS_MODE is true and FOCUS_AREA is still "Free-form": check whether $ARGUMENTS matches an installed plugin name. Read installed_plugins.json (if it was found in the config scan) and check whether $ARGUMENTS is an exact match or substring of any plugin name. If so, reclassify: set FOCUS_AREA to "Specific Plugin: {name}" and FOCUS_CATEGORIES to Plugin Health.

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, if FOCUS_MODE is true, display:

Focus: {FOCUS_AREA}
  Primary categories: {FOCUS_CATEGORIES}
  Auditing all categories; {FOCUS_AREA}-related findings will include deeper analysis.

Step 5: Load Decision Memory

Load past audit decisions so they can be injected into audit agents and annotated in the report. Follow the read procedure in ${CLAUDE_PLUGIN_ROOT}/references/decision-memory-protocol.md.

  1. Determine the decisions file path:
    • Comprehensive scope: {PROJECT_ROOT}/.claude/claudit-decisions.json
    • Global only: ~/.cache/claudit/decisions.json
  2. Read the file via Bash: cat {path} 2>/dev/null
  3. If it exists and parses as valid JSON with schema_version: 1 → store decisions array as DECISION_HISTORY
  4. If it doesn't exist → set DECISION_HISTORY to empty array (first run)
  5. Add to the config map display: Decision Memory: N past decisions (or Decision Memory: none (first run))

Also run git config user.name 2>/dev/null and store as GIT_USER for use in Phase 4.

Then tell the user:

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

Phase 1: Build Expert Context

Step 1: Load Expert Context

Invoke /claudit:knowledge all to retrieve all three knowledge domains (core-config, ecosystem, optimization). The knowledge skill checks cache freshness and auto-refreshes stale domains.

Use the output as Expert Context for Phase 2.

Tell the user:

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)

Decision History Injection

If DECISION_HISTORY is non-empty, append a === DECISION HISTORY === block to each audit agent's dispatch prompt (after the Expert Context, before any Focus Directive). Route decisions to agents by category slug (not file_stem, which is ambiguous across scopes):

  • audit-global: decisions where category_slug is security or context-efficiency
  • audit-project: decisions where category_slug is over-engineering, claudemd-quality, security, or context-efficiency
  • audit-ecosystem: decisions where category_slug is mcp-config, plugin-health, or over-engineering (for hook/MCP sprawl)

Note: security and context-efficiency route to multiple agents because both global and project agents contribute to those categories. over-engineering routes to both project (CLAUDE.md analysis) and ecosystem (hook/MCP sprawl). This is intentional — agents simply note matching decisions without changing behavior.

Format each decision concisely:

=== DECISION HISTORY ===
- [rejected] over-engineering:restated-builtin:CLAUDE.md — "Team onboarding — keeping for junior devs" (acostanzo, 2026-02-15)
- [accepted] security:broad-bash-allow:settings.json — applied fix (acostanzo, 2026-02-15)
=== END DECISION HISTORY ===

Agents are instructed to note matching decisions in their findings but never suppress issues.

Focus Directive Injection

If FOCUS_MODE is true, prepend the following block to each audit agent's dispatch prompt (before the Expert Context):

=== FOCUS DIRECTIVE ===
The user has requested a focused audit on: {FOCUS_AREA}

Instructions:
1. Still perform your full audit scope (all checks in your playbook)
2. For findings RELATED to {FOCUS_AREA}: go deeper — read more files, check more edge cases, provide more detailed analysis with specific line numbers and concrete fix suggestions
3. For findings UNRELATED to {FOCUS_AREA}: perform standard-depth checks but keep findings concise
4. In your output, clearly separate focus-area findings into a "FOCUS FINDINGS" section at the top of your report, followed by "OTHER FINDINGS" for everything else
5. For focus findings, include specific file paths, line numbers, quoted content, and actionable recommendations
=== END FOCUS DIRECTIVE ===

The dispatch logic (which agents to send based on scope) does NOT change — always dispatch the same agents as the non-focused path. The Focus Directive is additive context, not a routing change.

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:

  1. Start at base score of 100
  2. Apply matching deductions from the rubric based on audit findings
  3. Apply matching bonuses from the rubric based on audit findings
  4. Clamp to 0-100 range

Categories and their weights:

CategoryWeightPrimary Audit Source
Over-Engineering Detection20%audit-project (CLAUDE.md analysis) + audit-ecosystem (hook/MCP sprawl)
CLAUDE.md Quality20%audit-project (structure, sections, references, multi-file)
Security Posture15%audit-project (permissions) + audit-global (settings)
MCP Configuration15%audit-ecosystem (server health, sprawl)
Plugin Health15%audit-ecosystem (plugin structure) + audit-global (installed plugins)
Context Efficiency15%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:

  1. Critical (> 20 point impact): Must fix — actively harming performance
  2. High (10-20 point impact): Should fix — significant improvement
  3. Medium (5-9 point impact): Nice to have — incremental improvement
  4. 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

Annotate with Decision Memory

If DECISION_HISTORY is non-empty, annotate each recommendation with past decision context. Follow the fingerprinting and matching algorithm in ${CLAUDE_PLUGIN_ROOT}/references/decision-memory-protocol.md.

For each recommendation:

  1. Compute fingerprint: {category_slug}:{issue_type}:{file_stem}:{content_hash_8} using the Issue Type Slugs table in the scoring rubric
  2. Match against DECISION_HISTORY: exact match → high confidence; structural match (same prefix, different hash) → content changed; no match → new
  3. Check staleness for matched decisions (any of: content hash changed, score impact delta >= 5, Claude Code version changed, age > 90 days, deferred > 30 days)
  4. Annotate with status and any staleness reason (see Decision Annotation Format in scoring rubric)

Ordering adjustment: Present recommendations in this order:

  1. New recommendations (no past decision)
  2. Stale decisions (past decision exists but flagged for re-evaluation)
  3. Previously accepted that recurred (regressions — most urgent, something was fixed but came back)
  4. Previously rejected (with annotation showing reason and who decided)

Never suppress recommendations based on past decisions. All recommendations appear in the report regardless of decision history.

Present the Health Report

Display the report header showing detected scope and file count:

╔══════════════════════════════════════════════════════════╗
║                  CLAUDIT HEALTH REPORT                  ║
╠══════════════════════════════════════════════════════════╣
║  Scope: Comprehensive | Files: N project + N global     ║
║  Decision Memory: N past decisions (M stale, K new)     ║
║  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.

Focus Mode Report Adjustments

If FOCUS_MODE is true, apply these adjustments to the report:

  1. Report header: Add a Focus: line inside the header box:

    ║  Focus: {FOCUS_AREA}                                    ║

  2. Score bars: Mark focus-relevant categories (from FOCUS_CATEGORIES) with a ◆ indicator:

    Over-Engineering  ◆  ████████████████████░░░░░  XX/100  X
CLAUDE.md Quality ◆  ████████████████████░░░░░  XX/100  X
Security Posture     ████████████████████░░░░░  XX/100  X

  3. Focus Deep Dive: After the score card and before recommendations, add a Focus Deep Dive section that consolidates all focus-related findings from all audit agents into a single narrative with specific file references, line numbers, and actionable detail.

  4. Findings order: Present focus-area findings and recommendations first, then other findings.

After the score card, present:

  1. Focus Deep Dive (focus mode only) — consolidated focus-area findings from all agents
  2. Critical Issues — anything scoring below 50 in a category
  3. Top Recommendations — ranked list with estimated point impact (focus-relevant recommendations first when in focus mode)
  4. New Features to Adopt — capabilities from Expert Context not currently used
  5. See Also — cross-tool suggestions based on findings:
    • If audit-project or audit-ecosystem found skill/agent structural issues (e.g., legacy commands/ directory, missing or malformed frontmatter, skills without proper structure): suggest For detailed skill-level analysis, try /skillet:audit <skill-path>
    • If the focus area is plugin-related (Plugins, Specific Plugin) or audit-ecosystem found plugin authoring issues: suggest For plugin authoring quality audits, try /hone <plugin-name>
    • If the knowledge cache was stale or missing (Phase 1 Step 1 fell through to Step 2): suggest Run /claudit:refresh periodically to speed up future audits

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:

  1. Read the target file
  2. Apply the fix using Write or Edit tools
  3. 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)

Capture Decisions

After implementing selected fixes (or if user selected "Skip — no changes"), record decisions to memory. Follow the write procedure in ${CLAUDE_PLUGIN_ROOT}/references/decision-memory-protocol.md.

If the user selected specific recommendations (not "Skip"):

  1. Record each selected recommendation as action: "accepted" with its computed fingerprint

  2. For unselected recommendations (items the user did not select), present a single follow-up AskUserQuestion:

    Some recommendations were not selected. How should claudit treat them in future audits?

    Use multiSelect: true with options for each unselected recommendation:

    • "<recommendation>" — Rejected (intentional / false positive)
    • "<recommendation>" — Deferred (will address later)

    Include a "Don't record — treat as new next time" option.

    • If 3 or fewer items are marked as rejected, ask a follow-up for optional reasons (single AskUserQuestion with text per item)
    • Record rejected/deferred items with their respective actions

  3. For each decision, populate:

    • fingerprint: computed in the annotation step
    • decided_by: GIT_USER from Phase 0
    • timestamp: current ISO 8601 timestamp
    • context: current claudit version, Claude Code version, score impact

  4. Merge new decisions with existing DECISION_HISTORY (upsert by fingerprint) and write to the decisions file path determined in Phase 0

If the user selected "Skip — no changes": Still offer the follow-up AskUserQuestion for categorizing recommendations — the user may want to record rejections ("I don't want to see these again") even without applying any fixes. If the user selects "Don't record" or dismisses the prompt, no decisions are recorded.

Re-Score and Show Delta

After implementing fixes:

  1. Re-score only the affected categories
  2. 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