explaingit

echoyu1025-a11y/file-butler

Analysis updated 2026-05-18

21C++Audience · generalComplexity · 2/5LicenseSetup · easy

TLDR

File Butler is a desktop app that uses local or cloud AI to suggest file organization and flag junk, duplicate, and large files, without ever deleting anything itself.

Mindmap

mindmap
  root((File Butler))
    What it does
      AI file organizing
      Read-only cleanup scan
      Duplicate detection
      Undo support
    Tech stack
      C plus plus
      Qt
      SQLite
      Local LLM
    Use cases
      Tidy messy folders
      Find duplicate files
      Offline privacy
    Audience
      Everyday computer users

Code map

Detail Auto

An interactive map of this repo's files and how they connect — its source is parsed live in your browser. Click Visualize to build it.

filefunction / class

What do people build with it?

USE CASE 1

Let an AI read the contents of files in a messy folder and suggest a clean category structure.

USE CASE 2

Scan a folder to find duplicate files, junk files, and oversized files worth deleting manually.

USE CASE 3

Run entirely offline with a local AI model to keep personal files private.

What is it built with?

C++QtSQLitellama.cpp

How does it compare?

echoyu1025-a11y/file-butlerjdduke/fpcpplagerpun/esp32-cyd-aquarium
Stars212121
LanguageC++C++C++
Last pushed2012-06-01
MaintenanceDormant
Setup difficultyeasyeasymoderate
Complexity2/52/52/5
Audiencegeneraldeveloperdeveloper

Figures from each repo's GitHub metadata at analysis time.

How do you get it running?

Difficulty · easy Time to first run · 5min

Prebuilt installers for macOS and Windows are unsigned, so first launch needs a security bypass step.

Based on AGPL-3.0, which requires sharing source code of modified versions, including when run as a network service.

In plain English

File Butler is a desktop app for macOS and Windows that uses AI to help clean up a messy folder. It is a customized version of an open source project called AI File Sorter, and it can run entirely offline if you use a local AI model. It has two main features. The first is file organizing: you point it at a folder, and the AI reads the actual contents of each file, not just the file name, then suggests a category and a clearer file name for it. You can preview every suggested change before anything happens, run it in a dry-run mode that only shows results without touching files, and undo changes afterward. By default it only creates one level of category folders so things do not get scattered into too many small folders. The second feature is file cleanup, which scans a folder and reports four kinds of files that are probably safe to remove: junk or cache files like temporary and log files, duplicate files found by comparing file content rather than just names, large files over 100 megabytes, and empty folders or zero-byte files. The app is careful to only report and locate these files. It never deletes or moves anything on its own, and instead lets you click through to the file's location and decide for yourself. For the AI step, you can either download a local language model such as Gemma 3 4B, which keeps everything private and free, or connect a cloud service like ChatGPT or Gemini using your own API key. The interface supports fifteen languages and defaults to Simplified Chinese in this fork. This project is aimed at everyday computer users who want an AI assisted way to tidy up cluttered folders without giving up control over what actually gets deleted.

Copy-paste prompts

Prompt 1
Walk me through installing File Butler on macOS and setting up a local AI model.
Prompt 2
Explain the difference between the file organizing and file cleanup features in File Butler.
Prompt 3
How do I connect File Butler to the ChatGPT API instead of using a local model?
Prompt 4
Show me the build steps for compiling File Butler from source on macOS.

Frequently asked questions

What is file-butler?

File Butler is a desktop app that uses local or cloud AI to suggest file organization and flag junk, duplicate, and large files, without ever deleting anything itself.

What language is file-butler written in?

Mainly C++. The stack also includes C++, Qt, SQLite.

What license does file-butler use?

Based on AGPL-3.0, which requires sharing source code of modified versions, including when run as a network service.

How hard is file-butler to set up?

Setup difficulty is rated easy, with roughly 5min to a first successful run.

Who is file-butler for?

Mainly general.

Open on GitHub → Explain another repo

This repo across BitVibe Labs

Verify against the repo before relying on details.