StorOps

English | 简体中文

Storage Operations for AI Agents.

See where your storage goes. Understand why. Move what matters. Clean what doesn't.

StorOps is an agent skill (storops) that lets AI coding agents — Claude Code, Codex, OpenCode, etc. — safely understand and manage local storage across Windows, Linux, and macOS (see Status below for per-platform maturity notes).

It is not another disk analyzer and not another disk cleaner. WizTree already answers "what is taking up space." StorOps answers the questions after that: what is this, why is it here, can it be deleted, should it be moved, where to, how to do it safely, and how to verify it worked.

Discover → Understand → Diagnose → Recommend → Plan → Execute → Verify
 WizTree     Identify     Analyze

See docs/DESIGN.md for the full product design and SKILL.md for the agent behavior contract.

Status

MVP. Windows is the most mature target. WizTree is used as a storage-discovery backend where it actually wins — StorOps never re-implements disk/MFT scanning, and never drives the WizTree GUI (no automation, screenshots, or OCR): it only calls WizTree64.exe from the command line and parses its CSV export — but only for a whole-drive scan (e.g. C:\) on an elevated process. Live measurement found WizTree's CLI export reads the entire volume's file table regardless of how small the requested target is, so for anything narrower (which most scan/inspect/ search targets are) that fixed cost isn't amortized and it measurably loses to StorOps' own parallel native scan, by 2x-10x depending on target size — so everything else uses the native scan instead, WizTree or not. Linux/macOS support is newer and uses gdu (falling back to the system du) behind the same scan-backend interface — see docs/DESIGN.md §4a. Identification rules for AI-model/ app/cache paths (rules/ai-models.yaml, applications.yaml, caches.yaml) are still Windows-token-only; only the critical-system-path rules (rules/windows.yaml/linux.yaml/macos.yaml) currently have per-platform coverage.

Requirements

• Python 3.9+ — the only implementation (src/storops/); python3/ python needs to be on PATH. 3.9 is the floor deliberately: it is what a stock macOS ships as python3, and StorOps is most useful on a machine nobody has set a modern toolchain up on yet. No pip install is required for the common "cloned into a skills directory" install path — python -m storops works straight out of the checkout.
• Windows: NTFS volumes. WizTree is optional — StorOps' own native scan (os.scandir, parallelized across the scanned tree with a work queue; $env:STOROPS_SCAN_WORKERS tunes the thread count, 1-64, default 8) is used for everything except a whole-drive scan on an elevated process, the one scope WizTree's CLI export was actually measured to win at (see Status above); install it (WizTree64.exe on PATH, in a standard install location, found via its own install-location registry entry, or pointed to via $env:STOROPS_WIZTREE_PATH) if you regularly run whole-drive scans elevated, skip it otherwise. Note WizTree is free for personal use only — commercial/organizational use requires a license.
• Linux/macOS: gdu recommended (brew install gdu / apt install gdu / see its install docs) for a parallel, much faster scan; StorOps falls back to the system du automatically if gdu isn't found (with a one-time warning — du is noticeably slower on large trees). Point at a specific binary via $env:STOROPS_GDU_PATH if it's not on PATH. No elevation is ever required or auto-applied.

Installation

StorOps is a plain agent skill: a directory with a SKILL.md at its root, discovered by name and description rather than invoked as a slash command. No build step and no pip install required — the agent reads SKILL.md to decide when to use the skill, then invokes python -m storops <verb> directly. The only runtime requirements are Python 3.9+ and, on Windows, WizTree — see Requirements above.

Ask your agent to install it (recommended)

Paste this into any AI coding agent chat (Claude Code, Codex, Cursor, etc.) and let it figure out the right method for your setup:

Install the "storops" agent skill from https://github.com/tzzs/storops
using whichever method fits the agent I'm running in, then confirm it
loaded.

Any skill-aware agent — npx skills add

skills is a community CLI that installs a SKILL.md from any public GitHub repo into an agent's skills directory (.claude/skills/, .agents/skills/, etc.):

