SmartDrive-OS

Saturn's rings as orderly storage lanes: every file in its lane, across the whole drive.

SmartDrive-OS is a zero-dependency drive operating suite and sub-10ms SQLite FTS5 search engine for external portable SSDs (exFAT 512 KB clusters) and internal secondary workstation drives (NTFS 4 KB clusters). It is built for developers, university students, and AI coding agents (Claude Code, Claude Desktop, Antigravity, Cursor, Codex, Windsurf) to organize drives without breaking agent paths, govern .gitignore rules, offload C: caches, and verify file integrity with SHA-256 snapshots. Everything runs 100% locally on the Python 3.9+ standard library (dependencies = []) with zero telemetry.

🇻🇳 Tiếng Việt: README_VN.md · 🚀 Internal NTFS Drive & C-Drive Cache Offload Guide: README_INTERNAL.md

Table of Contents

• Quickstart
• Everyday Use
• Why exFAT Needs This
• Features at a Glance
  • CLI Command Reference
  • Folder Moves and Coding Agents
  • MCP Server & AI Coding Agents
  • Search Syntax
  • Learning Materials (Aurora Slides and Polaris)
  • Gitignore Governance
  • Safe Junk Cleaner
  • Snapshots and Backup
  • Workstation Hybrid and C-Drive Offload
  • Launchers
  • Profiles
• Testing
• Privacy, Security & Data Isolation
• Contributing & License

Quickstart

1. Install (or run without installing)

uvx (after the first PyPI release): needs only uv, which also downloads a Python when the machine has none.

uvx smart-drive-os <subcommand>        # runs any subcommand, installs nothing
uvx smart-drive-os mcp register --all  # registers `uvx smart-drive-os mcp` with your coding agents

pipx (after the first PyPI release; Python 3.9+):

pipx install smart-drive-os
smart-drive <subcommand>
smart-drive mcp register --all         # registers this install with your coding agents

pip install smart-drive-os works too.

From source:

git clone https://github.com/DuongNAD/smart-drive-os.git
cd smart-drive-os
pip install -e .                    # editable install (`smart-drive` CLI)
python -m smart_drive <subcommand>  # or run directly from the checkout
py -m smart_drive <subcommand>      # Windows Python Launcher (when `python` is not on PATH)
smart-drive self-path-check         # check PATH and print 1-click shell setup

Editable installs (pip install -e .) need pip 21.3 or newer: with an older pip (the Python 3.9 that ships with Xcode on macOS has pip 21.2), run python -m pip install -U pip first.

2. Initialise the drive

Run Setup_SSD.bat / Setup_SSD.ps1 (Windows), Setup_SSD.command (macOS), ./Setup_SSD.sh (Linux), or smart-drive init --profile <name> (see Profiles):

• workstation-hybrid: your secondary drive (D:, E:, …) with games, Windows apps, and coursework.
• internal-developer-vault: internal NVMe/SATA SSD receiving offloaded C: dev and AI caches.
• ai-developer: portable external SSD for LLM weights, checkpoints, datasets, and AI agents.
• data-science: data engineering pipelines, raw data, and EDA notebooks.
• general-workspace (default): universal active/archive code, learning notes, and utilities.

python -m smart_drive init --profile workstation-hybrid
python -m smart_drive init --profile ai-developer

3. Set up the MCP ecosystem (one command)

Fetch Constellation, Polaris, Aurora Slides, Vega, Orion, Sirius, and Mira into ~/.smart-drive/mcp (off the exFAT drive), register them with SmartDrive in every installed coding agent (Claude Code, Antigravity, Cursor, Codex), and health-check them. It lists the servers and asks which ones you want before it downloads or registers anything; safe to repeat:

python3 -m smart_drive setup  # macOS / Linux (Windows: python -m smart_drive setup or py -m smart_drive setup)

