Watches. Understands. Acts safely.
Sentinel is a local-first, AI-powered file cleanup agent that intelligently scans your filesystem, generates a structured cleanup plan using a locally running LLM, validates it for safety, and executes it — but only after you explicitly approve every action.
Unlike basic scripts that delete files by extension, or cloud cleaners that upload your private data to remote servers, Sentinel runs entirely on your machine. The AI never touches your disk. A deterministic safety engine stands between the AI's suggestions and your files. You are always in control.
| Problem | Sentinel's Answer |
|---|---|
| Cluttered Downloads, Desktop, Documents | AI-driven scan that understands context, not just extensions |
| Cloud cleaners are a privacy risk | 100% local — your files never leave your machine |
| Scripts delete the wrong things | Safety Validator blocks dangerous paths before execution |
| Mistakes are permanent | Every action logged, every delete goes to Trash — full undo |
| Hard drives are huge | Generator-based scanner — never loads entire filesystem into RAM |
Sentinel is built on a 4-layer N-tier architecture with strict separation of concerns. Each layer has exactly one responsibility and no knowledge of the layers above it.
┌─────────────────────────────────────────────────────┐
│ Interface Layer │
│ CLI (Typer) │ Web (Next.js 14) │ Desktop (Tauri) │
└─────────────────────────┬───────────────────────────┘
│
┌─────────────────────────▼───────────────────────────┐
│ API Gateway │
│ FastAPI + WebSocket Stream │
└─────────────────────────┬───────────────────────────┘
│
┌─────────────────────────▼───────────────────────────┐
│ Core Pipeline (sentinel-core) │
│ Scanner → Classifier → Planner → Safety → Executor │
│ Preference Memory │
└─────────────────────────┬───────────────────────────┘
│
┌─────────────────────────▼───────────────────────────┐
│ Persistence Layer │
│ SQLite via SQLModel — tasks, logs, decisions, │
│ preference_patterns, preferences │
└─────────────────────────────────────────────────────┘
These rules are enforced structurally — not by convention:
- AI never executes — the LLM only produces a JSON plan. The Executor never calls the LLM.
- Human approval required — no destructive action runs without explicit user confirmation.
- Trash-first deletion — all deletes go to system Trash/Recycle Bin, never permanent wipe by default.
- Full audit trail — every operation logged to SQLite with source, destination, and file hash.
- System path protection —
/System,/Windows,/usr,C:\Windowsetc. are hardcoded blocklists. - Dry-run default — preview mode is always on unless you explicitly request execution.
Recursively walks the filesystem using Python yield generators — the Iterator Pattern. Files are streamed one at a time rather than loaded into RAM all at once. Respects a configurable MAX_SCAN_DEPTH and skips ignored directories (node_modules, .git, .cache, system folders). Each file becomes a FileMetadata object containing path, size, extension, modified date, and an MD5 hash for duplicate detection.
Maps file extensions to FileType enum values: DOCUMENT, IMAGE, VIDEO, AUDIO, ARCHIVE, EXECUTABLE, CODE, UNKNOWN. Uses PDF content inspection for deeper type detection. Identifies screenshots by filename pattern, old installers by age and type, large media files by size threshold, and duplicates by MD5 hash comparison.
Sends classified file data to a locally running LLM (via Ollama) using a Jinja2 prompt template. The LLM responds with a PlanSchema — a structured JSON list of proposed actions. The Planner never executes anything.
Key design — Adapter Pattern + Dependency Inversion:
PlannerAgent depends on the abstract LLMProvider interface, not on OllamaClient directly. To swap the AI backend, inject a different LLMProvider implementation at construction time. No changes to PlannerAgent required.
# Swap Ollama for any other provider — PlannerAgent doesn't care
planner = PlannerAgent(provider=OpenAIProvider()) # or OllamaClient(), or MockProvider()A mandatory, non-bypassable checkpoint between the AI and the Executor. For every proposed action, it checks:
- Is the source path within the user-defined scan scope?
- Is any path on the protected directory list?
- Does the source file actually exist right now?
If any check fails, the action is flagged is_safe=False and will not execute. The AI's output is treated as untrusted input — because LLMs hallucinate.
The only component that modifies the filesystem. Implements the Strategy Pattern — different logic per ActionType (MOVE, DELETE, COPY, RENAME) behind a single execute() interface. Uses graceful degradation — if one file fails (locked by another process), execution continues for remaining files, with each result logged individually.
A lightweight feedback loop. Every user approval/rejection is stored in the user_decisions table. Confidence scores are computed as approval_count / occurrence_count per operation type. Before each new planning cycle, these scores are injected into the LLM prompt as context — so the system learns your preferences over time without any cloud dependency.
| Principle / Pattern | Where | What it achieves |
|---|---|---|
| SRP | Scanner, Planner, Executor are separate classes | Each class has exactly one reason to change |
| OCP | ActionType enum + Executor |
Add new action types without modifying core logic |
| LSP | OllamaClient extends LLMProvider |
Any LLMProvider subclass works wherever the base is expected |
| ISP | IExecutable and IUndoable are separate interfaces |
Classes only implement what they actually need |
| DIP | PlannerAgent → LLMProvider (abstract) |
High-level module decoupled from low-level implementation |
| Adapter Pattern | LLMProvider interface |
Ollama, OpenAI, or any LLM backend becomes a drop-in swap |
| Pipeline Pattern | CleanPCPipeline |
Each stage is isolated; failure in one stage stops the chain |
| Iterator Pattern | _safe_walk() generator in Scanner |
Streams files lazily — never loads entire filesystem into RAM |
| Strategy Pattern | Executor's ActionType dispatch |
Runtime selection of MOVE / DELETE / COPY / RENAME logic |
- FastAPI — REST API + WebSocket server
- SQLModel — SQLAlchemy + Pydantic combined ORM
- Pydantic v2 — Data validation and schema enforcement
- Ollama — Local LLM runtime (Llama 2, Mistral, etc.)
- Typer — CLI framework
- Rich — Terminal UI rendering
- send2trash — Safe deletion to system Trash
- Next.js 14 — React framework
- Tailwind CSS — Utility-first styling
- Framer Motion — Animations
- Zustand — State management
- TanStack Query — Data fetching + caching
- Tauri — Lightweight native desktop wrapper (replaces Electron)
- Tokio — Async runtime
- Serde — Serialization
# 1. Install Ollama (local AI runtime)
curl -fsSL https://ollama.ai/install.sh | sh
# 2. Pull a model
ollama pull llama2
# 3. Install Poetry via Python 3.12 (required — Python 3.14 has a known pip/libexpat bug)
curl -sSL https://install.python-poetry.org | python3.12 -
# 4. Add Poetry to PATH
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc# Clone the repository
git clone https://github.com/Mystic-commits/Sentinel.git
cd Sentinel/sentinel-core
# Regenerate lock file (required after fresh clone)
poetry lock
# Install all dependencies
poetry installpoetry run pytest --ignore=tests/test_executor.py --ignore=tests/test_safety.pyExpected output: 102 passed ✅
Note on test failures:
test_executor.pyandtest_safety.pyhave two import errors from a refactor whereOperationSchemawas renamed andExecutorclass was restructured. These are stale test files — the core engine itself is fully functional.
# Scan Downloads folder (preview only — nothing is changed)
poetry run sentinel clean-pc scan ~/Downloads
# Scan multiple directories
poetry run sentinel clean-pc scan --dirs ~/Downloads --dirs ~/Desktop
# Control scan depth
poetry run sentinel clean-pc scan ~/Downloads --max-depth 3Open two terminals:
Terminal 1 — Backend:
cd Sentinel/sentinel-core
poetry run uvicorn sentinel_core.api.main:app --reloadTerminal 2 — Frontend:
cd Sentinel/sentinel-web
npm install
npm run devOpen http://localhost:3000 in your browser.
# macOS
cd Sentinel/sentinel-web
npm run tauri:build:mac
open src-tauri/target/release/bundle/dmg/Sentinel_0.1.0_x64.dmg
# Windows
npm run tauri:build:wintasks — Central job record with state machine (SCANNING→PLANNING→REVIEW→EXECUTING→COMPLETED)
execution_logs — Per-action audit trail, FK → tasks
user_decisions — Every approve/reject event, FK → tasks
preference_patterns — Learned confidence scores (approval_count / occurrence_count)
preferences — Key-value store for user settings
Sentinel will never:
- Delete files permanently by default
- Touch system directories (
/System,/Windows,/usr,C:\Windows, etc.) - Execute without explicit user approval
- Send any file data to external servers
- Run without comprehensive operation logging
Sentinel will always:
- Move deletions to Trash/Recycle Bin
- Log every operation with source path, destination, file hash, and timestamp
- Validate AI-generated plans before showing them to the user
- Allow full undo of any executed operation
- Run in preview mode by default
Sentinel/
├── sentinel-core/ # Core engine — all business logic (Python)
│ ├── sentinel_core/
│ │ ├── scanner/ # Filesystem walker (Iterator pattern)
│ │ ├── cleanpc/ # Classifier + pipeline orchestrator
│ │ ├── planner/ # LLMProvider interface + OllamaClient
│ │ ├── safety/ # SafetyValidator + protected path constants
│ │ ├── executor/ # File operations + undo + audit logging
│ │ ├── memory/ # PreferenceMemory + SQLite integration
│ │ ├── models/ # Pydantic schemas (FileMetadata, PlanAction, etc.)
│ │ ├── api/ # FastAPI routes + WebSocket manager
│ │ └── cli/ # Typer CLI commands
│ └── tests/ # 102 passing tests
├── sentinel-web/ # Next.js 14 dashboard (TypeScript)
├── sentinel-desktop/ # Tauri desktop wrapper (Rust)
├── sentinel-cli/ # Thin CLI shell
└── design-assets/ # Brand guidelines + design system
cd Sentinel/sentinel-core
# Full test suite (skipping 2 stale import files)
poetry run pytest --ignore=tests/test_executor.py --ignore=tests/test_safety.py
# With coverage report
poetry run pytest --ignore=tests/test_executor.py --ignore=tests/test_safety.py --cov=sentinel_core --cov-report=html
# Specific module
poetry run pytest tests/test_scanner.py -v
poetry run pytest tests/test_planner_adapter.py -v
poetry run pytest tests/test_memory.py -v- Fork the repository
- Create a feature branch:
git checkout -b feature/your-feature - Make your changes with tests
- Run quality checks:
poetry run ruff check . poetry run black . poetry run mypy sentinel_core poetry run pytest --ignore=tests/test_executor.py --ignore=tests/test_safety.py
- Commit:
git commit -m 'Add your feature' - Push and open a Pull Request
MIT License — see LICENSE for details.
- Ollama — for making local AI accessible
- FastAPI — for the excellent Python web framework
- Tauri — for lightweight cross-platform desktop apps
- Next.js — for the powerful React framework
Made with care by developers who hate cluttered computers.