Folder Organizer - Upsonic AI

An autonomous agent that semantically reorganizes any messy folder into a clean, navigable structure. Drop your files into workspace/unorganized_folder/, run the agent, and get a logically grouped hierarchy back. No hardcoded sorting rules — the agent reads the folder_organization skill and reasons about what goes where based on file names, types, and context.

Overview

The setup has two parts:

AutonomousAgent with a workspace directory
Workspace files (AGENTS.md, skills/folder_organization/SKILL.md) that define how the agent classifies and moves files

The agent has no custom tools and no hardcoded logic. It reads the skill, surveys the folder with tree, plans a structure, moves files, and writes a log — entirely on its own.

Project Structure

folder_organizer/
├── main.py                              # Agent setup and task
├── requirements.txt                     # Python dependencies
├── .env.example                         # Template for .env
│
└── workspace/
    ├── AGENTS.md                        # Agent behavior and skill index
    ├── unorganized_folder/              # Drop your messy files here
    │   └── REORGANIZATION_LOG.md        # Created after the agent runs
    └── skills/
        └── folder_organization/
            └── SKILL.md                 # How the agent categorizes files

Environment Variables

ANTHROPIC_API_KEY=your-api-key

Installation

cd examples/autonomous_agents/folder_organizer
uv venv && source .venv/bin/activate
uv pip install -r requirements.txt

Usage

Drop your files into workspace/unorganized_folder/
Run the agent:

uv run main.py

The agent surveys the folder, classifies each file semantically, moves them into a structured hierarchy, and writes a log.

How It Works

Step	What happens
Survey	Agent runs `tree` on the target folder to map all files
Classify	Groups files by semantic category using name, extension, and context
Move	Executes all moves into the new structure
Log	Writes `REORGANIZATION_LOG.md` with every `original path → new path` move

The agent never deletes files — only moves them. Duplicates are kept together, not resolved.

Complete Implementation

main.py

import os
from dotenv import load_dotenv
from upsonic import AutonomousAgent, Task

load_dotenv()

agent = AutonomousAgent(
    model="anthropic/claude-sonnet-4-6",
    workspace=os.path.join(os.path.dirname(__file__), "workspace"),
)

classification_task = Task("Organize the unorganized_folder.")

if __name__ == "__main__":
    agent.print_do(classification_task)

One task, one line. No custom tools, no system prompt, no sorting logic in code.

Workspace: SKILL.md

The agent’s behavior is fully defined in workspace/skills/folder_organization/SKILL.md. It specifies:

Categories: photos/, videos/, audio/, documents/official/, design/, code/<project>/, archives/, projects/<name>/
Classification rules: infer purpose from name, extension, and folder context
Move rules: never delete, keep related files together, prefer semantic names
Log format: every move recorded as original path → new path

Change the skill file to change the agent’s behavior — no code changes needed.

Example output structure

unorganized_folder/
├── photos/
│   ├── IMG_4665.JPEG
│   └── YDXJ0387.JPG
├── videos/
│   ├── raw/
│   │   └── YDXJ0406.MP4
│   └── edited/
│       └── part_3_edited.mov
├── audio/
│   └── track.wav
├── documents/
│   ├── official/
│   │   └── invoice.pdf
│   └── notes.docx
├── design/
│   └── logo.svg
├── code/
│   └── queue-api/
│       └── push_call_into_queue.py
├── archives/
│   └── backup.zip
└── REORGANIZATION_LOG.md

Repository

View the full example: Folder Organizer

​Overview

​Project Structure

​Environment Variables

​Installation

​Usage

​How It Works

​Complete Implementation

​main.py

​Workspace: SKILL.md

​Example output structure

​Repository

Overview

Project Structure

Environment Variables

Installation

Usage

How It Works

Complete Implementation

main.py

Workspace: SKILL.md

Example output structure

Repository