Answer a (all), n (none, the default), or numbers/names such as 1,3 or polaris,vega; Constellation, the control plane, always comes with the others while it is not installed yet. A server that is already downloaded is listed too when it would be added to an agent's config, with the agents named. --yes skips the question (--only polaris,vega --yes installs just those). A coding agent has no terminal to answer in: its run installs nothing, exits with code 4 and lists the servers, and the agent asks you in its own chat before it runs setup --only <your picks> --yes.

Needs Node.js >= 22.4 and git. --dry-run previews; --check --json reports state (exit code 3 = setup needed); --no-clone stays offline; --agents claude,cursor limits targets. Registered servers are reused, never cloned twice (mcp-agy is separate: own venv, Python >= 3.10, API key).

4. Register SmartDrive MCP standalone

smart-drive mcp register --all  # Antigravity, Claude, Cursor, Codex, Windsurf, .mcp.json

Or add the entry yourself. For Claude Desktop (claude_desktop_config.json), Cursor (~/.cursor/mcp.json), Antigravity (~/.gemini/antigravity/mcp_config.json), Windsurf (~/.codeium/windsurf/mcp_config.json) and a project's .mcp.json:

{
  "mcpServers": {
    "smart-drive": {
      "command": "uvx",
      "args": ["smart-drive-os", "mcp"],
      "env": { "PYTHONIOENCODING": "utf-8", "PYTHONUTF8": "1" }
    }
  }
}

Claude Code:

claude mcp add --scope user smart-drive -- uvx smart-drive-os mcp

Codex (~/.codex/config.toml):

[mcp_servers.smart-drive]
command = "uvx"
args = ["smart-drive-os", "mcp"]

With pipx use "command": "smart-drive", "args": ["mcp"] instead. Apps started from the desktop (Claude Desktop on macOS, for example) may not see ~/.local/bin: if uvx or smart-drive is not found, put its full path in command (which uvx or where uvx); smart-drive mcp register writes full paths by itself. To pin a drive add "--root", "E:\\" to args or set SMART_DRIVE_ROOT; otherwise it looks for a SmartDrive root above the folder the agent starts it in, then on attached drives.

Everyday Use

Checkup (1-screen health score & next steps) — Get a 0–100 (A–F) health score with plain-language status and copy-pasteable commands:

smart-drive checkup
smart-drive checkup --lang vi

Search (<10ms) — Query the SQLite FTS5 index with BM25 ranking instead of recursive find/grep:

smart-drive search "llama cat:ai_models"
smart-drive search "exam ext:pdf size:>1MB dir:DBI202"
smart-drive search --kind slide "vòng lặp"

Organize & Undo — Auto-zone root folders into the 6 taxonomies, route coursework, and rebalance slack (or run Smart_Organize.bat / ./Smart_Organize.sh for a guided flow):

smart-drive organize --dry-run
smart-drive organize --apply
smart-drive undo --apply        # revert the latest organize/classify batch & relink back

Moving folders without breaking coding agents, IDEs, or shortcuts — organize --apply and classify --apply relink automatically. After moving folders by hand (or via menu option [8] in SmartDrive), run:

smart-drive relink --find --apply --ask --wait
smart-drive relink "E:\Old\proj" "E:\New\proj" --wait
smart-drive paths --broken      # scan for broken IDE entries, agent configs, and .lnk shortcuts

Clean (with quarantine & restore) — Preview junk first (mandatory dry-run default). --apply deletes regenerable OS metadata and build caches (Tier 1-2) at once; only logs, temp files, and dumps (Tier 3) go to a restorable .smart_drive/quarantine/:

smart-drive clean                      # dry-run preview (Tier 1 by default)
smart-drive clean --tier 2             # dry-run preview of Tier 1-2: what --apply would delete permanently
smart-drive clean --apply --tier 3     # delete Tier 1-2 junk, quarantine Tier 3 junk
smart-drive clean --list-quarantine
smart-drive clean --restore latest

Audit & HTML Treemap — Inspect storage and cluster slack using actual volume cluster geometry, or export a self-contained offline HTML treemap:

smart-drive audit
smart-drive audit --html

Health (Sentinel) — Verify mount, filesystem geometry, shields (auto-healed), index, and Git status:

