File Organizer
Agent

Build an AI agent that cleans up your messy Downloads folder -- sorts files by type, date, and project automatically. Built with OpenCode in under 15 minutes.

Start Building Setup Guide First
Need to set up OpenCode first?

This guide assumes you have OpenCode and a free model provider configured. If you haven't set that up yet:

  1. Install OpenCode: curl -fsSL https://opencode.ai/install | bash
  2. Get a free API key from OpenRouter (no credit card needed)
  3. Or follow the full setup guide for detailed steps

What You'll Build

By the end of this guide, you'll have a command-line file organizer agent that can:

  • Scan a folder and identify every file inside it
  • Categorize files by type -- images, documents, videos, music, code, archives, and other
  • Create subfolders for each category automatically
  • Move files into the right subfolder based on their extension
  • Print a summary showing exactly what was moved and where

No more manually sorting through hundreds of random files. You describe what you want, OpenCode writes the code, you run it and refine.

1

Create Your Project

Set up a project folder with an AGENTS.md file that tells OpenCode what kind of project this is.

mkdir -p ~/projects/file-organizer
cd ~/projects/file-organizer
mkdir -p ~/projects/file-organizer
cd ~/projects/file-organizer

Now create an AGENTS.md file. This is the context file that OpenCode reads to understand your project:

# File Organizer Agent

## Project Type
Python CLI application

## Description
A command-line tool that scans a target folder (like ~/Downloads),
categorizes every file by its type, creates organized subfolders,
and moves each file into the correct category folder.

## Tech Stack
- Python 3.8+ (standard library only, no external deps)
- pathlib for file operations
- argparse for CLI arguments

## File Categories
- Images: .jpg, .jpeg, .png, .gif, .svg, .webp, .bmp, .ico, .tiff
- Documents: .pdf, .doc, .docx, .txt, .rtf, .odt, .xls, .xlsx, .csv, .pptx
- Videos: .mp4, .mov, .avi, .mkv, .wmv, .flv, .webm
- Music: .mp3, .wav, .flac, .aac, .ogg, .wma, .m4a
- Code: .py, .js, .ts, .html, .css, .json, .xml, .yaml, .yml, .sh, .go, .rs
- Archives: .zip, .tar, .gz, .rar, .7z, .bz2, .xz
- Other: everything else

## Conventions
- Use type hints
- Keep it in a single file for simplicity
- Never move directories, only files
- Print a clear summary table after organizing

Save this as AGENTS.md in your project folder. You can create it manually or use OpenCode:

opencode
Why AGENTS.md?
OpenCode reads this file automatically when you start it in the project directory. It gives the AI context about your project's purpose, tech stack, and conventions -- so every response is more relevant and accurate.
2

Give OpenCode the Task

With OpenCode running in your project folder, give it the task. One prompt builds the whole thing.

Type this into OpenCode:

Create a Python script called organize.py that organizes files
in my Downloads folder. It should:

1. Accept a folder path as a command-line argument
2. Scan all files in that folder (not subdirectories)
3. Categorize them by type (images, documents, videos, music,
   code, archives, other)
4. Create subfolders for each category that has files
5. Move files into the right subfolder
6. Print a summary of what was moved, grouped by category,
   with a total count at the end

OpenCode will generate a complete Python script. You'll see it write the file in real time. When it's done, you'll have a working organize.py in your project folder.

What OpenCode Generates

The output will typically include:

  • A FILE_CATEGORIES dictionary mapping category names to file extensions
  • A categorize_file() function that determines which category a file belongs to
  • A organize_folder() function that handles the scanning, folder creation, and moving
  • An argparse setup so you can pass the target folder as an argument
  • A formatted summary table printed to the terminal after completion
3

Run It and Iterate

Test your agent and ask OpenCode to improve it based on what you find.

Safety first: test on a copy!
Don't run this on your real Downloads folder the first time. Copy a handful of files into a test folder and run it there. Once you're happy with the results, point it at the real thing.

Create a test folder and run your organizer:

# Create a test folder with some sample files
mkdir -p ~/test-downloads
touch ~/test-downloads/photo.jpg
touch ~/test-downloads/report.pdf
touch ~/test-downloads/song.mp3
touch ~/test-downloads/backup.zip
touch ~/test-downloads/notes.txt
touch ~/test-downloads/app.py

# Run the organizer
python3 organize.py ~/test-downloads
# Create a test folder with some sample files
mkdir -p ~/test-downloads
touch ~/test-downloads/photo.jpg
touch ~/test-downloads/report.pdf
touch ~/test-downloads/song.mp3
touch ~/test-downloads/backup.zip
touch ~/test-downloads/notes.txt
touch ~/test-downloads/app.py

# Run the organizer
python3 organize.py ~/test-downloads

You should see a summary like this:

=======================================
  File Organizer - Summary
=======================================

Images (1 file):
  photo.jpg -> Images/photo.jpg

Documents (2 files):
  report.pdf -> Documents/report.pdf
  notes.txt  -> Documents/notes.txt

Music (1 file):
  song.mp3 -> Music/song.mp3

Code (1 file):
  app.py -> Code/app.py

Archives (1 file):
  backup.zip -> Archives/backup.zip

---------------------------------------
Total: 6 files organized into 5 folders

Once you've verified it works on the test folder, run it on your real Downloads:

python3 organize.py ~/Downloads

Iterate with OpenCode

Found something you want to change? Go back to OpenCode and ask. The AI remembers your project context from AGENTS.md.

# Example iteration prompts:
The script works but I want it to skip hidden files (dotfiles).
Also add a --verbose flag that shows each file as it's being moved.

Handle duplicate filenames -- if Images/photo.jpg already exists,
rename it to Images/photo_1.jpg instead of overwriting.
Version control tip
Initialize a git repo with git init and commit after each working version. Store it on GitHub for free. That way you can always roll back if an iteration breaks something.

Example Prompts to Try

Once your basic file organizer works, try these prompts to extend it. Start with the simple ones and work your way up:

# Dry run mode
Add a --dry-run flag that shows what WOULD be moved without
actually moving anything. Print the same summary but with
"[DRY RUN]" in the header.
# Sort by date
Sort files by date too -- create year/month subfolders inside
each category. So an image from March 2025 goes to
Images/2025/03/photo.jpg instead of just Images/photo.jpg.
# Activity log
Add a log file that records everything that was moved and when.
Save it as organize_log.txt in the target folder. Each line
should have a timestamp, the original path, and the new path.
# Skip recent files
Skip files that were modified in the last 24 hours. I don't want
to organize files I'm still actively working on. Add a --skip-recent
flag that accepts a number of hours (default 24).

Each prompt builds on the existing code. OpenCode reads the current state of organize.py and modifies it in place.

What's Next?

You've built a working file organizer agent. Here's where to go from here:

  • Automate it: Set up a cron job (Linux/Mac) to run the organizer on your Downloads folder every day. No more manual cleanup.
  • Make it smarter: Ask OpenCode to add content-based detection -- read PDF titles, check image dimensions, or parse code file headers for better categorization.
  • Try another agent: The setup is the same -- only the task changes. Pick your next project:

Ready for the Next Agent?

The pattern is always the same: create a folder, write AGENTS.md, give OpenCode the task. The only thing that changes is the prompt.

Build Shopping Agent All Guides