Configuration Change Audit Log Hook

Hook Type

ConfigChange -- Fires when any configuration file is modified.

Description

This hook maintains a persistent audit log of all configuration changes made during Claude Code sessions. Every change is recorded as a JSON line with timestamp, source, and file path. This is critical for compliance-sensitive environments, debugging configuration drift, and understanding what Claude modified.

Patterns/Rules

• Triggers on all ConfigChange events (empty matcher)
• Appends to ~/claude-config-audit.log in JSONL (one JSON object per line)
• Each entry includes ISO 8601 timestamp, change source, and file path
• Log file persists across sessions
• Uses jq for reliable JSON parsing and generation

Configuration

Copy
{
  "hooks": {
    "ConfigChange": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "jq -c '{timestamp: (now | todate), source: .source, file: .file_path, event: \"config_change\"}' >> ~/claude-config-audit.log"
          }
        ]
      }
    ]
  }
}

Enhanced Version with Session ID

Copy
{
  "hooks": {
    "ConfigChange": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "jq -c --arg sid \"$CLAUDE_SESSION_ID\" '{timestamp: (now | todate), session: $sid, source: .source, file: .file_path}' >> ~/claude-config-audit.log"
          }
        ]
      }
    ]
  }
}

Action

When any configuration file is changed:

1. The ConfigChange event fires with change metadata
2. jq processes the event JSON and adds a timestamp
3. The resulting JSON line is appended to the audit log
4. The log can be queried later for auditing or debugging

Querying the Audit Log

Copy
# View all changes
cat ~/claude-config-audit.log | jq .

# Find changes to a specific file
cat ~/claude-config-audit.log | jq 'select(.file | contains("settings.json"))'

# Changes in the last 24 hours
cat ~/claude-config-audit.log | jq 'select(.timestamp > (now - 86400 | todate))'

# Count changes by file
cat ~/claude-config-audit.log | jq -r '.file' | sort | uniq -c | sort -rn