File Organizer Agent

Agent YAML

# file-organizer.yaml
name: file-organizer
description: "Categorizes and moves files into organized folders"

llm:
  model: gpt-4o-mini
  temperature: 0

system_prompt: |
  You are a file organization expert. Given a file's name, size, type,
  and a preview of its content, determine:
  1. category: one of [documents, invoices, images, videos, code, data, archives, misc]
  2. subcategory: more specific label (e.g., "tax-returns", "product-photos", "python-scripts")
  3. suggested_name: a clean filename in kebab-case (keep extension)
  4. destination: path relative to ~/Organized/ (e.g., "documents/invoices/2025/")
  5. confidence: 0.0-1.0
  
  Return JSON only.

tools:
  - list_directory
  - read_file_preview   # Reads first 500 chars of text files, EXIF for images
  - move_file           # Only executes when --dry-run is NOT set

approval_required: []   # Remove this line to require human approval for each move

Pipeline

# organize-pipeline.yaml
name: organize-downloads
steps:
  - id: scan
    tool: list_directory
    params:
      path: "{{ input.source_dir | default('~/Downloads') }}"
      recursive: false
      exclude: ["*.tmp", "*.part"]
    
  - id: analyze_each
    type: for_each
    iterate_over: "{{ scan.files }}"
    as: file
    step:
      agent: file-organizer
      input:
        name: "{{ file.name }}"
        size_kb: "{{ file.size_kb }}"
        extension: "{{ file.extension }}"
    collect_as: analysis
    
  - id: move_high_confidence
    type: for_each
    iterate_over: "{{ analysis | selectattr('confidence', 'ge', 0.75) }}"
    as: item
    step:
      tool: move_file
      params:
        source: "{{ input.source_dir }}/{{ item.original_name }}"
        destination: "{{ input.dest_dir | default('~/Organized') }}/{{ item.destination }}/{{ item.suggested_name }}"
        create_dirs: true
    
  - id: report
    tool: file_write
    params:
      path: ./organization-report.md
      content: |
        # File Organization Report
        Processed: {{ analysis | length }} files
        Moved: {{ analysis | selectattr('confidence', 'ge', 0.75) | list | length }} files
        Skipped (low confidence): {{ analysis | selectattr('confidence', 'lt', 0.75) | list | length }} files
        
        ## Skipped Files (Review Manually)
        {% for item in analysis | selectattr('confidence', 'lt', 0.75) %}
        - {{ item.original_name }} ({{ "%.0f%%" | format(item.confidence * 100) }} confidence)
        {% endfor %}

Running the Agent

# Dry run first — see what WOULD happen
openclaw pipeline run organize-pipeline.yaml \
  --input '{"source_dir": "~/Downloads"}' \
  --dry-run

# Review the report, then run for real
openclaw pipeline run organize-pipeline.yaml \
  --input '{"source_dir": "~/Downloads", "dest_dir": "~/Organized"}'

What This Agent Does

This tutorial builds a file organization agent that can analyze a directory full of files and organize them into a logical structure. The agent reads file names, examines content samples, infers categories, and produces either a reorganization plan for review or performs the moves directly. This is useful for cleaning up a messy downloads folder, organizing project assets, or restructuring legacy documentation.

Step 1 — Agent Configuration

Create file-organizer.yaml:

agent:
  name: file-organizer
  description: Analyzes and organizes files into logical structures
  system_prompt: |
    You are a meticulous file organization assistant. When given a
    directory to organize, you:
    1. List all files and examine names, extensions, and dates
    2. Sample a small portion of each file's content to understand it
    3. Devise a logical category hierarchy (max 3 levels deep)
    4. Produce a reorganization plan with: current path → suggested path
    5. Always ask for confirmation before moving files unless told to proceed

    Organization principles:
    - Group by purpose first, then by date or project
    - Keep related files together (e.g., a document and its attachments)
    - Use lowercase-kebab-case for directory names
    - Never delete files — move them to an archive/ directory if purpose unclear

llm:
  model: claude-3-5-sonnet-20241022
  temperature: 0.2
  max_tokens: 4096

