跳到正文
DEV Community· SJ·· 3 小時前AI 評分48

Organizer CLI：以裝置端 Gemma 整理 macOS 檔案

Organizer CLI: Channeling My Inner Sloth to Tidy macOS with On-Device Gemma

AI 導讀

Organizer CLI 是一款開源的終端檔案整理工具，以裝置端 Gemma 模型掃描並分類 macOS 資料夾中的檔案，再由用戶透過互動介面確認整理方案。工具支援 Ollama 本機推理、Google Gemini 和 OpenRouter 雲端選項，並設有本機模型管理及硬件檢查功能；私隱模式會限制網絡連線至本機迴路。

正文

This is a submission for the Hacktoberfest Open-Source AI Challenge Week 3: Slow and Steady

What I Built

Every developer's ~/Downloads and ~/Desktop is a digital graveyard of good intentions: tax forms, software installers (.dmg, .pkg), flight receipts, random screenshots, zip archives, and research papers all dumped into one giant, overwhelming heap. Tidying it up manually takes willpower, time, and tedious dragging and dropping.

In honor of International Sloth Day and this week's "Slow and Steady" theme, I built Organizer CLI (organizer): a private, human-in-the-loop, terminal-based folder organizer powered by local, open-weight Gemma models.

Instead of spending Sunday afternoon categorizing files, you run one command:

organizer scan ~/Downloads

What It Does

  1. Zero-Effort Inspection: Recursively scans any target directory and categorizes files using local open-weight Gemma models running on-device via Ollama (or zero-RAM cloud fallbacks like Google Gemini and OpenRouter).
  2. Folder-Grouped Proposals: Aggregates proposals into clean tables under destination folder banners with file counts and AI attribution badges (📁 ⭐ Photographs (3 files)).
  3. Interactive Human-in-the-Loop TUI: Launches a keyboard-driven terminal UI (built on Rich Live). You can navigate files with ↑/↓ (k/j), toggle multi-select with Space or Shift+Space, and press m to reassign folders with Tab-autocompleting suggestions before anything is touched on disk.
  4. Autonomous Model Lifecycle Subsystem: Provides built-in commands (organizer models install, status, doctor, available) to discover, pull with streaming progress, verify, and diagnose local Gemma models with hardware resource checks (RAM and disk space).
  5. Strict Local Loopback Privacy: Enforces strict loopback network checks (127.0.0.1, localhost), ensuring confidential files, payslips, and NDAs never leave your machine.

Who Gets to Be Lazier Because of It?

  • Developers & Students who download dozens of PDFs, tarballs, and repos every week and dread the weekend cleanup.
  • Privacy-Conscious Mac Users who refuse to upload their personal tax returns, invoices, and bank statements to closed third-party cloud organizers.
  • Anyone with Digital Clutter Anxiety who wants their workspace tidy with minimal effort.

Demo

Here is how the interactive terminal workflow looks when running organizer scan:

╭────────────────────────── Organizer Review Plan ──────────────────────────╮
│ 📁 ⭐ Financial Invoices (2 files)                                         │
│   • Q3_Tax_Summary_2026.pdf      [98% - Semantic AI: Tax document]        │
│   • Stripe_Payout_Sept.csv       [95% - Semantic AI: Payout receipt]      │
│                                                                           │
│ 📁 ⭐ Photographs & Media (3 files)                                        │
│ ▶ • IMG_9402_Receipt.png         [92% - Multimodal Vision: Paper receipt] │
│   • Product_Mockup_V2.png        [90% - Multimodal Vision: UI wireframe]  │
│   • Architecture_Draft.heic      [88% - Semantic AI: Design diagram]      │
│                                                                           │
│ 📁 Installers & Packages (2 files)                                        │
│   • Docker_Desktop_v4.dmg        [Rule: Executable Disk Image]            │
│   • Node_v24_Darwin_arm64.pkg    [Rule: macOS Package Installer]          │
╰───────────────────────────────────────────────────────────────────────────╯
[Browse Mode] ↑/↓: Navigate • Space: Toggle • m: Move Folder • Enter: Confirm • q: Quit

Setup in Seconds: organizer setup