smart-drive sentinel
smart-drive health

Snapshot and backup — Create streaming SHA-256 manifests to detect bit rot and run incremental backups:

smart-drive snapshot create pre_release
smart-drive snapshot verify pre_release
smart-drive backup --target E:\Backups\SSD_Mirror --dry-run

Why exFAT Needs This

High-capacity external SSDs (such as the Kingston XS2000 2 TB) format exFAT with 512 KB (524,288-byte) clusters:

• Physical allocation is $\lceil \text{File Size} / 524,288 \rceil \times 524,288\text{ B}$ (0 B $\rightarrow$ 0 B; 1 B $\rightarrow$ 512 KB / 99.9998% slack; 10 KB $\rightarrow$ 512 KB / 98.05% slack; 100 KB $\rightarrow$ 512 KB / 80.47% slack; 512 KB + 1 B $\rightarrow$ 1,024 KB / 50% slack).
• A repo with 10,000 source files (15 MB nominal) consumes >5.12 GB on exFAT (>99% cluster slack waste).
• OS indexers (macOS Spotlight mds, Windows Search) write hidden metadata (.DS_Store, Thumbs.db, .fseventsd), causing I/O wear and battery drain.
• Internal secondary SSDs (D:, E:, … on NTFS 4 KB) face C: exhaustion from 50–200 GB AI/dev caches while your secondary drive (D:, E:, …) hosts Windows apps, games, and active SQL Server databases that must never be moved or deleted.

Features at a Glance

CLI Command Reference

All commands run via smart-drive <command>, python -m smart_drive <command>, or py -m smart_drive <command> (Windows when python is not on PATH):

Folder Moves and Coding Agents

Coding agents, IDEs, and desktop shortcuts remember projects and MCP servers by absolute path, and exFAT cannot leave a link at the old place. When organize or classify moves a folder, SmartDrive protects system-referenced folders first and rewrites paths everywhere else:

• System & App Protection (protected_by_system): Before planning any move, SmartDrive scans Windows User/System PATH, Windows Services (ImagePath), Installed Apps (Uninstall registry InstallLocation / DisplayIcon / UninstallString), Startup (Run), .lnk shortcuts (Desktop, Start Menu, Quick Launch, drive root), folders containing unins000.exe / uninstall.exe, and game libraries (SteamLibrary, Riot Games, Epic Games, XboxGames, GOG Galaxy, Battle.net, Ubisoft Game Launcher, EA Games, HoYoPlay, Genshin Impact, LDPlayer). Any matching folder is pinned in place with its exact reason in protected_by_system.
• Keeping a folder of your own in place: organize only moves what lies directly in the drive root, so a folder you keep inside one of the taxonomy folders (for example 03_Development_Projects\my-app) stays where it is. On Windows, a folder is also protected_by_system when a shortcut (.lnk) on the Desktop, in the Start Menu or on the taskbar points at it or at something inside it: organize, classify, clean and dup leave it alone, and organize --dry-run lists it as skipped. A shortcut in the drive root counts too, but classify --apply files loose root files, .lnk included, and the protection leaves with the shortcut.
• Agent, IDE & Shortcut Settings: Claude Code (~/.claude.json), Claude desktop (config, sessions, worktrees, including Microsoft Store MSIX), Codex (config.toml), Gemini CLI, Antigravity, Cursor, Windsurf, VS Code, VSCodium, Positron (storage.json and SQLite state.vscdb), JetBrains IDEs (recentProjects.xml including $USER_HOME$ macros), Obsidian (obsidian.json), Windows .lnk shortcuts, Constellation manifest, and the drive's .mcp.json. Each file is backed up to <file>.bak.smart-drive before writing; SQLite state.vscdb is skipped with a warning (busy_apps) if the IDE currently holds it open.
• History and repositories: Claude Code history and memory move to the new project folder, git worktrees are repaired, and editable installs in a moved .venv point at the new place.
• Locked folders (git fsmonitor): Windows refuses to rename a folder while a process holds a handle inside it, and a repository with core.fsmonitor=true gets a background git fsmonitor--daemon that does exactly that after its first git status ([WinError 5] Access is denied). SmartDrive's own git commands run with -c core.fsmonitor=false, so they never start one, and every move stops the daemons of the repositories inside the folder first (--dry-run lists them as fsmonitor_to_stop, --apply reports fsmonitor_stopped; git starts a daemon again by itself at the next git status). If a move is still refused, the error says what may be holding the folder: a program, a terminal, an Explorer window or a daemon that is still running, and on Windows the processes that have files of the folder open. Windows also refuses to rename a folder while anything below it is open, so a read-only probe (at most 8 levels, 20,000 entries and 5 seconds; it renames and keeps open nothing) tries to open every folder and file exclusively and names the deepest ones that are in use (in use: E:\project\...\Images, and in_use in the --json output of organize, undo, classify and the MCP tool ssd_auto_organize). When a folder inside is pinned in Explorer's Quick Access, the hint says so (Explorer keeps a handle on every pinned folder and opens it again at each logon, so restarting Windows alone does not help): unpin it, then restart Windows Explorer from Task Manager. When no process can be named for what is in use, the hint points at explorer.exe (an open Explorer window or Quick Access) and at Resource Monitor as administrator (resmon → CPU → Associated Handles).
• Reversible Journal (undo): Every batch of moves is recorded in .smart_drive/moves.jsonl (identified by its time) so smart-drive undo --apply can move the latest organize/classify batch back and relink agents/IDEs/shortcuts to the original paths. Moves logged by relink and paths are not undoable.

