Auto Change Logger

Logs every file mutation to a structured CSV file for audit trails, demo preparation, and change tracking across all tool operations.

When to Use This Hook

Attach this hook when you need to:

• Maintain a detailed audit log of every file change made during a Claude Code session for compliance or review purposes
• Prepare demo recordings where you need a precise timeline of all modifications with timestamps and tool attribution
• Debug unexpected file changes by reviewing a chronological record of which tools modified which files and when

Consider alternatives when:

• Git history provides sufficient change tracking for your workflow and you do not need sub-commit granularity
• You are working in a high-throughput environment where logging every file mutation creates unacceptable I/O overhead

Quick Start

Configuration

Copy
name: auto-change-logger
type: hook
trigger: PostToolUse
category: automation

Example Trigger

Copy
# Any file edit triggers the logger:
# Claude edits src/app.ts via the Edit tool
# Hook output:
# Change logged: Edit | src/app.ts | 2026-03-15 14:23:07

Example Output

timestamp,tool,file_path,action,details
2026-03-15T14:23:07,Edit,src/app.ts,modified,Lines 14-18 replaced
2026-03-15T14:23:12,Write,src/utils/helper.ts,created,New file 47 lines
2026-03-15T14:24:01,Bash,package.json,modified,npm install executed
2026-03-15T14:24:15,MultiEdit,src/api/routes.ts,modified,3 regions changed
Log location: .claude/critical_log_changes.csv

Core Concepts

Change Logging Overview

Aspect	Details
Output Format	CSV with columns: timestamp, tool, file_path, action, details
Log Location	.claude/critical_log_changes.csv in the project root
Monitored Tools	Edit, MultiEdit, Write, and Bash operations
Trigger Timing	PostToolUse, after each tool completes its operation
Supporting Script	python3 .claude/hooks/change-logger.py processes tool context
Append Mode	New entries are appended to existing log without overwriting history

Logging Workflow

Tool Operation Completes
    |
    v
[PostToolUse fires] --> [Identify tool type]
    |                         |
    v                         v
[Edit?] [Write?] [MultiEdit?] [Bash?]
    |       |         |          |
    +-------+---------+----------+
    |
    v
[change-logger.py extracts context]
    |
    v
[Parse: file path, action, details]
    |
    v
[Append CSV row to critical_log_changes.csv]

Configuration

Parameter	Type	Default	Description
log_file	string	.claude/critical_log_changes.csv	File path for the CSV output relative to the project root
monitored_tools	string	Edit|Write|MultiEdit|Bash	Pipe-separated list of tool names to capture in the change log
timestamp_format	string	ISO8601	Timestamp format for log entries, supports ISO8601 or Unix epoch
max_log_size	string	10MB	Maximum log file size before automatic rotation to a dated archive
include_details	boolean	true	Whether to capture detailed change descriptions or only file paths

Best Practices

1. Rotate logs between sessions - Large projects can generate hundreds of log entries per session. Archive the CSV file at the start of each new session or configure automatic rotation to prevent the log from growing unbounded and slowing down file I/O operations.

2. Use the log for demo narration - When preparing demos or presentations, the timestamped CSV provides an exact chronological script of every change made. Sort by timestamp to reconstruct the development narrative and identify key decision points in the workflow.

3. Filter Bash entries carefully - Bash operations can include commands that do not modify files, such as ls or cat. The logger captures all Bash operations by default, so consider post-processing the CSV to filter out read-only commands when reviewing actual mutations.

4. Protect the log from accidental commits - Add .claude/critical_log_changes.csv to your .gitignore file to prevent sensitive audit data from being committed to the repository. The log may contain internal file paths and operational details that should not be shared publicly.

5. Cross-reference with git diff for completeness - The change log captures tool-level operations while git diff captures content-level changes. Use both together for comprehensive auditing: the log tells you when and which tool made a change, while git diff tells you exactly what changed.

Common Issues

1. Log file not created on first run - The logger script expects the .claude/ directory to exist. If this is a fresh project without Claude Code configuration, create the directory manually with mkdir -p .claude before starting the session, or configure the hook script to create it automatically.

2. Duplicate entries for MultiEdit operations - MultiEdit applies multiple changes to the same file in a single operation, but the hook fires once per tool use. If the logger records each sub-edit separately, you may see apparent duplicates. Check the details column to confirm each entry represents a distinct change region.

3. Bash entries missing file path context - When Bash commands modify files indirectly through piped commands or scripts, the CLAUDE_TOOL_FILE_PATH variable may be empty. The logger records these as entries with an empty file_path column. Review these entries manually to determine which files were actually affected.