FileFlow

FileFlow is a terminal-based file organizer with search, analytics, duplicate detection, history tracking, and optional AI-assisted commands.

What you get after installation

After installing FileFlow correctly, you can start it from any terminal with:

fileflow

You can also run it with:

python -m fileflow

Interface Overview

The screenshots below show the main sections of FileFlow and what you can do in each one.

Dashboard

The Dashboard is the main overview screen of FileFlow.

What you can do here:

• View the total number of managed files
• Check the total storage currently used by organized files
• See which AI provider is currently active
• Review recent activity logs from recent file operations

Use this section when you want a quick summary of system status before organizing, searching, or changing settings.

Organize

The Organize screen is where manual sorting happens.

What you can do here:

• Enter a source folder path
• Enter a destination folder path
• Run a normal organization process
• Run a dry run to preview file moves without changing anything
• Cancel a running organization job
• Watch progress updates and operation logs

Use this section when you want to sort files into categories such as Documents, Images, Videos, Audio, Archives, Code, and more.

Search

The Search screen helps you find files quickly.

What you can do here:

• Search by filename text
• Filter by file extension such as .pdf, .png, or .py
• Filter by time ranges like last 24 hours, 7 days, or 30 days
• Search file contents for smaller text-based files
• Search only configured folders or broaden the search scope
• Copy a selected file path directly from the results
• Open the folder containing the selected file

Use this section when you want to locate files after they have been organized or when you want to search across your configured directories.

AI Assistant


The AI Assistant screen gives you a chat-based workflow for file operations.

What you can do here:

• Type natural language requests such as moving files or creating folders
• Ask the assistant to search for files
• Use AI-generated command responses to trigger supported actions
• Review the conversation and AI output inside the in-app chat log

Use this section when you want a more natural way to control the app instead of manually performing each action.

AI Model Selection


This screenshot shows the AI provider configuration area available through settings.

What you can do here:

• Choose the active AI provider
• Switch between Claude, OpenAI, and Ollama
• Enter the required API key for Claude
• Enter the required API key for OpenAI
• Configure the Ollama base URL for local model usage

Use this section when you want to control which language model powers the AI Assistant.

Analytics

The Analytics screen gives you storage and duplicate insights.

What you can do here:

• View total storage used in the destination folder
• See how many files are older than 90 days
• Review usage by category
• Scan the destination folder for duplicate files
• Select duplicate files for deletion
• Remove selected duplicates from inside the app

Use this section when you want to clean up storage, understand file distribution, and reduce wasted space.

History

The History screen tracks recent organization batches.

What you can do here:

• Review recent file move operations
• See batch number, file name, file size, and operation time
• Undo the most recent organization batch
• Clear stored history from the interface

Use this section when you want a safety net after organizing files.

Settings

The Settings screen controls folders, AI configuration, and automation.

What you can do here:

• Set the source folder
• Set the destination folder
• Enable or disable real-time monitoring
• Configure AI provider credentials
• Save changes
• Reset settings back to defaults

Use this section before using the rest of the application so FileFlow knows where to read files from and where to move them.

Exit

FileFlow can be closed from the terminal interface using keyboard shortcuts.

What you can do here:

• Exit the application cleanly
• Use the built-in keyboard shortcuts while working in the TUI

Important shortcuts:

• Ctrl+Q closes FileFlow
• Ctrl+O switches to the organize screen and starts organization
• Esc cancels an active organization process
• 1 to 7 switches between the main screens

Requirements

• Python 3.10 or newer
• pip available in terminal
• pipx recommended for global CLI-style installation

Install pipx first

If pipx is not installed yet:

python -m pip install --user pipx
python -m pipx ensurepath

After running ensurepath, close and reopen your terminal.

Check that pipx is available:

pipx --version

Installation methods

1. Recommended: install locally with pipx

If you already have the project folder on your machine:

cd P:\Projects\FileFlow
pipx install .

Run the app:

fileflow

Fallback:

python -m fileflow

Verify where the command is installed:

where fileflow
pipx list

2. Install locally with pip

This installs FileFlow into the current Python environment:

cd P:\Projects\FileFlow
python -m pip install .

Run the app:

fileflow

Fallback:

python -m fileflow

Note: pipx is preferred for CLI apps because it exposes the command globally in a cleaner way.

3. Install directly from a Git repository

Once this project is pushed to GitHub or another Git host, users can install it without manually downloading the folder.

Using pipx:

pipx install git+https://github.com/YOUR_USERNAME/FileFlow.git

Using pip:

python -m pip install git+https://github.com/YOUR_USERNAME/FileFlow.git

Then run:

fileflow

Fallback:

python -m fileflow

4. Install from PyPI

If FileFlow is published to PyPI in the future, installation becomes:

pipx install fileflow

or:

python -m pip install fileflow

Then run:

fileflow

Fallback:

python -m fileflow

Development run

If you want to run it directly from source without installing:

cd P:\Projects\FileFlow
python main.py

This also works:

cd P:\Projects\FileFlow
python -m fileflow

Upgrade commands

If installed with pipx from a local folder:

cd P:\Projects\FileFlow
pipx reinstall .

If installed with pipx from Git:

pipx upgrade fileflow

If installed with pip:

cd P:\Projects\FileFlow
python -m pip install . --upgrade

Uninstall commands

If installed with pipx:

pipx uninstall fileflow

If installed with pip:

python -m pip uninstall fileflow

Useful verification commands

Check Python:

python --version

Check pip:

python -m pip --version

Check pipx:

pipx --version

Check whether the command is available:

where fileflow

Check installed pipx apps:

pipx list

Features

• Organize files by extension-based categories
• Real-time monitoring with watchdog
• AI assistant with Claude, OpenAI, or Ollama providers
• Search with extension, date, and content filters
• Undo history for recent organize operations
• Storage analytics and duplicate detection

Troubleshooting

fileflow command not found

Try:

pipx ensurepath

Then restart the terminal and run:

where fileflow

pipx command not found

Install it with:

python -m pip install --user pipx
python -m pipx ensurepath

Dependencies not installing correctly

Upgrade pip first:

python -m pip install --upgrade pip

Then retry the install command.

Thank You

Thank you for using FileFlow.

FileFlow is designed to make terminal-based file management simpler, faster, and more structured through organization, search, analytics, and AI-assisted workflows.

If you are using, testing, or improving this project, your time and feedback are appreciated. Clear setup, reliable behavior, and practical usability are the priorities of this project.

For the best experience, keep the application updated, review your folder settings before running large organize jobs, and use dry runs whenever you want to preview changes safely.