How to run it:

smart-drive organize --dry-run                           # preview moves, protected folders, and which agents/IDEs follow
smart-drive organize --apply                             # move, then relink agents, IDEs, Obsidian, and shortcuts
smart-drive undo                                         # preview reversing the latest move batch
smart-drive undo --apply                                 # undo the latest batch and relink back to original paths
smart-drive relink                                       # re-apply latest batch (after closing an open IDE/agent)
smart-drive relink "E:\Old\proj" "E:\New\proj" --dry-run # a folder moved by hand: preview
smart-drive relink "E:\Old\proj" "E:\New\proj"           # ...then apply
smart-drive relink --find                                # list stale agent/IDE paths and where folders went
smart-drive relink --find --apply --wait                 # relink sure (?) matches after open apps close
smart-drive relink --find --apply --ask --wait           # ...and ask y/N for each ? match first
smart-drive paths --broken                               # inspect broken shortcuts, IDE entries, PATH, and agent configs
smart-drive paths --broken --fix                         # repair sure matches via relink

Menu option [8] in SmartDrive (or [10] / Smart_Organize.* for the guided organizer with 1-key U undo) handles this interactively, and [11] re-applies the latest organize/classify batch: it previews smart-drive relink --dry-run, asks [y/N], then runs smart-drive relink --wait. Use [11] after running organize --apply from inside a coding agent: quit the agent first (a running one may write its old paths back), then open SmartDrive and pick [11]. Close open coding agents and IDEs before relinking, or pass --wait so SmartDrive waits for them to close, then reopen them. If a command in a moved .venv still points at the old place, run uv sync --reinstall in that project.

--find marks a folder ✓ only when the move journal, or what the agents remember inside the old folder, shows where it went. A folder found by its name alone is marked ? and never relinked by --apply on its own, since it may be another project and the old one deleted: check it, then run the smart-drive relink "OLD" "NEW" command printed next to it. Or add --ask (menu option [8] does): it asks Relink OLD -> NEW? [y/N] for each ? folder with one candidate, and relinks the ones you answer y together with the ✓ ones. Enter means no. It asks only in a terminal: with --json or piped input it asks nothing.

MCP Server & AI Coding Agents

SmartDrive-OS exposes a JSON-RPC 2.0 stdio MCP server with 9 tools:

