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:

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
Wait for validation to complete
Read updated JSON files with validation results
Filter out FALSE_POSITIVE findings completely before aggregation
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...