How to Enable Debug Logging in Mole: A Complete Guide

Set the MO_DEBUG environment variable to 1 or pass the --debug flag to any Mole command to enable verbose logging to ${HOME}/Library/Logs/mole/mole_debug_session.log.

Mole is a macOS utility by tw93 designed for managing applications and system optimization. When troubleshooting issues or auditing operations, you may need to enable debug logging in Mole to capture detailed execution traces and system information.

Understanding Mole's Debug Logging Architecture

The MO_DEBUG Environment Variable

Mole's debug logging is controlled entirely by the MO_DEBUG environment variable. When this variable is set to 1, the logging system activates verbose output mode. This design allows both manual environment configuration and automated flag handling through command wrappers.

Central Logging Implementation in lib/core/log.sh

The core logging logic resides in lib/core/log.sh. This file contains function definitions that check the debug state using conditional expressions like if [[ "${MO_DEBUG:-}" == "1" ]].

Key functions affected by debug mode include:

• log_info() – Writes informational messages
• log_success() – Confirms successful operations
• debug_log() – Writes debug-specific entries
• log_system_info() – Dumps system details when the module loads

When MO_DEBUG=1, these functions write additional [DEBUG] entries to the session log file at ${HOME}/Library/Logs/mole/mole_debug_session.log.

How to Enable Debug Logging in Mole

Method 1: Using the --debug Command Flag

Each top-level Mole command supports a --debug flag that automatically exports the environment variable. The argument parsers in command wrappers like bin/clean.sh, bin/optimize.sh, bin/installer.sh, bin/purge.sh, and bin/uninstall.sh contain this case statement:

"--debug")
    export MO_DEBUG=1
    ;;

To enable debug logging for a single operation:

mo clean --debug

This exports MO_DEBUG=1 for the duration of that command only.

Method 2: Setting the MO_DEBUG Environment Variable

For granular control, export the variable directly in your shell:

export MO_DEBUG=1
mo optimize

This approach persists for the entire shell session, affecting all subsequent Mole commands without requiring the --debug flag.

Method 3: Persistent Debug Mode in Shell Sessions

To maintain debug logging across multiple terminal sessions, add the export to your shell configuration file:

echo 'export MO_DEBUG=1' >> ~/.zshrc

After reloading your configuration (source ~/.zshrc), every Mole command will automatically run in debug mode.

What Gets Logged When Debug Mode Is Active

System Information Dump

When lib/core/log.sh loads with MO_DEBUG=1, the log_system_info() function executes immediately. This writes a header containing:

• macOS version
• Sudo status
• Shell environment details
• Timestamp markers

This header appears at ${HOME}/Library/Logs/mole/mole_debug_session.log before any command-specific output.

Operation Boundaries and Cache Removal Details

During command execution, debug mode captures:

• Function entry points (e.g., === start_cleanup ===)
• Cache removal operations with specific byte counts
• File path resolutions
• Success/failure states for each sub-operation

Example log output:

[DEBUG] Debug session log saved to: /Users/you/Library/Logs/mole/mole_debug_session.log
[DEBUG] === start_cleanup ===
[DEBUG] Removing cache: /Users/you/Library/Caches/com.example.app (120.3MB)
[DEBUG] Operation completed successfully

Viewing and Analyzing Debug Logs

To inspect the detailed execution trace:

less "${HOME}/Library/Logs/mole/mole_debug_session.log"

For real-time monitoring during command execution:

tail -f "${HOME}/Library/Logs/mole/mole_debug_session.log" &
mo clean --debug

To filter for specific operations:

grep "start_cleanup" "${HOME}/Library/Logs/mole/mole_debug_session.log"

Summary

• Debug logging in Mole is controlled by setting MO_DEBUG=1 as an environment variable.
• The --debug flag on any command (mo clean --debug, mo optimize --debug) automatically exports this variable.
• Central logging logic resides in lib/core/log.sh, which checks MO_DEBUG and writes to ${HOME}/Library/Logs/mole/mole_debug_session.log.
• When enabled, log_system_info() dumps system details immediately, and all operations write verbose [DEBUG] entries showing boundaries, file removals, and status changes.
• Command wrappers in bin/clean.sh, bin/optimize.sh, and related files implement the --debug parsing.

Frequently Asked Questions

Where does Mole store its debug log files?

Mole writes debug logs to ${HOME}/Library/Logs/mole/mole_debug_session.log on macOS. This path is hardcoded in lib/core/log.sh and is created automatically when MO_DEBUG=1 is set and any logging function executes.

Can I enable debug logging for all Mole commands at once?

Yes. Export MO_DEBUG=1 in your shell configuration file (e.g., ~/.zshrc or ~/.bash_profile). This persists the setting across all terminal sessions, ensuring every Mole command runs with debug logging enabled without requiring the --debug flag.

Does the --debug flag work with every Mole subcommand?

Yes. The --debug flag is implemented consistently across all command wrappers including bin/clean.sh, bin/optimize.sh, bin/installer.sh, bin/purge.sh, and bin/uninstall.sh. Each wrapper parses the flag and exports MO_DEBUG=1 before executing the command logic.

How do I disable debug logging once enabled?

If you set MO_DEBUG manually using export MO_DEBUG=1, run unset MO_DEBUG or close the terminal session. If you added the export to your shell configuration file, remove that line and run source ~/.zshrc (or equivalent) to reload the configuration. The --debug flag only affects the single command invocation, so subsequent commands run without debug logging unless the flag is passed again.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}