Mole/AGENT.md

Mole AI Agent Guide

Quick reference for AI assistants working on Mole (Mac system cleaner). Last updated: 2026-01-04

Safety Checklist

Before any operation:

• Use safe_* helpers (never raw rm -rf or find -delete)
• Check protection: is_protected(), is_whitelisted()
• Test first: MO_DRY_RUN=1 ./mole clean
• Validate syntax: bash -n <file>
• Run tests: ./scripts/test.sh

Never Do

• Raw deletions without safe_* helpers
• Remove --prefix/--config flags from install.sh
• Commit code unless explicitly requested
• Mix languages: Python in shell, shell in Go
• Delete without checking protection lists

Architecture Quick Map

mole                   # CLI entrypoint (menu + routing)
├── bin/              # Commands: clean, uninstall, optimize, analyze, status
├── lib/              # Shell logic: core/, clean/, ui/
├── cmd/              # Go apps: analyze/, status/
├── tests/            # BATS integration tests
└── scripts/          # Build and test automation

Decision Tree:

• User cleanup logic → lib/clean/<module>.sh
• Command entry → bin/<command>.sh
• Core utils → lib/core/<util>.sh
• Performance tool → cmd/<tool>/*.go
• Tests → tests/<test>.bats

Common Commands

# Validation (run before suggesting changes)
bash -n <file>                    # Syntax check
./scripts/test.sh                 # Full test suite
MO_DRY_RUN=1 ./mole clean         # Safe dry-run test

# Development
make build                        # Build Go binaries
go run ./cmd/analyze              # Test without building
bats tests/clean.bats -f "name"   # Specific test

# Debugging
MO_DEBUG=1 ./mole clean           # Verbose output

Code Style Rules

Shell (Bash 3.2 compatible):

• 2-space indent, quote variables: "$var"
• Use [[ not [, prefer $(cmd) over backticks
• Comments: English, intent-focused, for safety boundaries only
• Entry scripts: 2-3 line header describing purpose

Go:

• Standard conventions: gofmt, go vet
• Never ignore errors

Key Helpers

• safe_rm <path> - Protected deletion
• safe_find_delete <base> <pattern> <days> <type> - Safe find+delete
• is_protected <path> - Check system protection
• is_whitelisted <name> - Check user whitelist
• log_info/success/warn/error <msg> - Logging

Workflow

1. Read first: Never propose changes to unread code
2. Shell work: Logic in lib/, called from bin/
3. Go work: Edit cmd/<app>/*.go
4. Test: Dry-run → BATS → full test suite
5. Style: Match existing file conventions (Bash 3.2)

Example: Add New Cleanup

# 1. Create lib/clean/my_module.sh
clean_my_cache() {
  local dir="$HOME/Library/Caches/MyApp"
  [[ -d "$dir" ]] && ! is_whitelisted "my_app" || return
  safe_find_delete "$dir" "*" "30" "f"
  log_success "Cleaned MyApp cache"
}

# 2. Call from bin/clean.sh
source "${LIB_DIR}/clean/my_module.sh"
clean_my_cache

# 3. Test
bats tests/clean.bats -f "my_cache"

Troubleshooting

• Tests fail → bats tests/<file>.bats -f "test name"
• Syntax error → bash -n <file>
• Permission denied → ./mole touchid
• Cleanup not working → Check is_protected() or ~/.config/mole/whitelist