AI-Powered Desktop File Organizer
Drop files on your Desktop. File Clerk reads them, tags them, and files them
into organized folders. Search them later by description, not filename.
The problem: You save a file, give it some name, toss it somewhere. Six months later you know you built it but can't find it. You've been doing this for decades.
The fix: Let AI read your files, understand what they are, and organize them into a searchable index. You drop files on your Desktop. Every morning, File Clerk wakes up, reads each new file, files it into a logical folder, and indexes it with tags and a summary. When you need something later, just describe it.
Before: 12 files on your Desktop with names like Plain Text.txt, Screenshot_2025-08-05_17-23-17.png, and FOCUS MUSIC.
After: Clean Desktop. In your Documents folder:
Documents/
├── Business/
│ ├── Consulting-Strategy/AI-Consulting-Strategy-2026.txt
│ └── Market-Analysis/competitive-landscape.png
├── Credentials/
│ └── Remote-Access/VPN-Server-Credentials.txt
├── System/
│ └── Troubleshooting/GPU-Driver-Fix-2026-01-29.txt
└── Reference/
└── Focus-Music-Playlists.txt
Search: ./find.sh "that GPU driver fix" — found instantly.
- Python 3.8+ with tkinter (for the GUI; optional)
- Claude Code CLI — install guide
# Install Claude Code (requires Node.js)
npm install -g @anthropic-ai/claude-code
# On Ubuntu/Debian, install tkinter if needed
sudo apt install python3-tkgit clone https://github.com/spanklitch/file-clerk.git
cd file-clerk
./install.shThe installer will walk you through setup:
- Checks that Python and Claude Code are available
- Asks where your inbox is (default:
~/Desktop) - Asks where organized files should go (default:
~/Documents) - Creates category folders (without touching existing files)
- Sets up the search index
- Optionally installs a daily cron job (7 AM)
- Optionally creates a desktop shortcut for the GUI
┌─────────────┐ 7 AM cron ┌───────────┐
│ Desktop │ ──────────────────> │ clerk.sh │
│ (inbox) │ │ │
└─────────────┘ └─────┬─────┘
│
v
┌────────────────┐
│ Claude Code │
│ (headless) │
│ confined tools│
└───────┬────────┘
│
┌──────────────┼──────────────┐
v v v
┌──────────┐ ┌──────────────┐ ┌─────────┐
│ Move to │ │ SQLite Index │ │ Log │
│ Docs/ │ │ (FTS5) │ │ results │
└──────────┘ └──────┬───────┘ └─────────┘
│
┌────────────────────┤
v v
┌────────────┐ ┌────────────────┐
│ find.sh │ │ File Finder │
│ (AI search)│ │ (GUI search) │
└────────────┘ └────────────────┘
- You drop a file on your Desktop (or configured inbox)
- clerk.sh runs at 7 AM via cron (or manually)
- Claude Code reads each new file in headless mode with confined tool access:
- Understands the file's content
- Chooses (or creates) an appropriate folder
- Renames the file with a descriptive name
- Adds it to the SQLite index with tags and a summary
- You search later using either:
- GUI: File Finder app (instant local search, no AI cost)
- CLI + AI:
./find.sh "description"(uses Claude to search intelligently) - CLI direct:
python3 index-manager.py search "keywords"(instant, free)
Claude Code runs with confined tool access — it can only:
- Read files (
Read,Glob,Grep) - Move files (
Bash(mv),Bash(mkdir)) - Query file metadata (
Bash(ls),Bash(file)) - Update the index (
Bash(python3))
It cannot install packages, run arbitrary code, access the network, or modify file contents. It can only move and rename.
Files dropped on your Desktop are organized every morning at 7 AM. Check the logs:
cat ~/file-clerk/logs/$(date +%F).log# Organize inbox right now
./clerk.sh
# Search with AI
./find.sh "that document about market analysis"
# Search instantly (no AI, queries local index)
python3 index-manager.py search "market analysis"
# Launch GUI
python3 file-finder-gui.py
- Type in the search box — results filter live as you type
- Click a result to see its full path, summary, and tags
- Double-click to open the file
- "Open Folder" button opens the containing directory
After installation, edit config.env to change paths:
CLERK_HOME="/home/you/file-clerk" # Where file-clerk lives
INBOX_DIR="/home/you/Desktop" # Where new files appear
DOCS_DIR="/home/you/Documents" # Where organized files go
CLAUDE_CMD="/home/you/.local/bin/claude" # Path to Claude CLI
DB_PATH="/home/you/file-clerk/index.sqlite" # Search indexcrontab -e
# Edit the "0 7 * * *" part. Examples:
# 0 7 * * * = 7:00 AM daily
# 0 7 * * 1-5 = 7:00 AM weekdays
# */30 * * * * = Every 30 minutesEdit prompt-filer.md to change the folder categories or filing strategy. The AI follows these instructions when deciding where to put files.
By default, .desktop launcher files are ignored. Edit the clerk.sh find command to change the exclusion pattern.
Documents/
├── Credentials/ # Passwords, API keys, access info
│ ├── Remote-Access/
│ └── Service-Keys/
├── Projects/ # Project-specific docs and notes
├── Business/ # Strategy, presentations, research
├── System/ # Configs, troubleshooting, scripts
│ ├── Troubleshooting/
│ └── Backup-Scripts/
├── Reference/ # Bookmarks, playlists, how-to guides
└── Archive/ # Old data, deprecated stuff
The AI will create new categories as needed. These are starting points.
./uninstall.shThis removes the cron job and desktop launcher. Your organized files are never deleted. You choose whether to keep or delete the search index and configuration.
| Feature | Linux | macOS |
|---|---|---|
| Automatic filing (cron) | Yes | Yes |
| AI search (find.sh) | Yes | Yes |
| GUI search (File Finder) | Yes | Yes |
| Desktop launcher | Yes | Manual (Automator) |
| Default directory detection | XDG + fallback | $HOME fallback |
- Python 3.8+ (with
sqlite3module — included by default) tkinterfor the GUI (optional —sudo apt install python3-tkon Debian/Ubuntu)- Claude Code CLI for automatic filing and AI search
cronfor scheduled runs (included on Linux and macOS)
MIT — see LICENSE