Auto Browser Cleaner

Automated browser history and cache cleaner with customizable retention policies.

Features

• Multi-browser support: Chrome, Firefox, Safari
• Configurable retention policies: Set rules by domain and date
• Scheduled cleaning: Cron-like syntax for automated execution
• Web dashboard: Monitor and control cleaning operations
• Statistics and reporting: Track cleaned data and performance
• Backup system: Safely backup data before cleaning
• Notifications: Get alerts about cleaning operations
• Docker support: Easy deployment with containers

Installation

From PyPI (Recommended)

pip install auto-browser-cleaner

From Source

git clone https://github.com/yourusername/auto-browser-cleaner.git
cd auto-browser-cleaner
pip install -e .

Docker

docker pull auto-browser-cleaner:latest
# Or build from source
docker-compose up -d

Quick Start

Command Line Usage

# Initialize configuration
auto-browser-cleaner init

# Run cleaning with default config
auto-browser-cleaner clean

# Clean specific browser
auto-browser-cleaner clean --browser chrome

# Dry run to see what would be cleaned
auto-browser-cleaner clean --dry-run

# Start scheduler daemon
auto-browser-cleaner schedule --daemon

# Launch web dashboard
auto-browser-cleaner dashboard --host 0.0.0.0 --port 8080

Configuration

Create a config.yaml file:

browsers:
  chrome:
    enabled: true
    data_dir: "~/.config/google-chrome"
  firefox:
    enabled: true
    profile_dir: "~/.mozilla/firefox"
  safari:
    enabled: false

retention:
  default_days: 30
  rules:
    - domain: "example.com"
      days: 7
    - domain: "*.social.com"
      days: 1
    - domain: "important-site.com"
      days: 365

schedule:
  enabled: true
  cron: "0 2 * * *"  # Daily at 2 AM

logging:
  level: INFO
  file: "cleaner.log"

notifications:
  email:
    enabled: false
    smtp_server: "smtp.gmail.com"
    smtp_port: 587
    username: "your-email@gmail.com"
    password: "your-app-password"
    to: "admin@example.com"

backup:
  enabled: true
  directory: "./backups"
  max_backups: 5

web:
  enabled: true
  host: "127.0.0.1"
  port: 8080
  auth:
    enabled: false
    username: "admin"
    password: "secure-password"

Usage Examples

Basic Cleaning

from auto_browser_cleaner import BrowserCleaner
from auto_browser_cleaner.config import Config

# Load configuration
config = Config.from_file('config.yaml')

# Initialize cleaner
cleaner = BrowserCleaner(config)

# Clean all browsers
results = cleaner.clean_all()

# Clean specific browser
results = cleaner.clean_browser('chrome')

Advanced Retention Rules

from auto_browser_cleaner.retention import RetentionPolicy, Rule

# Create retention policy
policy = RetentionPolicy(default_days=30)

# Add custom rules
policy.add_rule(Rule(domain='*.work.com', days=90))
policy.add_rule(Rule(domain='temp-*.com', days=1))
policy.add_rule(Rule(domain='important.org', days=365))

# Apply policy
cleaner = BrowserCleaner(config, retention_policy=policy)
results = cleaner.clean_all()

Scheduled Cleaning

from auto_browser_cleaner.scheduler import Scheduler

# Create scheduler
scheduler = Scheduler(config)

# Add cleaning job (daily at 2 AM)
scheduler.add_job('0 2 * * *', cleaner.clean_all)

# Start scheduler
scheduler.start()

Web Dashboard

Access the web dashboard at http://localhost:8080 to:

• Monitor cleaning statistics
• Configure retention policies
• Schedule cleaning jobs
• View cleaning history
• Manage backups

Docker Deployment

# docker-compose.yml
version: '3.8'
services:
  auto-browser-cleaner:
    image: auto-browser-cleaner:latest
    ports:
      - "8080:8080"
    volumes:
      - ./config.yaml:/app/config.yaml
      - ./logs:/app/logs
      - ./backups:/app/backups
      - ~/.config:/root/.config  # For Chrome data
      - ~/.mozilla:/root/.mozilla  # For Firefox data
    environment:
      - CONFIG_FILE=/app/config.yaml
    restart: unless-stopped

API Usage

The web interface provides a REST API:

# Get cleaning statistics
curl http://localhost:8080/api/stats

# Trigger cleaning
curl -X POST http://localhost:8080/api/clean

# Get cleaning history
curl http://localhost:8080/api/history

# Update configuration
curl -X PUT http://localhost:8080/api/config \
  -H "Content-Type: application/json" \
  -d '{"retention": {"default_days": 60}}'

Browser Support

Browser	Platform	Status	Notes
Chrome	Linux, macOS, Windows	✅ Full	History, cache, cookies
Firefox	Linux, macOS, Windows	✅ Full	History, cache, cookies
Safari	macOS	⚠️ Limited	History only (macOS restrictions)

Configuration Options

See config.example.yaml for all available options.

Key Settings

• retention.default_days: Default retention period
• schedule.cron: Cron expression for automated cleaning
• backup.enabled: Enable/disable backup before cleaning
• notifications.email: Email notifications configuration
• web.enabled: Enable web dashboard

Security Considerations

• Backup: Always enable backups before cleaning
• Authentication: Use web authentication in production
• Permissions: Ensure appropriate file system permissions
• HTTPS: Use HTTPS for web dashboard in production
• Secrets: Store sensitive configuration in environment variables

Troubleshooting

Common Issues

1. Permission denied: Ensure the application has read/write access to browser data directories
2. Browser not detected: Check browser installation paths in configuration
3. Schedule not running: Verify cron syntax and system permissions
4. Web dashboard not accessible: Check firewall settings and port availability

Debug Mode

# Enable debug logging
auto-browser-cleaner clean --log-level DEBUG

# Run with verbose output
auto-browser-cleaner clean --verbose

See docs/TROUBLESHOOTING.md for detailed troubleshooting guide.

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests
5. Submit a pull request

Documentation

• Installation Guide
• API Reference
• Usage Examples
• Deployment Guide
• Troubleshooting

License

MIT License - see LICENSE file for details.

Support

• GitHub Issues: Report bugs and feature requests
• Documentation: Comprehensive guides and examples
• Community: Join discussions and get help

---

⚠️ Important: This tool modifies browser data. Always test with backups enabled and review retention policies carefully before production use.