Bash Command Logger

Automatic command auditing for Claude Code. Logs all bash commands to a centralized audit file with automatic secret masking.

Example Log Entry

[2024-10-10T15:30:45Z] COMMAND: git status
  DESCRIPTION: Show working tree status
  WORKING_DIR: /Users/developer/my-project
  SESSION_ID: abc123def456
---

Features

• Automatic Logging: Every bash command logged before execution
• Secret Masking: Auto-redacts API keys, passwords, tokens (8 core patterns)
• Log Rotation: Automatic rotation when files exceed 10MB (configurable)
• Non-Blocking: Logging failures never prevent command execution
• Zero Configuration: Works immediately after installation
• Concurrent Safe: File locking prevents log corruption
• Structured Format: ISO 8601 timestamps, session tracking, working directory
• jq Optional: Works with or without jq (better parsing with jq)

Installation

Via Plugin System (Recommended)

The easiest way to install is through Claude Code's plugin system:

# Add the marketplace
/plugin marketplace add ChrisSc/bash-logger-hook

# Install the plugin
/plugin install bash-command-logger@bash-logger-hook

The plugin system automatically:

• Installs the hook script
• Configures the hook in Claude Code settings
• Enables the hook across all projects

After installation, restart Claude Code and the hook will be active.

Manual Installation

For advanced users or custom setups, see Manual Installation Guide.

Quick Start

Verification

# Check hook registration
/hooks

# Test with a command
ls -la

# View log
cat claude-commands.log

For detailed installation instructions, see docs/installation.md.

Documentation

• Installation Guide - Global and project-level installation
• Configuration - Timeouts, log format, secret masking
• Security - Secret masking patterns, best practices, threat model
• Testing - Running tests, manual testing, writing new tests
• Troubleshooting - Common issues and solutions

Usage

View Logs

# View entire log
cat claude-commands.log

# Last 20 entries
tail -20 claude-commands.log

# Search for git commands
grep "COMMAND: git" claude-commands.log

# Watch in real-time
tail -f claude-commands.log

Maintenance

Automatic Rotation

Logs are automatically rotated when they exceed 10MB (default, configurable):

# Rotated files are named with timestamps
claude-commands-20251011-143022.log
claude-commands-20251011-150315.log

# Configure rotation threshold (in MB)
export BASH_LOGGER_MAX_SIZE_MB=20

# Keep last 10 rotations (default: 5)
export BASH_LOGGER_ROTATE_COUNT=10

# Enable compression
export BASH_LOGGER_COMPRESS_OLD=true

Manual Rotation

# Check size
du -h claude-commands.log

# Archive logs
mv claude-commands.log "claude-commands-$(date +%Y%m%d).log"

# Keep last 1000 entries
tail -1000 claude-commands.log > claude-commands.tmp
mv claude-commands.tmp claude-commands.log

Security

Automatic Masking

Sensitive data is automatically masked using 8 core patterns:

• GitHub tokens: Personal access tokens, OAuth tokens
• API keys: Various formats (quoted, unquoted, case-insensitive)
• Bearer tokens: Authorization headers
• AWS keys: Access key IDs (AKIA...)
• URL credentials: Passwords in connection strings
• Generic secrets: PASSWORD, TOKEN, SECRET, AUTH keywords
• Command flags: -p, --password flags
• Private keys: RSA, OpenSSH key blocks

Default behavior: Masking enabled, extensible via environment variables

Best Practices

# Restrict log access
chmod 600 claude-commands.log

# Exclude from version control
echo "claude-commands.log" >> .gitignore

# Add custom patterns for organization-specific secrets
export BASH_LOGGER_MASK_PATTERNS="CORP_API_KEY=[A-Z0-9]{32}"

Important: Masking is defense-in-depth, not 100% effective. Encoded secrets may bypass detection. See docs/security.md for details.

Technical Details

Architecture

Claude Code prepares bash command
    ↓
PreToolUse event triggers (matcher: "Bash")
    ↓
bash-logger.sh receives JSON via stdin
    ↓
Parse and mask sensitive data
    ↓
Acquire lock (timeout: 5s)
    ↓
Append to claude-commands.log
    ↓
Release lock and exit (code 0 or 1)
    ↓
Original command executes

Performance

• Typical overhead: 10-50ms per command
• With jq: 10-20ms
• Without jq: 20-40ms
• Memory: <1 MB
• Lock overhead: <5ms (concurrent writes only)

Platform Support

• Supported: macOS, Linux (bash 4.0+)
• Requires: Standard Unix utilities (grep, sed, cat, date)
• Optional: jq for better JSON parsing
• Not Supported: Native Windows (use WSL2)

Contributing

Contributions welcome! Common improvements:

• Additional secret patterns
• Database logging support
• Analysis/reporting tools
• Windows PowerShell port

Submit issues or pull requests on GitHub.

License

MIT License - modify and distribute freely.

Resources

• Claude Code Documentation
• Hooks System Guide
• jq Manual

---

Repository: https://github.com/ChrisSc/bash-logger-hook Version: 3.0.0