Command Logger Proactive

Proactively logs all Claude Code tool invocations with timestamps and file paths for comprehensive audit trails and debugging.

When to Use This Hook

Attach this hook when you need to:

• Maintain a complete audit trail of every tool invocation during Claude Code sessions for compliance or security review
• Debug unexpected behavior by reviewing the chronological sequence of tool calls that led to a specific state
• Analyze tool usage patterns to understand which tools are used most frequently and optimize your workflow accordingly

Consider alternatives when:

• Claude Code's built-in session history provides sufficient detail for your debugging and review needs
• You are concerned about I/O overhead from logging every single tool invocation in high-frequency editing sessions

Quick Start

Configuration

Copy
name: command-logger-proactive
type: hook
trigger: PreToolUse
category: development-tools

Example Trigger

Copy
# Any tool invocation triggers logging:
# Claude uses the Edit tool on src/app.ts
# Log entry written before tool executes

Example Output

Log file: ~/.claude/command-log.txt

[2026-03-15 14:23:07] Tool: Edit | File: /project/src/app.ts
[2026-03-15 14:23:12] Tool: Read | File: /project/src/utils.ts
[2026-03-15 14:23:15] Tool: Bash | File:
[2026-03-15 14:23:18] Tool: Write | File: /project/src/new-helper.ts
[2026-03-15 14:23:22] Tool: Edit | File: /project/src/app.ts
[2026-03-15 14:23:30] Tool: Bash | File:

Core Concepts

Command Logging Overview

Aspect	Details
Trigger Point	PreToolUse with wildcard matcher to capture all tool invocations
Log Location	~/.claude/command-log.txt (user home directory)
Log Format	[timestamp] Tool: name | File: path per line
Data Source	$CLAUDE_TOOL_NAME and $CLAUDE_TOOL_FILE_PATH environment variables
Write Mode	Append-only to preserve complete session history
Scope	Logs all tools including Edit, Read, Write, Bash, Glob, and Grep

Logging Workflow

Any Tool Invocation
    |
    v
[PreToolUse fires with matcher: *]
    |
    v
[Read $CLAUDE_TOOL_NAME from environment]
    |
    v
[Read $CLAUDE_TOOL_FILE_PATH from environment]
    |
    v
[Format: "[$(date)] Tool: $NAME | File: $PATH"]
    |
    v
[Append to ~/.claude/command-log.txt]
    |
    v
[Tool proceeds with execution]

Configuration

Parameter	Type	Default	Description
log_file	string	~/.claude/command-log.txt	Path to the command log file
matcher	string	*	Tool name pattern to log; * captures all tools
timestamp_format	string	date default	Format for log entry timestamps
include_session_id	boolean	false	Whether to include a unique session identifier in each log entry
max_file_size	string	50MB	Maximum log file size before rotation

Best Practices

1. Rotate logs regularly to manage disk space - The append-only log grows continuously across sessions. Implement log rotation by archiving the file at session start or configuring a size-based rotation policy to prevent unbounded disk usage.

2. Use the log for post-mortem debugging - When something goes wrong, the command log provides an exact timeline of tool invocations. Correlate timestamps with git history to identify which tool call introduced the issue.

3. Add session identifiers for multi-session analysis - Enable include_session_id when you run multiple Claude Code sessions. This allows you to filter log entries by session when analyzing behavior across concurrent or sequential sessions.

4. Exclude read-only tools to reduce noise - If the log is too verbose, change the matcher from * to Edit|Write|MultiEdit|Bash to capture only mutation operations. This reduces log volume while retaining the most actionable audit information.

5. Parse logs programmatically for usage analytics - The consistent log format makes it easy to parse with standard text processing tools. Extract tool usage frequency, session duration, and file edit patterns to identify workflow optimization opportunities.

Common Issues

1. Log file not created on first run - The ~/.claude/ directory may not exist on systems where Claude Code has not been configured before. Create the directory with mkdir -p ~/.claude to ensure the log file can be written.

2. File path column is empty for Bash tools - The $CLAUDE_TOOL_FILE_PATH environment variable is only set for file-specific tools like Edit and Write. Bash operations that do not target specific files will have an empty file path in the log. This is expected behavior.

3. Log file grows very large in active sessions - A busy session can generate thousands of log entries. If the log file exceeds the configured max_file_size, implement rotation or compression. The logrotate utility on Linux can be configured to manage this automatically.