tools:
  - name: file_list
    enabled: true
  - name: file_read
    enabled: true
    config:
      max_file_size: 10240   # 10KB preview only
  - name: file_move
    enabled: true
    config:
      allowed_dirs:
        - ./target-directory
      require_confirmation: true

Step 2 — Generate an Organization Plan

openclaw run --config file-organizer.yaml   --task "Analyze the files in ./downloads. Create a proposed directory structure
  and show me a plan: for each file, show where you'd move it and why.
  Do NOT move anything yet — just show the plan."

Review the plan before proceeding. The agent's reasoning is transparent — you'll see exactly why it categorized each file as it did, and you can correct any mistakes before any files are moved.

Step 3 — Execute the Organization

Once the plan looks right, approve the execution:

openclaw run --config file-organizer.yaml   --task "Implement the organization plan you previously created for ./downloads.
  Create all necessary directories. Move each file to its planned location.
  After moving, verify the file exists at the new path. Report any errors."

Step 4 — Organize Project Documentation

For technical documentation, provide domain-specific instructions:

openclaw run --config file-organizer.yaml   --task "Organize ./project-docs into a structure suitable for a software project.
  Expected categories: architecture/, api/, user-guides/, deployment/, decisions/.
  Place ADRs (Architecture Decision Records) in decisions/.
  Place anything that looks like an API spec or swagger in api/.
  Group related documents even if they have different formats (e.g., a diagram
  and the spec it illustrates should be in the same directory)."

Step 5 — Automated Maintenance

Set up ongoing organization for directories that accumulate new files regularly, such as a downloads folder or an email attachment dump. Schedule the agent weekly to review new files and move them to appropriate locations based on your established structure. After the first full organization run, subsequent runs only need to process new files — add "focus only on files created in the last 7 days" to the task for efficient incremental maintenance.

Troubleshooting

If the agent misclassifies domain-specific files, add examples to the system prompt: "Files ending in .iac are infrastructure-as-code configs — put them in infrastructure/." If the agent tries to read large binary files (videos, executables) and hits size limits, add to file_read config: skip_binary: true. If you want to preview moves without any filesystem changes, set dry_run: true in the file_move config.

Domain-Specific Organization Rules

Generic file organization produces generic results. For the best outcomes, teach the agent domain-specific conventions by adding them to the system prompt. For a software project: place test files adjacent to the code they test, keep database migrations in chronological order, group feature flags with their corresponding feature code. For a media production project: organize by project, then deliverable type, then revision number. For financial documents: organize by fiscal year, then document type, then entity name. The more specific your conventions, the more useful the organization output.

Create an organization conventions file (conventions.md) that documents your project's file organization rules in plain language. Have the agent read this file at the start of any organization task: "Read conventions.md and apply these rules when organizing files." This externalizes the rules from the system prompt, making them easier to maintain and update, and lets different team members understand why files were organized as they were.

Dealing with Ambiguous Files

Files without descriptive names (like final_v2_FINAL.docx or scan0042.pdf) are the hardest to categorize. Configure the agent to handle these gracefully: "When a file's destination cannot be determined from its name alone, read the first 2000 characters of its content and use that to classify it. If still unclear after reading, place it in an _needs-review/ directory and add a line to a review-report.txt explaining what's unclear." This keeps the automated process moving while flagging the genuinely ambiguous cases for human decision.

Post-Organization Verification

After a major organization run, have the agent verify its work: "List all files that were moved and confirm each exists at its new path. Report any that are missing." Also verify that no files were lost by comparing original file count to final file count. A simple Python script can check this: count files before the agent runs, then verify the count matches afterward. File count verification is your last line of defense against accidental data loss during organization operations.

Combining with Version Control

For codebases or document repositories managed in Git, run the file organizer in proposal mode before executing any moves, then apply the moves as a Git commit with a clear message describing the reorganization. This creates a clean, auditable history of the structural change. Reviewers can see exactly what moved where in the pull request diff, and the move is reversible with a simple git revert if the organization turns out to be wrong. Always perform a reorganization as its own isolated commit — mixing structural moves with content changes in the same commit makes both harder to review and harder to revert.