CachyOS Scripts

A collection of utility scripts for CachyOS — automated file organization, system maintenance, and cache management.

Quick Start

git clone https://github.com/votetz/cachyos_scripts.git
cd cachyos_scripts
bash install.sh

That's it. The script sets up the virtual environment, installs dependencies, and enables the systemd service automatically.

---

Project Structure

cachyos_scripts/
├── automation/
│   ├── path_master.py      # File sorting logic
│   ├── path_watcher.py     # Filesystem watcher (systemd service)
│   └── update_cachyos.py   # System updater
├── utils/
│   ├── clear_cache.py      # Cache cleaner
│   └── file_analyzer.py    # MIME detection, hash tracking, duplicate detection
├── config.json             # Centralized configuration
├── install.sh              # One-command setup
└── requirements.txt

---

Configuration

All settings are stored in config.json at the project root — no need to edit source files.

⚠️ Important: The default configuration uses Ukrainian folder names (Завантажене, Документи, etc.). If your system uses different XDG user directory names, you must update the dirs section in config.json to match your locale.

{
    "mime_map": {
        "application/pdf": "DOCUMENTS",
        "image/jpeg": "PICTURES",
        "video/mp4": "VIDEOS",
        "application/zip": "ARCHIVES",
        ...
    },
    "dirs": {
        "DOWNLOADS": "Завантажене",
        "DOCUMENTS": "Документи",
        "PICTURES": "Зображення",
        "VIDEOS": "Відео",
        "ARCHIVES": "Архіви",
        "OTHERS": "Інші файли"
    },
    "telegram_path": "Завантажене/Telegram Desktop"
}

To change target folders or add new MIME types — just edit config.json.

---

File Autosorter

Background service that automatically organizes files in ~/Завантажене and ~/Завантажене/Telegram Desktop into categorized folders.

How it works

• path_watcher.py monitors directories for new files using watchdog
• path_master.py moves files into the correct folder based on type
• file_analyzer.py detects file type via MIME (not just extension) using python-magic
• Every moved file is hashed (SHA-256) and saved to ~/.cache/cachyos/file_hashes.json
• On next run, duplicates are detected by hash and automatically deleted before sorting
• A desktop notification is sent via libnotify each time a file is moved

Supported categories

Category	Target folder	Examples
Documents	~/Документи	.pdf, .docx, .txt
Pictures	~/Зображення	.jpg, .png, .gif, .webp
Videos	~/Відео	.mp4, .mkv, .avi
Archives	~/Архіви	.zip, .rar, .tar, .gz, .zst
Others	~/Інші файли	everything else

Collision handling is built-in — if a file with the same name already exists, it is renamed automatically (file_1.pdf, file_2.pdf, etc).

Desktop Notifications

Every time a file is moved, a desktop notification is sent:

📁 File sorted
document.pdf → Документи

Notifications are sent via notify-send (requires libnotify). To disable them, set "notifications": false in config.json.

Manual Setup

If you prefer to set things up step by step instead of using install.sh:

git clone https://github.com/votetz/cachyos_scripts.git
cd cachyos_scripts
python -m venv .venv
source .venv/bin/activate.fish  # or .bash
pip install -r requirements.txt

Systemd Service

1. Create ~/.config/systemd/user/path-watcher.service:

[Unit]
Description=CachyOS File Autosorter

[Service]
Type=simple
WorkingDirectory=%h/cachyos_scripts/
Environment=PYTHONPATH=%h/cachyos_scripts/
Environment=PYTHONUNBUFFERED=1
ExecStart=%h/cachyos_scripts/.venv/bin/python3 automation/path_watcher.py
Restart=always

[Install]
WantedBy=default.target

2. Enable:

systemctl --user daemon-reload
systemctl --user enable --now path-watcher.service

Commands

Action	Command
Status	systemctl --user status path-watcher.service
Logs	journalctl --user -u path-watcher.service -f
Restart	systemctl --user restart path-watcher.service
Stop	systemctl --user stop path-watcher.service
Disable	systemctl --user disable --now path-watcher.service

---

Cache Cleaner

Clears the pacman package cache and optionally the user cache in ~/.cache/cachyos.

python utils/clear_cache.py

• Uses paccache -rk2 to keep the 2 most recent versions of each package
• Asks for confirmation before each action
• Logs everything to ~/.cache/cachyos/logs/clear_cache.log
• Skips the logs directory when clearing user cache

---

System Updater

Runs a full system upgrade and cleans up the package cache afterwards.

sudo .venv/bin/python automation/update_cachyos.py

• Requires root (sudo)
• Runs pacman -Syu --noconfirm then paccache -rk2
• Sends a desktop notification on completion via notifypy
• Offers to reboot after update

---

Logs

All scripts write logs to ~/.cache/cachyos/logs/:

File	Script
path_master.log	File autosorter
clear_cache.log	Cache cleaner

Hash database is stored separately at ~/.cache/cachyos/file_hashes.json.

---

Requirements

watchdog
notifypy
python-magic

Install with:

pip install -r requirements.txt