1. ssd_search: Instant FTS5 search returning compact tokens (<2,000 tokens/query). (read-only)
2. ssd_audit: Storage breakdown and cluster slack waste analytics with compact formatting. (read-only)
3. ssd_clean: Whitelist-protected safe junk cleaner with dry-run support. A sub_dir is judged like the whole-drive scan, folders above it included: inside an installed app nothing is scanned and scan_skipped names the folder and why; the result also lists what was kept and the protected_by_system folders. (destructive)
4. ssd_find_duplicates: 3-phase SHA-256 duplicate detection with pagination and preview capping. min_size drops small files before anything is hashed, slack is worked out at the drive's real allocation unit (cluster_size), and a sub_dir inside an installed app or a dependency tree is not scanned (scan_skipped). (read-only)
5. ssd_update_index: Fast incremental index synchronization (<2s). (idempotent)
6. ssd_check_safety: exFAT compatibility validator (9 Win32 forbidden chars, 22 DOS stems, symlinks). (read-only)
7. ssd_status: SSD mount root status, shield health, and taxonomy status. (read-only)
8. ssd_auto_organize: Autonomous drive auto-zoning and anti-slack relocation with AcademicClassifier. (destructive)
9. ssd_gitignore: Stack-aware .gitignore governance, personal data defense, secrets audit, and safe untracking. (idempotent)

Register across all agents via smart-drive mcp register --all (or smart-drive mcp-config --all). A pipx or pip install registers its own Python, a uvx smart-drive-os run registers uvx smart-drive-os mcp, and from a source checkout (without pip install) each entry sets PYTHONPATH to the checkout so clients can launch from any folder. Templates in configs/: .mcp.json (workspace), mcp_config.json (Antigravity), claude_desktop_config.json (Claude Desktop & Code), cursor_mcp.json (Cursor / Codex), windsurf_mcp.json (Windsurf).

Search Syntax

The SQLite FTS5 engine (unicode61 + BM25) executes multi-criteria queries in <10ms:

• Free Text: smart-drive search "machine learning"
• File Extension: smart-drive search "weights ext:gguf"
• Size Filter: smart-drive search "dataset size:>100MB" (size:<1MB, size:0). >/< exclude the bound, >=/<= include it; binary units (1KB = 1024 bytes). Unreadable filters (size:>abc, size:>10 MB) emit a warning (CLI stderr, MCP warnings) instead of being ignored silently.
• Taxonomy Category: smart-drive search "llama cat:ai_models"
• Directory Constraint: smart-drive search "assignment dir:FPTU"
• Learning Kind: smart-drive search --kind slide "vòng lặp" (or kind:fact, --kind capture, --kind lesson)
• Compound Query: smart-drive search "exam ext:pdf size:>1MB dir:DBI202"

Learning Materials (Aurora Slides and Polaris)

SmartDrive-OS integrates with Aurora Slides MCP and Polaris MCP across the DuongNAD learning ecosystem:

SmartDrive-OS serves Polaris (learning search), Sirius, and Rigel (file discovery), receives post-write updates (smart-drive update <dir> --quiet) from Aurora ($\ge$ 0.6.2), Polaris ($\ge$ 0.3.2), and Mira, and enforces the personal-data ignore rules of Constellation's contracts.

Gitignore Governance

smart-drive gitignore audits and applies stack-aware .gitignore rules across Git repos on the drive (<5ms shallow detection for Python, Node.js, Jupyter, Java, Rust, .NET, LaTeX, AI Models, Learning). It maintains an idempotent block between # >>> smart-drive managed (do not edit inside) >>> and # <<< smart-drive managed <<<, preserving user rules and CRLF/LF line endings:

• exFAT Cluster Slack Defense: Ignores **/.agents/* (500+ scratch files waste >260 MB on 512 KB clusters; .agents/skills/, .agents/workflows/, .agents/rules/ stay tracked), .claude/settings.local.json, __pycache__/, .pytest_cache/, node_modules/, target//dist//bin//obj/.
• Constellation personal-data Protection: Locks down .vega/, **/progress.jsonl, aurora-progress-*.jsonl, orion-attempts.jsonl, **/polaris/.cache/, **/polaris/captures/, .polaris/, and .sirius/, alerting if tracked in public or unconfigured remotes.

