file-org-wiz

An AI-powered file organization system using the PARA + Zettelkasten methodology.

A complete file organization system that provides tools to reorganize any computer's files with consistent structure, naming conventions, and documentation using the PARA (Projects, Areas, Resources, Archive) methodology combined with Zettelkasten principles.

Features

• PARA Folder Structure: Action-oriented organization by Projects, Areas, Resources, and Archive
• Deep File Scanning: Recursive analysis and intelligent categorization
• Duplicate Detection: Content hash + name similarity matching
• Zettelkasten Integration: MOCs, atomic notes, bidirectional links for Obsidian vaults
• MCP Server: HTTP API for integration with AI coding assistants
• Natural Language Commands: Parse requests like "organize my downloads folder"
• Auto-Tagging: Generate semantic tags from filenames and readable file content
• Smart Renaming: Infer better filenames from content with auto_describe
• Templates: Apply finance, research, and media folder templates instantly
• Analytics Dashboard API: Inspect file types, categories, duplicate waste, tags, and largest files
• dry-Run Mode: Preview changes before applying
• Safe by Design: Path validation, backup-first execution, no data deletion without confirmation

Integration status: MCP server is the primary interface. Direct integration docs are available for Claude Desktop, Aider, and OpenCode. Generic HTTP/MCP integration works with any AI coding assistant — see MCP generic guide.

Quick Start

Install

# Install from source
pip install -e .

# Or install with pipx (recommended for CLI tools)
pipx install .

Start the MCP server:

file-org-wiz --port 5000 --mount /YOUR/MOUNT --backup /YOUR/BACKUP
# Portfolio alias (both commands work identically)
turintech-file-org-wiz --port 5000 --mount /YOUR/MOUNT --backup /YOUR/BACKUP

Examples

Try the examples/ directory:

• examples/organize_downloads.py — Scan, analyze, and organize a directory of files using PARA + Zettelkasten methodology

python examples/organize_downloads.py /path/to/your/folder

Test:

curl http://localhost:5000/health

Preview (dry-run):

curl -X POST http://localhost:5000/organize \
  -H "Content-Type: application/json" \
  -d '{"mount_path": "/YOUR/MOUNT", "dry_run": true}'

Organize (for real):

curl -X POST http://localhost:5000/organize \
  -H "Content-Type: application/json" \
  -d '{"mount_path": "/YOUR/MOUNT", "backup_path": "/YOUR/BACKUP", "do_backup": true}'

API Endpoints

Organize Options

{
  "mount_path": "/path/to/mount",
  "backup_path": "/path/to/backup",
  "do_backup": true,
  "template": "finance",
  "dry_run": true,
  "create_vault": false,
  "vault_path": "/path/to/vault"
}

With dry_run: true, the response includes suggested_actions preview.

Smart Naming

{
  "file_path": "/path/to/file.txt",
  "auto_describe": true,
  "version": 1
}

Natural Language Commands

curl -X POST http://localhost:5000/nlp-command \
  -H "Content-Type: application/json" \
  -d '{"command": "preview organize my downloads folder"}'

Analytics

curl "http://localhost:5000/analytics?path=/YOUR/MOUNT"

Documentation

Templates

Installation by System

Choose your AI system below:

Folder Structure Created

MOUNT_PATH/
├── 00_INBOX/                    # Drop zone - process daily
├── 01_PROJECTS/               # Time-bound deliverables
│   ├── Projects/
│   ├── Client-Work/
│   └── Personal/
├── 02_AREAS/                  # Ongoing responsibilities
│   ├── Health/
│   ├── Finance/
│   ├── Home/
│   ├── Learning/
│   └── Personal/
├── 03_RESOURCES/              # Reference material
│   ├── AI/
│   ├── Tech/
│   ├── Career/
│   ├── Development/
│   ├── Media/
│   ├── Reading/
│   └── Tools/
├── 04_ARCHIVE/               # Completed items
├── 90_TEMPLATES/             # Reusable templates
└── 99_SYSTEM/                # Rules & documentation
    ├── File Naming Rules.md
    ├── Tag Rules.md
    ├── Vault Rules.md
    └── File_System_User_Guide.md

File Naming Convention

Pattern: YYYY-MM-DD__context__description__vNN.ext

Requirements

• Python 3.8+
• Flask >= 2.3.2
• An AI agent that can execute bash commands, read/write files, and navigate directory structure

Security

See SECURITY.md for our security policy and reporting guidelines.

Contributing

Contributions are welcome! Please read CONTRIBUTING.md for detailed guidelines on our development process, coding standards, PR workflow, and code of conduct.

License

MIT — see LICENSE for details.

Your digital life is an extension of your mind. Organize it.