🗂️ Agent File Organizer

An intelligent, safety-first, cross-platform file organizer for Windows, macOS, and Linux.

Organize your Downloads, Documents, Pictures, Videos, and Music folders with one command — or let your AI agent do it for you. Works with Windows File Explorer, macOS Finder, and Linux file managers (Nautilus, Dolphin, Thunar, etc.) without any plugins or special setup.

💡 No AI agent? No problem. The CLI works completely offline with no internet connection, no API keys, and no AI agent required. The intelligence is built in.

✨ What Makes It Smart

Unlike tools that blindly sort by file extension, Agent File Organizer uses content-aware heuristics:

• 📸 Smart Photos — Tells apart screenshots, camera shots (via EXIF), and scanned receipts

• 🎵 Music Hierarchy — Sorts by Artist / Album using ID3 tags or filename patterns

• 🎥 Video Classification — Separates screen recordings (OBS, Zoom) from regular videos

• 🎮 Game Mod Detection — Identifies Minecraft mod .jar files and keeps them separate from regular apps

• 🔒 Always Safe — Dry-run preview before anything moves, full undo support, no silent overwrites

Related MCP server: Organizer MCP Server

📦 Install

Via pip (works offline, no agent needed)

pip install agent-file-organizer

👉 pypi.org/project/agent-file-organizer

Via Smithery (for AI agent MCP setup)

Smithery auto-installs and configures the MCP server for your agent — no manual JSON editing needed.

# Claude Code / Claude Desktop
npx -y @smithery/cli install michaelattah80/file-organizer --client claude

# Cursor
npx -y @smithery/cli install michaelattah80/file-organizer --client cursor

# Codex
npx -y @smithery/cli install michaelattah80/file-organizer --client codex

👉 smithery.ai/server/michaelattah80/file-organizer

Via GitHub (for the Agent Skill)

git clone https://github.com/NerdBlaq/agent-file-organizer.git

Or download as ZIP — no git required.

🚀 3 Ways to Use

1. 💻 CLI — Offline, No Agent Required

After pip install agent-file-organizer, run these commands directly in your terminal:

Scan and preview (nothing moves yet):

file-organizer scan --targets ~/Downloads --output /tmp/plan.json

Apply the plan:

file-organizer apply --plan /tmp/plan.json

Undo any past run:

file-organizer undo ~/.file-organizer/logs/moves-<timestamp>.log

Verify a recovery actually completed (v1.1.2):

file-organizer verify ~/.file-organizer/logs/moves-<timestamp>.log

Checks the real filesystem state against the log — run this before trusting that an undo (or any manual recovery) actually worked, not a one-off search.

Record what happened and why (v1.1.3):

file-organizer log-session --event confirmed --confirmation "yes, reorganize the games folder too"
file-organizer show-sessions

A structured record separate from the moves log — what was asked, what mode was chosen, what the user actually said to approve an action.

Detect existing folder structure first:

file-organizer detect --targets ~/Pictures ~/Videos ~/Music

2. 🤖 Agent Skill — For AI Coding Assistants

Drop the skill into your agent and simply say "Organize my Downloads folder".

Works with any agent that supports external skills, custom rules, or runbooks (Cursor, Windsurf, Aider, Devin, GitHub Copilot, etc.).

3. ⚙️ MCP Server — For AI Desktop Apps

Connect Agent File Organizer directly to Claude Desktop, ChatGPT for Desktop, Cursor, Zed, or Windsurf via the Model Context Protocol.

Easiest way — use Smithery (see Install section above).

Or configure manually — add this to your MCP settings file (claude_desktop_config.json, Cursor MCP config, etc.):

{
  "mcpServers": {
    "file-organizer": {
      "command": "file-organizer-mcp",
      "args": []
    }
  }
}

Available MCP tools your agent can call:

🛡️ Safety Guarantees

1. Dry-run first — nothing moves until you review and confirm the plan

2. Move, never delete — duplicates are flagged for your review, never auto-deleted

3. No silent overwrites — filename collisions get a suffix: file (1).jpg, file (2).jpg

4. Full undo — every move is logged and 100% reversible

5. Skips system files — ignores .DS_Store, Thumbs.db, .git, .tmp, .crdownload, etc.

6. Remembers past runs — files already organized won't be moved again

7. Path isolation (v1.1.2) — the base directory is derived from what was actually scanned, never silently defaulted to your home folder; a move that would cross a filesystem/drive boundary aborts before touching anything unless you explicitly allow it

8. Integrity Guard (v1.1.2, extended v1.1.3) — a folder is protected either because it contains .exe/.dll/.so/.dylib/.bin/.msi anywhere in its subtree, or because its own name matches a known curated-content pattern (games, my games, shaderpacks, mc extras, etc.) — extend the list with protected_folder_names, or lock an exact path with exclude

9. No self-nesting (v1.1.3) — a file already inside a folder named e.g. "Documents" won't be filed into a "Documents/Documents" duplicate just because its bucket shares that name

10. Verified recovery (v1.1.2) — verify checks a moves log against actual current filesystem state, so "restored" is a confirmed fact, not an assumption

11. Session logging (v1.1.3) — log-session records what was asked, chosen, and confirmed, separate from the mechanical moves log, so an incident can be reconstructed by reading a file instead of a chat transcript

Items 7–11 were added directly in response to real incidents: a run with no explicit base moved files from an external drive onto the OS partition; a reorganize run flattened curated folders and, separately, tore apart game archives and save-data folders that had no detectable binaries; and a scan of a folder whose name matched its own destination bucket produced redundant nested folders. All are now structurally blocked rather than just documented against.

📄 License

Released under the MIT License.