If you haven't configured a model yet, running organizer setup launches an onboarding wizard that auto-detects your local Ollama runtime, checks host RAM and disk availability, and downloads the recommended Gemma model with real-time transfer speeds:

$ organizer setup

✔ Detected local Ollama runtime at http://localhost:11434
✔ Inspected host hardware: 16.0 GB Unified RAM, 142.4 GB free disk

? Select your operational mode:
 > 1. Download recommended local model (gemma4:e2b - Multimodal, ~7.5 GB)
   2. Configure Google Gemini API (Free cloud tier, zero host RAM)
   3. Configure OpenRouter (Free cloud tier)
   4. Select another local model from catalog (gemma2:2b, gemma2:9b)
   5. Deterministic rule-only mode (instant, zero models)

Pulling gemma4:e2b [━━━━━━━━━━━━━━━━━━━━] 7.5 GB / 7.5 GB (48.2 MB/s)
✔ Model readiness smoke test passed! Active model set to 'gemma4:e2b'.

Self-Healing Diagnostics: organizer models doctor 

$ organizer models doctor

🔍 Running Organizer Diagnostics...
  [✔] Ollama binary installed: /usr/local/bin/ollama
  [✔] Ollama daemon running on loopback: http://localhost:11434
  [✔] Strict loopback validation: Passed (no remote egress detected)
  [✔] Memory check: 16.0 GB RAM total (8.0 GB required for gemma4:e2b)
  [✔] Disk space: 142.4 GB available (9.0 GB estimated storage)
  [✔] Active model readiness: 'gemma4:e2b' responds within 0.42s

Everything is healthy and ready to organize!

Code

The project is completely open source under the MIT License:
👉 https://github.com/BoseSj/OrgCLI

Tech Stack:

  • Language: Python 3.10+ (tested on Python 3.10 through 3.14)
  • CLI Framework: Typer with Click backend
  • Terminal UI: Rich & Rich Live (interactive ANSI terminal handling)
  • Local Inference: Ollama API client over asynchronous HTTPX
  • Hardware Diagnostics: psutil & shutil for live RAM and disk constraint evaluation
  • Testing: Deterministic Pytest suite with fake_ollama in-memory mock server (115 passing tests)

How I Built It

Organizer CLI is designed around Google's Gemma open-weight model family paired with a local-first lifecycle management engine.

graph TD
    User["User Terminal"] --> CLI["Organizer CLI (Typer)"]

    subgraph "CLI Entrypoints"
        Setup["organizer setup"]
        Scan["organizer scan <path>"]
        Models["organizer models <subcommand>"]
    end

    CLI --> Setup
    CLI --> Scan
    CLI --> Models

    subgraph "Local Engine Subsystems"
        Lifecycle["LocalModelLifecycleService"]
        Catalog["Gemma Model Catalog & Resource Evaluator"]
        TUI["Interactive Live TUI (Rich)"]
        Rules["Semantic + Deterministic Engine"]
    end

    Setup --> Lifecycle
    Models --> Lifecycle
    Scan --> Rules
    Rules --> TUI

    subgraph "Inference Providers"
        OllamaGemma["Ollama (gemma4:e2b / gemma2:2b / gemma2:9b)"]
        GeminiCloud["Google Gemini 3.8 Flash (Cloud Fallback)"]
        StaticRule["Deterministic File Rules (Offline Fallback)"]
    end

    Lifecycle --> OllamaGemma
    Rules --> OllamaGemma
    Rules --> GeminiCloud
    Rules --> StaticRule

1. Curated Local Model Catalog for Gemma

Local inference often frustrates users when model weights exceed their computer's available unified memory. To fix this, I created a curated catalog in src/organizer/models/catalog.py with hardware advisory evaluations:

  • gemma4:e2b (Recommended): Multimodal (text + image input), ~7.5 GB download size, optimized for 8 GB+ Apple Silicon Macs. Enables vision-based classification for screenshots, photos, and scanned receipts.
  • gemma2:2b: Lightweight text-only model (~1.6 GB pull size), perfect for low-spec machines or background battery-saving operations.
  • gemma2:9b: High-precision text reasoning model (~5.4 GB pull size) for users with 16 GB+ unified memory.

