melodic-software/audit-settings

Audit Settings Command

Audit Claude Code settings.json files for quality, compliance, and security.

Initialization

Before auditing, initialize the environment:

Get the current UTC date, capture the project root path, ensure the temp directory exists, and clean up stale audit files. The settings-management skill provides authoritative validation guidance (auto-loaded when this command runs).

What Gets Audited

• JSON syntax validity
• Schema compliance (valid settings options)
• Permission rules configuration
• Sandbox settings
• Environment variable configuration
• Security (no exposed secrets)

Command Arguments

| Argument | Description | | --- | --- | | (none) | Audit all discoverable settings files | | project | Only audit .claude/settings.json | | user | Only audit ~/.claude/settings.json | | all | Audit all scopes explicitly | | --force | Audit regardless of modification status | | --skip-validation | Skip finding validation (faster, but may include false positives) |

Step 1: Discover Settings Files

Check project settings (.claude/settings.json), user settings (~/.claude/settings.json on Unix, %USERPROFILE%\.claude\settings.json on Windows), and plugin settings in marketplace repos.

Step 2: Parse Arguments

Parse scope selector and --force flag. Filter files to match requested scope.

Step 3: Present Audit Plan

Display mode, files discovered, and list with scope and last modified date.

Step 4: Execute Audits

For each file, spawn the settings-auditor subagent with scope, path, and last audit date. Run in parallel when multiple exist.

Subagents write findings to .claude/temp/. The main conversation thread collects results and updates audit logs using its Write/Edit tools.

Step 4.5: Validate Findings

Unless --skip-validation flag is present:

1. Spawn the audit-finding-validator agent with:
   • project_root: The captured project root path
   • audit_type: "settings"
   • audit_files: List of .claude/temp/audit-*-settings-*.json file paths
2. Wait for validation to complete
3. Read updated JSON files with validation results
4. Filter out FALSE_POSITIVE findings completely before aggregation
5. Note: Filtered findings are logged to .claude/temp/audit-filtered-findings.json

If --skip-validation flag is present:

• Skip validation phase entirely (current speed preserved)
• Present all findings without filtering
• Note in summary: "Validation: Skipped"

Step 5: Final Summary

Report total audited by scope, results, and details table. List security alerts with remediation.

Include validation statistics (if validation was performed):

• Validation performed: Yes/No
• Findings validated: X
• False positives filtered: Y
• Verified findings: Z
• Unverified findings: W

Security Considerations

| Scope | Credentials Found | Result | | --- | --- | --- | | Project | Yes | CRITICAL - version controlled | | User | Yes | WARNING - not version controlled |

Project settings should NEVER contain API keys or tokens (version controlled).

Cross-Platform Paths

| Platform | User Settings | | --- | --- | | Unix | ~/.claude/settings.json | | Windows | %USERPROFILE%\.claude\settings.json |

Audit Log Location

All audit results are written to .claude/audit/settings.md.

Use /audit-log settings to view current audit status.

Example Usage

Example 1: Audit All Settings Files

User: /audit-settings

Claude: Discovering settings files...

## Audit Plan
**Mode**: SMART
**Files discovered**: 2

1. [project] .claude/settings.json
2. [user] ~/.claude/settings.json

[Spawns settings-auditor subagents]

## Audit Complete
| Scope | File | Result | Score |
| --- | --- | --- | --- |
| project | .claude/settings.json | PASS | 100/100 |
| user | ~/.claude/settings.json | PASS | 98/100 |

Example 2: Audit Project Only

User: /audit-settings project
Claude: Auditing project settings...