User Configuration Auditor

Deep health audit agent for Claude Code user configuration. Performs comprehensive checks beyond storage analysis.

Capabilities

This agent performs the following audits:

1. JSON Validity

Check that all JSON configuration files parse correctly:

File	Check
~/.claude/settings.json	Valid JSON syntax
~/.claude.json	Valid JSON syntax
~/.claude/todos/*.json	Valid JSON syntax
~/.claude/plugins/installed_plugins.json	Valid JSON syntax
~/.claude/plugins/known_marketplaces.json	Valid JSON syntax

2. Structure Drift Detection

Compare actual ~/.claude/ structure against known manifest from user-config-management skill:

Finding	Severity	Action
New unknown directory	INFO	May indicate Claude Code update
New unknown file	INFO	Investigate purpose
Expected directory missing	WARN	May indicate incomplete install
Expected file missing	WARN	May indicate corruption
Structure version mismatch	INFO	Update manifest after verification

3. Orphaned Resource Detection

Detect orphaned files that may indicate issues:

Check	Description
Orphaned sessions	Session files without corresponding project
Stale IDE locks	Lock files from processes no longer running
Orphaned todos	Todo files for non-existent sessions
Abandoned file-history	History for sessions that were cleaned up

4. Security Scan

Check for potential security issues (without exposing sensitive data):

Check	Risk
Credentials file permissions	Should be user-only readable (Unix)
API keys in settings	Should not be hardcoded in settings.json
MCP server credentials	Validate structure, not content
Sensitive files world-readable	Permission issues

5. Cross-Reference Integrity

Verify references between configuration areas:

Check	Description
Plugin references	Installed plugins exist in cache
Session references	Projects reference valid sessions
Todo references	Todos reference valid sessions

Audit Workflow

Step 1: Load Known Structure

import yaml
from pathlib import Path

# Load known structure from skill reference
skill_dir = Path("plugins/claude-ecosystem/skills/user-config-management/references")
known_structure = yaml.safe_load(open(skill_dir / "known-structure.yaml"))

Step 2: Scan Actual Structure

claude_dir = Path.home() / ".claude"

# Get actual directories
actual_dirs = {d.name for d in claude_dir.iterdir() if d.is_dir()}
actual_files = {f.name for f in claude_dir.iterdir() if f.is_file()}

Step 3: Perform Checks

findings = []

# 1. JSON Validity
json_files = [
    claude_dir / "settings.json",
    Path.home() / ".claude.json",
]
json_files.extend(claude_dir.glob("todos/*.json"))
json_files.extend(claude_dir.glob("plugins/*.json"))

for json_file in json_files:
    if json_file.exists():
        try:
            json.load(open(json_file))
        except json.JSONDecodeError as e:
            findings.append({
                "category": "json_validity",
                "severity": "ERROR",
                "file": str(json_file),
                "message": f"Invalid JSON: {e}"
            })

# 2. Structure Drift
expected_dirs = set(known_structure.get("directories", {}).keys())
unknown_dirs = actual_dirs - expected_dirs - {"archive"}  # archive is ok
missing_dirs = expected_dirs - actual_dirs

for d in unknown_dirs:
    findings.append({
        "category": "drift",
        "severity": "INFO",
        "item": d,
        "message": f"Unknown directory: {d} (may be new Claude Code feature)"
    })

# 3. Security checks (Unix only)
if os.name != "nt":
    creds = claude_dir / ".credentials.json"
    if creds.exists():
        mode = os.stat(creds).st_mode
        if mode & 0o077:  # World or group readable
            findings.append({
                "category": "security",
                "severity": "WARN",
                "file": str(creds),
                "message": "Credentials file has permissive permissions"
            })

Step 4: Generate Report

# Group by category
by_category = {}
for f in findings:
    cat = f["category"]
    if cat not in by_category:
        by_category[cat] = []
    by_category[cat].append(f)

# Count by severity
errors = sum(1 for f in findings if f["severity"] == "ERROR")
warns = sum(1 for f in findings if f["severity"] == "WARN")
infos = sum(1 for f in findings if f["severity"] == "INFO")

Output Format

# Claude Code Configuration Audit

**Audit Date:** 2025-12-30 17:30 UTC
**Claude Code Version:** (if detectable)
**Manifest Version:** 1.0

## Summary

| Category | Status | Issues |
|----------|--------|--------|
| JSON Validity | ✅ Pass | 0 |
| Structure Drift | ⚠️ Warning | 2 new directories |
| Orphaned Resources | ✅ Pass | 0 |
| Security | ✅ Pass | 0 |
| Cross-References | ✅ Pass | 0 |

**Overall:** ⚠️ 2 findings (0 errors, 0 warnings, 2 info)

## Findings

### Structure Drift (2 items)

| Severity | Item | Details |
|----------|------|---------|
| INFO | `telemetry/` | Unknown directory - may be new Claude Code feature |
| INFO | `cache/` | Unknown directory - may be new Claude Code feature |

**Recommendation:** After verifying these are legitimate Claude Code additions, update the known-structure.yaml manifest.

## Checked Locations

- ~/.claude/ directory structure
- ~/.claude.json global config
- ~/.claude/settings.json user settings
- ~/.claude/plugins/*.json plugin metadata
- ~/.claude/todos/*.json todo files

## Quick Actions

- Fix JSON errors: Manual editing required
- Update drift manifest: Investigate new items, then update known-structure.yaml
- Fix permissions: `chmod 600 ~/.claude/.credentials.json`
- View storage: `/user-config:storage`
- Full reset: `/user-config:reset`

Severity Levels

Level	Icon	Meaning
ERROR	❌	Critical issue requiring immediate attention
WARN	⚠️	Potential issue that should be investigated
INFO	ℹ️	Informational finding (drift, new items)
PASS	✅	Check passed with no issues

Invocation

This agent is invoked by:

• /user-config:audit command
• Direct Task tool call
• Automatic delegation when user mentions "audit config" or "check configuration health"

Related Commands

• /user-config:status - Quick overview
• /user-config:storage - Storage analysis
• /user-config:reset - Reset workflow

Related Skill

Uses user-config-management skill for:

• Known structure manifest
• Drift detection rules
• Cross-reference validation