{"id":32460115,"url":"https://github.com/wianho/llm-file-manager-agent","last_synced_at":"2026-05-05T18:35:03.796Z","repository":{"id":320110375,"uuid":"1080836369","full_name":"wianho/llm-file-manager-agent","owner":"wianho","description":null,"archived":false,"fork":false,"pushed_at":"2025-10-22T00:57:51.000Z","size":22,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-10-22T02:41:17.539Z","etag":null,"topics":["ai-agent","chatbot","file-manager","flask","function-calling","llama","llm","local-llm","natural-language","ollama","python"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/wianho.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-10-21T23:59:10.000Z","updated_at":"2025-10-22T00:57:54.000Z","dependencies_parsed_at":"2025-10-22T02:41:20.387Z","dependency_job_id":"2462a32b-3c11-408d-a561-b5bcc5960bb2","html_url":"https://github.com/wianho/llm-file-manager-agent","commit_stats":null,"previous_names":["wianho/llm-file-manager-agent"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/wianho/llm-file-manager-agent","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wianho%2Fllm-file-manager-agent","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wianho%2Fllm-file-manager-agent/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wianho%2Fllm-file-manager-agent/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wianho%2Fllm-file-manager-agent/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/wianho","download_url":"https://codeload.github.com/wianho/llm-file-manager-agent/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wianho%2Fllm-file-manager-agent/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32663361,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-05T11:29:49.557Z","status":"ssl_error","status_checked_at":"2026-05-05T11:29:48.587Z","response_time":54,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai-agent","chatbot","file-manager","flask","function-calling","llama","llm","local-llm","natural-language","ollama","python"],"created_at":"2025-10-26T11:21:49.390Z","updated_at":"2026-05-05T18:35:03.790Z","avatar_url":"https://github.com/wianho.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# 📁 Local File Manager Agent\n\nAn **LLM-powered** file system assistant with intelligent function calling. Chat with your files using natural language - powered by **Ollama + Llama 3.1** with a beautiful purple gradient UI.\n\n![Version](https://img.shields.io/badge/version-2.0.0-blue)\n![Python](https://img.shields.io/badge/python-3.8+-green)\n![Flask](https://img.shields.io/badge/Flask-3.0.0-black)\n![Ollama](https://img.shields.io/badge/Ollama-llama3.1:8b-purple)\n\n## ✨ Features\n\n- 🤖 **LLM-Powered Intelligence**: Uses Ollama's Llama 3.1:8b with function calling to understand natural language\n- 🗣️ **Natural Language Interface**: No need for exact commands - just talk naturally (\"search for Python files\", \"what's taking up space?\")\n- 📊 **Smart File Operations**: Find files by extension, create folders, list directories, and find largest files\n- 🎨 **Beautiful UI**: Purple gradient theme with smooth animations and mobile-responsive design\n- 🚀 **Production Ready**: Comprehensive error handling, CORS support, and clean architecture\n- 🧠 **Function Calling**: LLM intelligently selects the right tool for each request\n- 🌐 **REST API**: Well-documented endpoints for chat and file operations\n\n## 🎯 Supported Operations\n\nThe LLM understands natural language, so you can phrase requests however you like!\n\n| Operation | Example Queries | Description |\n|-----------|----------------|-------------|\n| **Find Files** | \"Find all .py files\"\u003cbr\u003e\"Search for Python files\"\u003cbr\u003e\"Locate JavaScript code\" | Search for files by extension |\n| **Largest Files** | \"Show me the largest files\"\u003cbr\u003e\"What's taking up space?\"\u003cbr\u003e\"Which files are biggest?\" | Get top 10 largest files in directory tree |\n| **Create Folder** | \"Create folder my_project\"\u003cbr\u003e\"I need a new directory called test\"\u003cbr\u003e\"Make a folder named docs\" | Create a new directory |\n| **List Directory** | \"List current directory\"\u003cbr\u003e\"Show me what files are in here\"\u003cbr\u003e\"What's in this folder?\" | Show contents of a directory |\n| **Move Files** | \"Move all Screenshot*.png files to archive\"\u003cbr\u003e\"Relocate *.txt files from Downloads to Documents\"\u003cbr\u003e\"Organize report_*.pdf files\" | Move files matching a pattern from one directory to another |\n| **Find Duplicates** | \"Find duplicate files\"\u003cbr\u003e\"Show me duplicate files in Downloads\"\u003cbr\u003e\"Which files are duplicated?\" | Find duplicate files using SHA256 hashing and show wasted space |\n\n## 📋 Prerequisites\n\n- **Python**: 3.8 or higher\n- **pip**: Python package installer\n- **Ollama**: Local LLM runtime ([Install here](https://ollama.ai))\n- **Llama 3.1:8b model**: Run `ollama pull llama3.1:8b` after installing Ollama\n- **Modern browser**: Chrome, Firefox, Safari, or Edge\n\n## 🛠️ Installation\n\n### 1. Install and Start Ollama\n\n```bash\n# Install Ollama (macOS)\nbrew install ollama\n\n# Start Ollama service\nbrew services start ollama\n\n# Pull the Llama 3.1:8b model (supports function calling)\nollama pull llama3.1:8b\n\n# Verify Ollama is running\nollama list\n```\n\n### 2. Clone or Navigate to Project\n\n```bash\ncd /Users/andle/AI/aichat/file-manager-agent\n```\n\n### 3. Set Up Backend\n\n```bash\n# Create virtual environment (recommended)\npython3 -m venv venv\nsource venv/bin/activate\n\n# Install Python dependencies\npip install -r backend/requirements.txt\n```\n\n### 4. Frontend Setup\n\nNo installation needed! The frontend is pure HTML/CSS/JavaScript.\n\n## 🚀 Running the Application\n\n### Start the Backend Server\n\n```bash\n# Activate virtual environment\nsource venv/bin/activate\n\n# Start the server\npython3 backend/app.py\n```\n\nYou should see:\n```\n🚀 Starting Local File Manager Agent...\n📁 Base path: /Users/andle\n🤖 AI Model: llama3.1:8b (with function calling)\n🌐 Server running on http://localhost:5001\n\n✨ LLM-powered intelligent file operations enabled!\n```\n\n**Note**: Port 5001 is used instead of 5000 because macOS AirPlay Receiver uses port 5000 by default.\n\n### Open the Frontend\n\n1. Open `frontend/index.html` in your browser, or\n2. Serve with a local server (optional):\n\n```bash\n# From the frontend directory\ncd frontend\npython3 -m http.server 8080\n```\n\nThen visit: `http://localhost:8080`\n\n## 🎮 Usage\n\n### Via Chat Interface\n\n1. Open the frontend in your browser\n2. Wait for the green \"Connected\" status indicator\n3. Type natural language commands (the LLM understands variations!):\n   - \"Find all .py files\" or \"Search for Python files\"\n   - \"Show me the largest files\" or \"What's taking up disk space?\"\n   - \"Create folder test_project\" or \"I need a new directory called my_project\"\n   - \"List current directory\" or \"Show me what files are in here\"\n\n### Via API (cURL examples)\n\n#### Health Check\n```bash\ncurl http://localhost:5001/api/health\n```\n\n#### Chat Endpoint\n```bash\ncurl -X POST http://localhost:5001/api/chat \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"message\": \"Find all .py files\",\n    \"context\": {\"directory\": \"/Users/andle\"}\n  }'\n```\n\n#### Execute Operation\n```bash\ncurl -X POST http://localhost:5001/api/execute \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"action\": \"find_by_extension\",\n    \"params\": {\n      \"directory\": \"/Users/andle\",\n      \"extension\": \".py\",\n      \"limit\": 50\n    }\n  }'\n```\n\n## 📐 Architecture\n\n```\nfile-manager-agent/\n├── backend/\n│   ├── app.py              # Flask server with API endpoints\n│   └── requirements.txt    # Python dependencies\n├── frontend/\n│   ├── index.html         # Chat interface structure\n│   ├── styles.css         # Purple gradient theme \u0026 animations\n│   └── app.js             # Chat logic \u0026 API communication\n└── README.md              # This file\n```\n\n### Backend Components\n\n- **FileOperations**: Handles all file system operations with proper error handling\n- **AgentProcessor**: Processes natural language queries (currently keyword-based, ready for LLM integration)\n- **API Endpoints**:\n  - `POST /api/chat`: Natural language chat interface\n  - `POST /api/execute`: Execute specific file operations\n  - `GET /api/health`: Health check endpoint\n\n### Frontend Components\n\n- **Chat Interface**: Beautiful message display with user/agent distinction\n- **Typing Indicator**: Animated dots while processing\n- **Status Indicator**: Real-time connection status with color-coded dot\n- **File Results**: Formatted tables for file listings\n- **Mobile Responsive**: Adapts to different screen sizes\n\n## 🎨 UI Features\n\n- **Color Scheme**: Purple gradient (#667eea → #764ba2) with dark theme\n- **Animations**: Smooth fade-in, slide-down, and typing animations\n- **Custom Scrollbar**: Themed scrollbar for chat container\n- **Message Types**: Success (green), error (red), and normal messages\n- **File Path Display**: Monospace font for file paths and names\n\n## 🧠 How It Works\n\n### LLM Function Calling Architecture\n\nThe agent uses **Ollama's function calling** feature to intelligently understand your requests:\n\n1. **User Query**: You type a natural language request like \"search for Python files\"\n2. **LLM Processing**: Llama 3.1:8b analyzes your intent using the system prompt\n3. **Function Selection**: The LLM decides which file operation tool to call\n4. **Parameter Extraction**: The LLM extracts parameters (e.g., extension=\".py\")\n5. **Execution**: The backend executes the chosen operation\n6. **Response**: Results are formatted and displayed in the chat UI\n\n### Available Tools\n\nThe LLM has access to 6 file operation tools defined in `backend/app.py`:\n\n```python\n- find_files_by_extension: Search for files with specific extensions\n- get_largest_files: Find files taking up the most space\n- create_folder: Make new directories\n- list_directory: Show directory contents\n- move_files: Move files matching a pattern from one directory to another\n- find_duplicates: Find duplicate files using SHA256 hashing\n```\n\nEach tool has a detailed description that helps the LLM decide when to use it.\n\n### Model Configuration\n\nThe system uses **Llama 3.1:8b** because it:\n- ✅ Supports function calling (required for tools)\n- ✅ Runs locally on Apple Silicon M-series chips\n- ✅ Fast enough for real-time chat responses\n- ✅ Smart enough to understand natural language variations\n\n**Note**: Models like `qwen2.5-coder` and `deepseek-coder-v2` do NOT support function calling.\n\n### Future Operations\n\nPlanned additions:\n- **File Search**: Search file contents with regex\n- **File Rename**: Rename individual files\n- **File Delete**: Safe file deletion with confirmation\n- **File Stats**: Detailed file metadata\n- **Copy Files**: Copy files matching a pattern\n- **Smart Cleanup**: Suggest which duplicate files to delete based on file locations\n\n## 🔧 Configuration\n\n### Change LLM Model\n\nEdit `backend/app.py:24`:\n\n```python\nOLLAMA_MODEL = \"llama3.1:8b\"  # Change to any model with function calling support\n```\n\n**Compatible models**:\n- `llama3.1:8b` (recommended - 4.9GB)\n- `llama3.2` (faster - 2GB)\n- Other llama models with function calling\n\n**Note**: Make sure to pull the model first: `ollama pull \u003cmodel-name\u003e`\n\n### Change Base Directory\n\nEdit `backend/app.py:22`:\n\n```python\nBASE_PATH = os.path.expanduser(\"~\")  # Change to your preferred path\n```\n\n### Adjust File Limits\n\nEdit `backend/app.py:23`:\n\n```python\nMAX_FILE_SIZE_DISPLAY = 100  # Maximum files to return\n```\n\n### Frontend API URL\n\nEdit `frontend/app.js`:\n\n```javascript\nconst CONFIG = {\n    API_BASE_URL: 'http://localhost:5001',  // Change if backend runs elsewhere\n    TYPING_DELAY: 1000,\n    SCROLL_BEHAVIOR: 'smooth'\n};\n```\n\n## 🐛 Troubleshooting\n\n### Ollama Not Running\n\n**Problem**: `Error in LLM processing: Connection refused`\n\n**Solution**:\n```bash\n# Check if Ollama is running\nbrew services list | grep ollama\n\n# Start Ollama if not running\nbrew services start ollama\n\n# Verify the model is available\nollama list\n```\n\n### LLM Slow to Respond\n\n**Problem**: Queries take 10+ seconds\n\n**Solutions**:\n- Switch to a smaller model: `llama3.2` (2GB) instead of `llama3.1:8b` (4.9GB)\n- Check CPU usage - ensure no other heavy processes are running\n- On Apple Silicon, ensure Ollama is using the GPU\n\n### Backend Won't Start\n\n**Problem**: `ModuleNotFoundError: No module named 'flask'` or `'ollama'`\n\n**Solution**:\n```bash\n# Activate virtual environment first\nsource venv/bin/activate\n\n# Then install dependencies\npip install -r backend/requirements.txt\n```\n\n### Frontend Shows \"Disconnected\"\n\n**Problem**: Cannot connect to backend\n\n**Solutions**:\n1. Ensure backend is running: `python3 backend/app.py`\n2. Check backend is on port 5001: `lsof -i :5001`\n3. Verify CORS is enabled in `app.py`\n\n### Permission Errors\n\n**Problem**: `PermissionError: [Errno 13] Permission denied`\n\n**Solution**: The app runs with your user permissions. Ensure you have access to directories you're querying.\n\n### Port Already in Use\n\n**Problem**: `OSError: [Errno 48] Address already in use`\n\n**Solution**:\n```bash\n# Find process using port 5001\nlsof -i :5001\n\n# Kill the process (replace PID with actual process ID)\nkill -9 \u003cPID\u003e\n```\n\n**Note**: If you need to use port 5000 on macOS, you may need to disable AirPlay Receiver in System Preferences.\n\n## 📝 API Documentation\n\n### POST /api/chat\n\nProcess natural language queries.\n\n**Request:**\n```json\n{\n  \"message\": \"Find all .py files\",\n  \"context\": {\n    \"directory\": \"/Users/andle\"\n  }\n}\n```\n\n**Response:**\n```json\n{\n  \"response\": \"I'll execute: find_by_extension\",\n  \"action_info\": {\n    \"action\": \"find_by_extension\",\n    \"params\": {\n      \"directory\": \"/Users/andle\",\n      \"extension\": \".py\",\n      \"limit\": 50\n    }\n  }\n}\n```\n\n### POST /api/execute\n\nExecute a specific file operation.\n\n**Request:**\n```json\n{\n  \"action\": \"find_by_extension\",\n  \"params\": {\n    \"directory\": \"/Users/andle\",\n    \"extension\": \".py\",\n    \"limit\": 50\n  }\n}\n```\n\n**Response:**\n```json\n{\n  \"success\": true,\n  \"data\": [\n    {\n      \"path\": \"/Users/andle/script.py\",\n      \"name\": \"script.py\",\n      \"size\": 1024,\n      \"readable_size\": \"1.00 KB\",\n      \"modified\": \"2025-10-21T12:00:00\"\n    }\n  ],\n  \"message\": \"Found 1 files\"\n}\n```\n\n#### Find Duplicates Example\n\n**Request:**\n```json\n{\n  \"action\": \"find_duplicates\",\n  \"params\": {\n    \"directory\": \"/Users/andle/Downloads\",\n    \"min_size\": 102400\n  }\n}\n```\n\n**Response:**\n```json\n{\n  \"success\": true,\n  \"data\": {\n    \"duplicate_groups\": [\n      {\n        \"hash\": \"e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855\",\n        \"files\": [\n          {\n            \"path\": \"/Users/andle/Downloads/photo1.jpg\",\n            \"name\": \"photo1.jpg\",\n            \"size\": 2048576,\n            \"readable_size\": \"2.00 MB\"\n          },\n          {\n            \"path\": \"/Users/andle/Downloads/backup/photo1.jpg\",\n            \"name\": \"photo1.jpg\",\n            \"size\": 2048576,\n            \"readable_size\": \"2.00 MB\"\n          }\n        ],\n        \"wasted_space\": 2048576,\n        \"wasted_readable\": \"2.00 MB\"\n      }\n    ],\n    \"total_wasted_space\": 2048576,\n    \"total_wasted_readable\": \"2.00 MB\"\n  },\n  \"message\": \"Found 1 duplicate group(s) wasting 2.00 MB\"\n}\n```\n\n### Available Actions\n\n| Action | Parameters | Description |\n|--------|-----------|-------------|\n| `find_by_extension` | directory, extension, limit | Find files by extension |\n| `largest_files` | directory, limit | Get largest files |\n| `create_folder` | directory, folder_name | Create new folder |\n| `list_directory` | directory | List directory contents |\n| `move_files` | source_directory, destination_directory, pattern | Move files matching a pattern |\n| `find_duplicates` | directory, min_size | Find duplicate files using SHA256 hashing (default min_size: 102400 bytes = 100KB) |\n\n## 📄 License\n\nMIT License - Feel free to use and modify for your projects.\n\n## 🙏 Credits\n\nBuilt with:\n- [Ollama](https://ollama.ai/) - Local LLM runtime\n- [Llama 3.1:8b](https://ollama.ai/library/llama3.1) - Meta's LLM with function calling support\n- [Flask](https://flask.palletsprojects.com/) - Python web framework\n- [Flask-CORS](https://flask-cors.readthedocs.io/) - Cross-origin resource sharing\n- Pure HTML/CSS/JavaScript - No frontend frameworks needed\n\n---\n\n**Built with ❤️ and 🤖 for intelligent local file management**\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwianho%2Fllm-file-manager-agent","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fwianho%2Fllm-file-manager-agent","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwianho%2Fllm-file-manager-agent/lists"}