Before initiating a download, evaluate_model_resources() queries psutil to verify RAM headroom and free storage with a safety margin, warning the user before paging or system freezes can happen.

2. Autonomous Model Lifecycle Management

Users don't need to leave their terminal to juggle shell commands for Ollama. The organizer models subcommand suite manages model states directly:

  • organizer models available: Displays verified models with download sizes and hardware requirements.
  • organizer models install <id>: Pulls model layers via chunked streaming with live speed calculations.
  • organizer models use <id>: Switches active models and runs smoke tests.
  • organizer models doctor: Runs full system diagnostics.

3. Human-in-the-Loop Interactive TUI

Total automation can be dangerous when reorganizing important files. Organizer CLI implements an interactive review screen using rich.live.Live:

  • Moving between file rows using arrow keys (↑/↓) or Vim keys (k/j).
  • Multi-file selection (Space to toggle, Shift+Space for range select, d to deselect all).
  • Folder reassignment (m): Opens an inline prompt with Tab autocompletion cycling through existing folders, standard system categories, and AI-suggested categories.
  • Final confirmation (Enter) commits the finalized plan.

4. Zero-Friction Reliability: 115 Passing Tests

To ensure robustness across platforms without relying on live downloads during CI, the test harness features organizer.testing.fake_ollama—an in-process mock HTTP server that simulates stream chunking, download interruptions, network drops, and prompt responses. The entire test suite runs in under 25 seconds with 115 passing tests.

Why Does Open Innovation Matter?

Open innovation is the backbone of this project. Building this tool with proprietary, closed APIs would have introduced critical trade-offs:

  1. Uncompromising Document Privacy: Your ~/Downloads folder holds your life: tax returns, passport scans, medical invoices, private codebases, and company NDA documents. With open-weight Gemma running locally on Ollama over loopback (localhost), not a single byte of personal data ever leaves your computer.
  2. Offline & Air-Gapped Autonomy: Traveling on a flight without Wi-Fi? Working from an off-grid cabin? Open weights mean your tools keep working anywhere, anytime, without needing an active internet connection.
  3. No Subscriptions, No Rate Limits, No Token Bills: Closed APIs charge per token and impose throttling during peak demand. Open-source AI costs nothing to run once downloaded and will never be deprecated by a corporate API sunset.
  4. Hardware Acceleration on the Edge: Open models allow deep integration with local hardware—like Apple Silicon unified memory and the Apple Neural Engine (ANE)—giving instant responses with minimal power consumption.

My Agent Session

This project was built with the assistance of agentic pair programming sessions in Google Antigravity. The agent helped architect the multi-engine provider abstraction, implement the non-blocking streaming progress parser for Ollama pulls, and build the 115 unit and acceptance test scenarios (including edge cases like loopback enforcement and corrupted json streams).

(Agent session logs and transcript traces recorded during development).

The Lazy Payoff

How Much Time and Effort Does It Save?

  • Before: 30 to 45 minutes of manual sorting every two weeks (or avoiding it altogether until Finder search grinds to a halt).
  • With Organizer CLI:
    1. Open terminal: organizer scan ~/Downloads (1 second).
    2. Gemma parses and groups 100+ files into semantic folders (under 10 seconds).
    3. Skim the interactive grouped view, press Enter to confirm (5 seconds).
  • Total Time: Under 20 seconds. That is an immediate 95%+ time savings every single time you tidy your system.

I used Organizer CLI this week on my personal macOS development machine to sort through 184 unorganized downloads—filing bank statements into Invoices/, project assets into Assets/, and disk images into Installers/ with zero manual dragging.

Prize Categories

Primary Category:

  • Best Use of Gemma: Built from the ground up around Google's open-weight Gemma model family (gemma4:e2b, gemma2:2b, and gemma2:9b), complete with on-device Ollama integration, hardware resource validation, and full model lifecycle management.

Lazy developers make the best tools. Give your cluttered folders a rest and let Gemma(among few other options) do the heavy lifting!

來源：DEV Community · dev.to

#開源/倉庫#部署/工程#Google