Claudit: Claude Code Configuration Audit

/claudit

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 2: Scope Detection

• If

  PROJECT_ROOT

  is found → comprehensive (global + project)
• If

  PROJECT_ROOT

  is empty → global only

Step 3: Comprehensive Configuration Scan

{PROJECT_ROOT}/**/CLAUDE.md

{PROJECT_ROOT}/CLAUDE.local.md

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

{PROJECT_ROOT}/.claude/settings.json

{PROJECT_ROOT}/.claude/settings.local.json

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

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

{PROJECT_ROOT}/.claude/MEMORY.md

{PROJECT_ROOT}/.mcp.json

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

**/CLAUDE.md

node_modules

.git

vendor

dist

build

~/.claude/settings.json

~/.claude/CLAUDE.md

~/CLAUDE.md

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

~/.claude/MEMORY.md

~/.claude/.mcp.json

~/.claude/plugins/installed_plugins.json

~/.claude/plugins/known_marketplaces.json

/Library/Application Support/ClaudeCode/CLAUDE.md

/etc/claude-code/CLAUDE.md

wc -l

/Library/Application Support/...

Step 4: Build and Present the Configuration Map

=== 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 ===

(total_lines * 40) / 4

chars/4

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

Phase 1: Build Expert Context

run_in_background

Dispatch All Three Simultaneously

• 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."

• 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."

• 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

=== 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 ===

Expert context assembled. Proceeding to configuration analysis...

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

Phase 2: Expert-Informed Audit

Build Agent Dispatch Prompts

audit-global

• 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.

audit-project

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

audit-ecosystem

• 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

audit-global

audit-ecosystem

• subagent_type

  : "claudit:audit-global"

• subagent_type

  : "claudit:audit-project"

• subagent_type

  : "claudit:audit-ecosystem"

Phase 3: Scoring & Synthesis

• Read

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

Score Each Category

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

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

Build Recommendations

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

• Issues to fix — problems found in current config
• Features to adopt — capabilities from Expert Context the user isn't using

Present the Health Report

╔══════════════════════════════════════════════════════════╗
║                  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

█

░

1. Critical Issues — anything scoring below 50 in a category
2. Top Recommendations — ranked list with estimated point impact
3. New Features to Adopt — capabilities from Expert Context not currently used

Phase 4: Interactive Enhancement

Present Recommendations for Selection

multiSelect: true

• 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")

Implement Selected Fixes

1. Read the target file
2. Apply the fix using Write or Edit tools
3. Briefly explain what changed

• 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

• 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

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

Offer PR Option

AskUserQuestion

• "Open a PR" — Create branch, commit changes, push, open PR with educational inline comments
• "Keep as local edits" — Leave changes uncommitted in the working tree

Check Prerequisites

1. Verify

   gh

   CLI is available:

   command -v gh

2. Verify

   gh

   is authenticated:

   gh auth status

3. If either fails, tell the user

   gh

   CLI is required for PR delivery and fall back to "Keep as local edits"

Create the PR

1. Record the current branch:

   CURRENT_BRANCH=$(git rev-parse --abbrev-ref HEAD)

   — this is the branch the user was on before claudit creates its own branch. The PR will target this branch so the diff only shows claudit changes.
2. Create branch:

   git checkout -b claudit/improvements-YYYY-MM-DD-HHMM

   (use today's date and current time to avoid same-day collisions)
3. Stage changed project files: Only stage project-scoped files that were modified in Phase 4. Never stage:

   • CLAUDE.local.md

     (gitignored/personal)

   • .claude/settings.local.json

     (personal local settings)
   • Any file under

     ~/.claude/

     (personal config)
   • Any file outside the project root
4. Commit with a clear message including the score delta:

   claudit: improve Claude Code configuration (score XX → YY)
   
   - [List key changes]

5. Push with

   git push -u origin claudit/improvements-YYYY-MM-DD-HHMM

   (same branch name as step 2)
6. Create PR via

   gh pr create --base $CURRENT_BRANCH

   :
   • Title:

     claudit: improve Claude Code configuration

   • Body: Concise summary with score delta, list of changes, and note that personal/global config was audited separately (if comprehensive)
   • The

     --base

     flag ensures the PR targets the user's original branch, not the repo default — so the diff only contains claudit's changes
7. Add inline review comments via

   gh api

   for each changed file. Use this JSON structure:
   bash

   gh api repos/{owner}/{repo}/pulls/{pr_number}/comments \
     --method POST \
     --field commit_id="$(git rev-parse HEAD)" \
     --field path="path/to/file" \
     --field line=N \
     --field side="RIGHT" \
     --field body="**What changed:** Brief description
   
   **Why it matters:** 1-2 sentences on impact
   
   **Claude Code feature:** Feature name
   **Docs:** https://docs.anthropic.com/en/docs/claude-code/relevant-page
   **Score impact:** +N pts Category"

   To determine the correct

   line

   value, run

   git diff HEAD~1 -- path/to/file

   and find line numbers within changed hunks. The

   line

   must be a line number in the new file version that falls within a diff hunk range. Target the most representative changed line per hunk. If line targeting fails (422 error), fall back to a general PR comment without line numbers using

   gh pr comment

   .
   Add one comment per significant change. Keep comments concise and educational.
8. Return the PR URL to the user.

Fallback

gh

• Tell the user what happened
• Fall back to "Keep as local edits"
• Show a

  git diff --stat

  of what was changed

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