AI-Powered File Organization & Cleanup Agent
Your intelligent assistant for safely organizing and cleaning your computer
Features • Installation • Usage • Architecture • Safety • Contributing
Sentinel is a local-first AI agent that intelligently organizes and cleans your computer's file system. Unlike traditional cleanup tools, Sentinel uses AI to understand your files and suggest smart organization strategies—while maintaining strict safety guarantees.
- 🧠 AI-Powered Intelligence: Understands file types, patterns, and optimal organization strategies
- 🔒 Safety First: Never performs destructive actions without explicit approval
- 🎯 Context-Aware: Learns from your preferences and adapts to your workflow
- 🖥️ Multi-Interface: CLI, Web UI, or Desktop app—use what you prefer
- 🌐 100% Local: Your data never leaves your machine
- ↩️ Fully Reversible: Every action can be undone
🗂️ Intelligent File Classification
- Detects installers, archives, screenshots, duplicates, and large media files
- Context-aware age analysis (old installers = cleanup candidates)
- Smart duplicate detection based on content hashing
🤖 AI-Driven Organization
- Generates cleanup plans using local LLMs (via Ollama)
- Learns from your preferences over time
- Suggests optimal folder structures and naming conventions
🛡️ Multi-Layer Safety System
- Pre-execution validation of all plans
- System directory protection (blocks /System, /Windows, etc.)
- Dry-run mode by default
- All deletions go to Trash/Recycle Bin
- Comprehensive operation logging
📊 Rich Insights
- Disk space analysis
- File age distribution
- Category-based reporting
- Visual organization hierarchy
💻 CLI Application
sentinel clean-pc scan ~/Downloads --max-depth 3
sentinel clean-pc execute --plan-id abc123
sentinel undo --operation-id xyz789🌐 Web Dashboard
- Real-time scanning progress
- Visual plan diff viewer
- Drag-and-drop rule customization
- Task history and analytics
🖥️ Desktop Application (Tauri)
- Native macOS and Windows app
- System tray integration
- One-click cleanup
- Scheduled automation
Note: Demo screenshots coming soon
┌─────────────────────────────────────────────────┐
│ 🛡️ Sentinel - Clean My PC │
├─────────────────────────────────────────────────┤
│ │
│ 📂 Scanned: ~/Downloads │
│ 📊 Found: 127 files (2.4 GB) │
│ │
│ Suggested Actions: │
│ • Delete 12 old installers → Save 850MB│
│ • Archive 8 old ZIPs → Save 340MB│
│ • Move 15 screenshots to Pictures → Organize │
│ • Remove 6 duplicates → Save 120MB│
│ │
│ [Preview Plan] [Execute] [Customize] │
└─────────────────────────────────────────────────┘
graph TB
subgraph "User Interfaces"
CLI[CLI - Typer]
WEB[Web UI - Next.js]
DESKTOP[Desktop - Tauri]
end
subgraph "API Layer"
API[FastAPI + WebSockets]
end
subgraph "Core Engine"
SCANNER[Scanner]
CLASSIFIER[File Classifier]
RULES[Rules Engine]
PLANNER[AI Planner]
SAFETY[Safety Validator]
EXECUTOR[Executor]
end
subgraph "External Services"
OLLAMA[Ollama - Local LLM]
DB[(SQLite DB)]
end
CLI --> API
WEB --> API
DESKTOP --> API
API --> SCANNER
SCANNER --> CLASSIFIER
CLASSIFIER --> RULES
RULES --> PLANNER
PLANNER --> OLLAMA
PLANNER --> SAFETY
SAFETY --> EXECUTOR
EXECUTOR --> DB
SCANNER --> DB
style SAFETY fill:#ff6b6b
style EXECUTOR fill:#51cf66
style PLANNER fill:#339af0
- AI Never Executes: AI only generates JSON plans; deterministic executor performs actions
- User Approval Required: No destructive actions without explicit user confirmation
- Trash-First Deletion: All deletes go to Trash/Recycle Bin by default
- Full Audit Trail: Every operation logged and reversible
- System Protection: Critical directories are blacklisted
- Dry-Run Default: Preview mode is the default behavior
- Python 3.11+ (Core engine)
- Node.js 18+ (Web UI)
- Ollama (Local AI runtime)
# Install Ollama
curl -fsSL https://ollama.ai/install.sh | sh
# Pull the model
ollama pull llama2
# Install Sentinel CLI
cd sentinel-core
poetry install
poetry run sentinel --help# Install CLI (see above)
# Install and run web UI
cd sentinel-web
npm install
npm run dev
# Backend
cd ../sentinel-core
poetry run uvicorn sentinel_core.api.main:app --reloadAccess at http://localhost:3000
macOS
# Build installer
cd sentinel-web
npm run tauri:build:mac
# Install the generated .dmg
open src-tauri/target/release/bundle/dmg/Sentinel_0.1.0_x64.dmgWindows
# Build installer
cd sentinel-web
npm run tauri:build:win
# Install the generated .msi# Scan your Downloads folder
sentinel clean-pc scan ~/Downloads
# Scan with custom depth
sentinel clean-pc scan ~/Downloads ~/Desktop --max-depth 3
# Execute a plan (requires approval)
sentinel clean-pc scan ~/Downloads --execute
# Dry run (default - shows what would happen)
sentinel clean-pc scan ~/Downloads --dry-run-
Start the backend:
cd sentinel-core poetry run uvicorn sentinel_core.api.main:app --reload -
Start the frontend:
cd sentinel-web npm run dev -
Open browser: Navigate to
http://localhost:3000 -
Create a task:
- Select directories to scan
- Review AI-generated plan
- Customize rules if needed
- Execute with one click
- Launch Sentinel from Applications/Start Menu
- Select folders from sidebar
- Click "Scan & Plan"
- Review suggestions in the main panel
- Click "Execute" to apply changes
- Use "Undo" if needed
Sentinel is built with safety as the #1 priority. Here's how we protect your data:
| Layer | Protection |
|---|---|
| AI Layer | Only generates JSON plans, never executes |
| Validation Layer | Blocks dangerous paths, validates all operations |
| Execution Layer | Deterministic, logged, reversible actions only |
| User Approval | Explicit confirmation required for destructive actions |
- ❌ Delete files permanently by default
- ❌ Touch system directories (/System, /Windows, /usr, etc.)
- ❌ Execute without user approval
- ❌ Send your data to external servers
- ❌ Run without comprehensive logging
- ✅ Moves deletions to Trash/Recycle Bin
- ✅ Creates undo logs for all operations
- ✅ Validates plans before execution
- ✅ Runs in dry-run mode by default
- ✅ Keeps detailed audit trails
- ✅ Allows manual review of all changes
Every action is logged with:
- Timestamp
- Operation type (move/delete/copy)
- Source and destination paths
- File hash (for verification)
- User who approved
- Plan ID and execution ID
View logs:
sentinel logs --operation-id xyz789
sentinel undo --operation-id xyz789Sentinel has comprehensive test coverage to ensure reliability:
# Run all tests
cd sentinel-core
poetry run pytest
# Run with coverage
poetry run pytest --cov=sentinel_core --cov-report=html
# Run specific test suite
poetry run pytest tests/test_scanner.py -vTest Coverage: 92%
Test Count: 45+ unit and integration tests
See TESTING.md for detailed testing documentation.
- File scanning and classification
- AI-powered planning
- Safety validation layer
- Basic CLI interface
- Undo functionality
- Clean PC pipeline
- Screenshot detection
- Duplicate file detection
- Archive management
- Old installer cleanup
- Next.js web dashboard
- Tauri desktop wrapper
- Real-time progress tracking
- Visual plan diff viewer
- Drag-and-drop rule editor
- Smart folder suggestions
- File naming conventions
- Tag-based organization
- Advanced duplicate detection (fuzzy)
- Photo organization (by date/location)
- Scheduled cleanup tasks
- Watch folder automation
- Custom rule templates
- Organization profiles
- Bulk rename utilities
- Code signing (macOS/Windows)
- Auto-update mechanism
- Plugin system
- Advanced analytics
- Multi-language support
We welcome contributions! Sentinel is built to be extensible and maintainable.
# Clone repository
git clone https://github.com/mystic/sentinel.git
cd sentinel
# Install backend dependencies
cd sentinel-core
poetry install
# Install frontend dependencies
cd ../sentinel-web
npm install
# Set up pre-commit hooks
cd ..
pre-commit installWe maintain high code quality standards:
- Linting: Ruff, Black
- Type Checking: Mypy
- Testing: Pytest with 90%+ coverage
- Pre-commit Hooks: Automatic formatting and validation
Run quality checks:
cd sentinel-core
poetry run ruff check .
poetry run black .
poetry run mypy sentinel_core
poetry run pytest- Fork the repository
- Create a feature branch:
git checkout -b feature/amazing-feature - Make your changes with tests
- Run quality checks:
poetry run pytest && poetry run ruff check . - Commit:
git commit -m 'Add amazing feature' - Push:
git push origin feature/amazing-feature - Open a Pull Request
- 🎨 UI/UX improvements
- 🧪 Additional test coverage
- 📝 Documentation improvements
- 🌐 Internationalization
- 🔌 Plugin development
- 🐛 Bug reports and fixes
See CONTRIBUTING.md for detailed guidelines.
- Testing Guide - Comprehensive testing documentation
- Building Desktop App - Desktop build instructions
- API Documentation - FastAPI endpoint reference
- Architecture Overview - System design and patterns
- FastAPI - High-performance API server
- SQLAlchemy - Database ORM
- Pydantic - Data validation
- Ollama - Local LLM runtime
- Typer - CLI framework
- Rich - Terminal UI
- Next.js 14 - React framework
- Tailwind CSS - Utility-first styling
- Framer Motion - Animations
- Zustand - State management
- TanStack Query - Data fetching
- Tauri - Native desktop wrapper
- Tokio - Async runtime
- Serde - Serialization
This project is licensed under the MIT License - see the LICENSE file for details.
We chose MIT for maximum freedom:
- ✅ Commercial use allowed
- ✅ Modification allowed
- ✅ Distribution allowed
- ✅ Private use allowed
- ℹ️ License and copyright notice required
- Ollama - For making local AI accessible
- FastAPI - For the excellent Python web framework
- Tauri - For lightweight desktop applications
- Next.js - For the powerful React framework
- 🐛 Bug Reports: GitHub Issues
- 💬 Discussions: GitHub Discussions
- 📧 Email: sentinel@example.com
- 🐦 Twitter: @SentinelAI
If you find Sentinel useful, please consider giving it a star! It helps the project grow.
Made with ❤️ by developers who hate cluttered computers