npx skills add tzzs/storops
# or, to install for every project on this machine:
npx skills add tzzs/storops -g

Claude Code — plugin marketplace

The repo carries its own .claude-plugin/marketplace.json, so it can be added as a marketplace and installed directly from inside Claude Code:

/plugin marketplace add tzzs/storops
/plugin install storops@storops

Codex — skill installer

Codex ships an official skill-installer skill that installs any skill from a GitHub URL. From inside Codex:

$skill-installer install https://github.com/tzzs/storops

Manual

Clone it directly into a skills directory the agent scans:

# Project-level (this checkout only)
git clone https://github.com/tzzs/storops.git .claude/skills/storops

# Personal (all projects)
git clone https://github.com/tzzs/storops.git ~/.claude/skills/storops

Calling it

StorOps is implemented in Python (src/storops/), exposed as a single unified CLI with one subcommand per capability:

python -m storops scan /home/me --json
# or, if the package has been `pip install`-ed: storops scan /home/me --json

The original scripts/*.ps1 entry points and their PowerShell compatibility layer were removed after the v2 Python rewrite settled — see docs/plans/storops-v2-cross-platform-refactor.md §2.10 for why they existed and why removing them was the plan all along. If you have automation still calling scripts/scan.ps1-style entry points, pin to a pre-removal tag or switch to the storops CLI form above — parameter names map 1:1 (-Path → positional/--path, -MaxRisk → --max-risk, -Confirm → --confirm, etc.), see Quick start below for a full worked example.

Layout

SKILL.md            agent behavior contract (when/how to use this skill)
docs/DESIGN.md       full design brief (source of truth for intent/scope)
docs/plans/          detailed design/audit records, e.g. the v2 Python/
                     cross-platform rewrite
rules/               declarative identification + risk rules (YAML),
                     per-platform critical-path files plus shared app/cache rules
src/storops/         the Python implementation: CLI (cli.py), core business
                     logic (core/), platform abstraction (platform/), and
                     output rendering (output/) — see docs/plans/storops-v2-
                     cross-platform-refactor.md §2.2 for the full tree
tests/               pytest suite (tests/unit, tests/integration)

Safety model

Every capability sits in exactly one of three tiers:

Tier	Capabilities	Confirmation
Read	scan, inspect, search, identify, analyze	none — safe to run freely
Plan	cleanup-plan, migrate-plan	none — produces a plan, touches nothing
Write	migrate-execute, cleanup-execute, junction creation	required, always

Nothing that deletes, moves, renames, or reconfigures anything ever runs without an explicit, itemized plan being shown to the user first, and nothing in the CRITICAL risk tier (Windows, Program Files, unknown system paths, user documents, etc.) is ever offered for automatic deletion.

Quick start (agent-driven)

An agent following SKILL.md will typically (examples below use Windows paths; on Linux/macOS pass POSIX paths instead, e.g. / and ~/.cache — scan/search default to / there automatically):

# 1. Read-only: see the big picture
python -m storops scan C:\

# 2. Read-only: drill into a large, unidentified consumer
python -m storops inspect C:\Users\me\AppData\Local

# 3. Read-only: attach meaning to what was found
python -m storops identify C:\Users\me\.lmstudio\models

# 4. Plan-only: build an itemized, risk-classified cleanup plan
python -m storops cleanup plan --max-risk low

# 5. Write, only after the user approves the plan from step 4
python -m storops cleanup execute --plan-file .\storops-cleanup-plan.json --confirm

# 6. Plan-only: build a migration plan for a big, movable directory
python -m storops migrate plan C:\Users\me\.lmstudio\models E:\AI\LMStudio\models

# 7. Write, only after the user approves the plan from step 6 — always verified
python -m storops migrate execute --plan-file .\storops-migrate-plan.json --confirm

# 8. Read-only: re-check the migration's result at any later time
python -m storops verify --result-file .\storops-migrate-result.json

See CHANGELOG.md for a history of notable changes.

License

MIT — see LICENSE.