Skip to main content
Get up and running with Pumu in under 5 minutes. You’ll learn how to scan for heavy dependency folders, perform your first cleanup, and understand the interactive selection workflow.

​
Installation

Choose your preferred installation method: 
brew install carlosedujs/pumu/pumu
Verify the installation: 
pumu --version

pumu version v1.2.1-rc.1

​
Your first cleanup

1

List heavy folders in your workspace

Start by scanning your projects directory to see what’s taking up space. This is a dry-run that won’t delete anything:
cd ~/projects
pumu list
You’ll see a color-coded table showing all dependency folders:
🔎 Listing heavy dependency folders in '.'...
⏱️  Found 3 folders. Calculating sizes concurrently...

Folder Path                                                                       | Size
/home/user/projects/webapp/node_modules                                           | 1.23 GB 🚨
/home/user/projects/rust-app/target                                               | 487.50 MB ⚠️
/home/user/projects/api/.venv                                                     | 89.32 MB
----------------------------------------------------------------------------------------------------
📋 List complete! Found 3 heavy folders.
💾 Total space that can be freed: 1.79 GB
Color coding helps you prioritize:
  • Red (🚨) = Folders over 1 GB (critical space users)
  • Yellow (⚠️) = Folders between 100 MB - 1 GB (moderate)
  • Green = Folders under 100 MB (minor)
2

Sweep with interactive selection

Now let’s clean up those folders. By default, Pumu shows an interactive multi-select so you can choose exactly what to delete:
pumu sweep
You’ll see an interactive TUI selector:
🔎 Scanning for heavy dependency folders in '.'...
⏱️  Found 3 folders. Calculating sizes concurrently...

🗑️  Select folders to delete:
▸ [✓] /home/user/projects/webapp/node_modules       1.23 GB
  [✓] /home/user/projects/rust-app/target            487.50 MB
  [ ] /home/user/projects/api/.venv                  89.32 MB

  2/3 selected
  press ? for help
Navigation shortcuts:
  • ↑/↓ or k/j - Move cursor up/down
  • space - Toggle item
  • a - Select all
  • n - Deselect all
  • i - Invert selection
  • enter - Confirm and delete
  • q or esc - Cancel
Select the folders you want to delete and press enter to confirm.
3

Sweep with reinstall

Want to clean up and automatically reinstall dependencies? Add the --reinstall flag:
pumu sweep --reinstall
This will:
  1. Show the interactive selector for deletion
  2. Delete selected folders
  3. Show another selector asking which projects to reinstall
  4. Automatically detect package managers and run the appropriate install command
Pumu automatically detects package managers by checking lockfiles in this order: bun.lockb, pnpm-lock.yaml, yarn.lock, package-lock.json, Cargo.toml, go.mod, and more.

​
Common scenarios

Preview disk usage

See what’s taking up space across all your projects without deleting anything:
cd ~/dev
pumu list
Perfect for understanding where your disk space is going before taking action.

Clean specific directory

Use the -p or --path flag to scan a specific directory:
pumu sweep -p ~/workspace
Works with all commands: list, sweep, repair, and prune.

Fix broken dependencies

Automatically detect and repair corrupted or broken dependencies:
pumu repair
Pumu checks dependency health using:
  • npm ls --json for npm/pnpm
  • yarn check --verify-tree for yarn
  • cargo check for Rust
  • go mod verify for Go
  • pip check for Python

Bulk cleanup without prompts

Skip the interactive selection and delete all found folders:
pumu sweep --no-select
Use with caution! This immediately deletes all dependency folders without confirmation.

​
Understanding repair mode

Repair mode is powerful for fixing broken projects across your entire workspace: 
pumu repair
Example output: 
🔧 Scanning for projects with broken dependencies in '.'...
⏱️  Found 3 projects. Checking health...

📁 ./webapp (npm)
   ❌ Missing: react, react-dom
   🗑️  Removing node_modules...
   📦 Reinstalling...
   ✅ Repaired!

📁 ./api (pnpm)
   ✅ Healthy, skipping.

📁 ./rust-cli (cargo)
   ❌ Compilation errors detected
   🗑️  Removing target...
   📦 Rebuilding...
   ✅ Repaired!

-----
🔧 Repair complete! Fixed 2/3 projects.
Use pumu repair --verbose to see details for all projects, including healthy ones.

​
Supported dependency folders

Pumu can detect and clean these dependency and build folders:
FolderPackage Manager(s)Typical Size
node_modulesnpm, yarn, pnpm, bun, deno50-500+ MB
targetcargo (Rust)100-2000+ MB
.venvpip (Python virtual env)50-300+ MB
.nextNext.js100-500+ MB
.svelte-kitSvelteKit50-200+ MB
distVarious build tools10-100+ MB
buildVarious build tools10-100+ MB

​
Safety features

Pumu is designed with safety in mind:
  • Interactive selection by default - Choose exactly what to delete via TUI
  • Dry-run with list - Preview before deletion
  • Smart folder detection - Only removes known dependency folders
  • Ignored system paths - Skips .git, .cache, Library, IDE folders, and system directories
  • Concurrent safe operations - Uses mutexes and atomic operations to prevent race conditions
  • Error resilience - Continues processing even if individual operations fail
Pumu automatically skips these directories for safety:
  • .Trash, .cache, .npm, .yarn, .cargo, .rustup
  • Library, AppData, Local, Roaming
  • .vscode, .idea
  • .git (version control)

​
Next steps

Explore sweep command

Learn about all sweep options, flags, and advanced usage patterns

Package manager detection

Understand how Pumu detects package managers and what lockfiles it looks for

Build docs developers (and LLMs) love

Get started for freeTalk to us