smart-drive gitignore audit                                 # audit own & local repos (--all includes third-party)
smart-drive gitignore apply D:\teamwork_projects\my_project # dry-run preview
smart-drive gitignore apply D:\teamwork_projects\my_project --yes --untrack

Safe Junk Cleaner

Purgeable files are grouped into 3 tiers with a mandatory dry-run default (--apply required to move or delete):

1. Tier 1 (Safe OS Metadata & Bytecode): macOS .DS_Store, ._* AppleDouble, .Spotlight-V100, .Trashes, .TemporaryItems; Windows Thumbs.db, desktop.ini, ehthumbs.db, ehthumbs_vista.db, $RECYCLE.BIN; Python __pycache__, *.pyc, *.pyo.
2. Tier 2 (Developer Caches): .pytest_cache, .ruff_cache, .mypy_cache, .tox, .nox, .coverage, htmlcov, *.egg-info; build, dist and .cache folders next to a project file; legacy polaris/.cache/**.
3. Tier 3 (Transient & Dumps): *.tmp, *.temp, *.swp, *.swo, *~, *.dmp, core and core.<pid> (a Unix core dump; core.py or core.js is a source file and never matches), hs_err_pid*.log.

clean lists only what is really regenerable. It never lists anything of Tier 2-3 inside a dependency folder (node_modules, bower_components, site-packages, .venv, vendor...): that is installed package code, and npm install does not notice a deleted dist/. It never lists anything inside a folder that Windows or an installed app depends on (the same protected_by_system index organize uses: PATH, Services, Installed Apps, shortcuts, uninstallers). A build, dist or .cache folder counts only when a project file (package.json, pyproject.toml, Cargo.toml, go.mod, pom.xml, *.csproj...) lies beside it, and a Tier 2-3 entry that git tracks (or sits in a repository git cannot be asked about) is kept. The report says how many look-alikes were kept and why (kept and protected_by_system in --json).

smart-drive clean --apply permanently deletes Tier 1 and Tier 2 items at once: they are regenerable (OS metadata, build caches), so they are never quarantined, and nothing can bring them back. Preview with smart-drive clean --tier 2 first (smart-drive checkup recommends the same order). Only Tier 3 items (--tier 3: temp files, swap files, crash dumps) move into a reversible quarantine batch under <root>/.smart_drive/quarantine/<batch_id>/ (with manifest.json) instead of being unlinked:

• Quarantine Tier 3 junk alone and delete nothing else (--tier 3 --apply also deletes every Tier 1-2 item permanently): preview with smart-drive clean --only-tier 3, then run smart-drive clean --only-tier 3 --apply
• Inspect quarantined batches: smart-drive clean --list-quarantine
• Restore a batch to its original paths: smart-drive clean --restore latest (or --restore <batch_id>)
• Permanently purge old quarantine batches: preview with smart-drive clean --purge-quarantine, then smart-drive clean --purge-quarantine --apply permanently deletes the batches older than 30 days (--older-than <days> sets another age, and --older-than 0 purges every batch)
• Delete Tier 3 items outright instead of quarantining them (for example when free space is critically low): smart-drive clean --apply --tier 3 --no-quarantine

Inviolable Whitelist: Root manifests (AGENTS.md, GEMINI.md, CLAUDE.md, README.md, PRIVACY.md), launcher scripts (Setup_*, Quick_*, Smart_Organize.*, SmartDrive.*), the 6 taxonomies, Windows folders (WindowsApps, Program Files, DumpStack.log.tmp), system-referenced folders (protected_by_system: Windows PATH, Services, Installed Apps, Startup, .lnk targets, uninstallers), game libraries (SteamLibrary, Riot Games, Epic Games, XboxGames, GOG Galaxy, Battle.net, Ubisoft Game Launcher, EA Games, HoYoPlay, Genshin Impact, LDPlayer), active SQL Server databases (Microsoft SQL Server 2022), and smart-drive-os are permanently protected.

Snapshots and Backup

• SHA-256 Snapshots (smart-drive snapshot): Streaming 64 KB-chunk ($O(1)$ memory) point-in-time manifests in .smart_drive/snapshots/<name>.json to detect bit rot or tampering.
• Incremental Backup (smart-drive backup): Copies modified/new files while excluding OS junk. Default coverage: 02_Learning_Knowledge, 03_Development_Projects, 05_Dev_Toolbox (override with --partitions); hidden dirs (.git, .github, .vscode) are skipped unless --include-hidden is passed, and every run lists what was not covered.
• Duplicates (smart-drive dup) & Git Clones (smart-drive repos): 3-phase SHA-256 duplicate finder (hard links counted once; node_modules, virtualenvs, caches and installed apps are never scanned) and read-only Git clone auditor checking SSD-vs-machine mirrors (commit, push, pull, fetch to compare) and same-drive duplicates (newest commit to keep, redundant same-branch copies, or git worktree with --relative-paths on git 2.48+; dirty/unpushed/stashed clones are blocked from removal).

Workstation Hybrid and C-Drive Offload

FilesystemAdapter and DriveDetectorBackend adapt between exFAT 512 KB (slack guard, anti-symlink rules, Spotlight/FSEvents shields) and NTFS 4 KB (4,096-byte math, fsutil TRIM check, C: cache offload). smart-drive offload migrates heavy caches (HuggingFace, Ollama, PyTorch, Docker WSL2, pip, uv, npm, Conda, Gradle, Cargo) from C: to <target>\04_System_Offload_Caches\<name> on your secondary drive (D:, E:, …) in a 7-phase transactional workflow with running-process detection (--wait, --force), rollback safety, and unprivileged NTFS Directory Junctions (mklink /J). See README_INTERNAL.md.

Launchers

All 24 portable launchers reside in both the repo root and launchers/ (zero Git required):

smart-drive self-path-check checks the running Python environment (venv, pyenv, user scripts) and prints the PowerShell SetEnvironmentVariable, ~/.bashrc/~/.zshrc export, or pyenv rehash command if smart-drive is not on PATH.

Profiles

Testing

1,150+ automated tests run in CI on Windows, macOS and Linux with Python 3.9 and 3.13 using unittest:

python -m unittest discover tests -v

Coverage spans gitignore governance (ownership, intentional build outputs, negations, keep lists, gh visibility, secret variable names, CRLF preservation, staged-change guard), atomic learning units, system reference protection (protected_by_system), agent/IDE/Obsidian/shortcut relinking (storage.json, state.vscdb, recentProjects.xml, .lnk, MSIX Claude desktop, --find, --wait), undo, checkup, paths --broken, clean quarantine/restore, HTML treemap audit, Smart_Organize (SD_SELFTEST=1), cluster geometry (512 B–32 MB), self-defense, and AcademicClassifier.

Privacy, Security & Data Isolation

SmartDrive-OS is engineered with a local-first, zero-trust architecture:

• 100% Local-Only Operations: All scanning, SQLite FTS5 indexing, and SHA-256 snapshotting run exclusively on local storage.
• Zero Telemetry & Zero PII Logging: No analytics, network beacons, or harvesting of file contents/secrets; only basic metadata is stored in .smart_drive/index.db.
• Air-Gap Ready & Defensive Safeguards: Zero external pip dependencies (dependencies = []), local stdio MCP transport, offline setup --no-clone, mandatory dry-run cleanup defaults, and an inviolable whitelist (AGENTS.md, CLAUDE.md, GEMINI.md, README.md, PRIVACY.md).

For full details and compliance specifications, read PRIVACY.md.

Contributing & License

• 🌟 Star & Fork on GitHub: DuongNAD/smart-drive-os · 🐛 GitHub Issues · 🔀 Pull Requests · 📖 CONTRIBUTING.md
• 📄 Licensed under the MIT License — see LICENSE.