> ## Documentation Index
> Fetch the complete documentation index at: https://toolkit.astralsolutions.tech/llms.txt
> Use this file to discover all available pages before exploring further.

# Reclaim Disk Space by Cleaning Dependency Directories

> Scan projects for node_modules, .venv, and other heavyweight dependency folders, preview recoverable gigabytes with dry-run, then purge in one command.

The Toolkit disk cleaner recursively scans your project tree for `node_modules`, `.venv`, `venv`, `env`, and `conda` directories — the heavyweight dependency folders that accumulate across months of development and can consume tens of gigabytes. It calculates exactly how much space you would recover, surfaces orphaned environments without a matching project manifest, and purges everything in a single command.

***

## `toolkit clean scan [targetPath]`

Recursively walk a directory tree and report every `node_modules` and Python virtual-environment folder found. For each directory, Toolkit shows its path, type, size, last-modified date, and whether it appears to be an orphan. At the end you get a total recoverable-size summary broken down by type.

The default scan depth is **5 levels**. Increase it with `--depth` if your project tree is deeply nested.

```bash theme={null}
# Scan the current working directory (depth 5)
toolkit clean scan

# Scan a specific projects folder
toolkit clean scan ~/projects

# Limit recursion to 3 levels deep
toolkit clean scan ~/projects --depth 3

# Output the full report as JSON
toolkit clean scan /var/www --json
```

| Flag                | Type      | Default | Description                                                       |
| ------------------- | --------- | ------- | ----------------------------------------------------------------- |
| `-d, --depth <num>` | `number`  | `5`     | Maximum directory-tree depth to traverse.                         |
| `--json`            | `boolean` | `false` | Emit found targets and total recoverable size as structured JSON. |

**Example terminal output:**

```
Scanning ~/projects (depth: 5) ...

  node_modules   ~/projects/dashboard/node_modules           823 MB   2024-11-03
  node_modules   ~/projects/api-gateway/node_modules         541 MB   2024-10-18
  python_venv    ~/projects/data-pipeline/.venv              312 MB   2024-09-30   [orphan]
  python_venv    ~/projects/ml-tools/venv                    1.2 GB   2024-12-01
  node_modules   ~/projects/old-site/node_modules            214 MB   2023-07-15   [orphan]

─────────────────────────────────────────────────────────────────────
  Total: 5 targets   node_modules: 3 (1.5 GB)   venvs: 2 (1.5 GB)
  Recoverable: 3.1 GB
```

***

## `toolkit clean purge [targetPath]`

Permanently delete the dependency folders discovered during a scan. Purge accepts the same `[targetPath]` argument and `--depth` behaviour as `scan`. Always confirm you know what will be deleted before running a destructive purge.

```bash theme={null}
# Preview what would be deleted — nothing is actually removed
toolkit clean purge --dry-run

# Purge a specific folder tree without interactive confirmation
toolkit clean purge ~/projects --force

# Purge with dry-run and machine-readable summary
toolkit clean purge --dry-run --json
```

| Flag        | Type      | Default | Description                                                                 |
| ----------- | --------- | ------- | --------------------------------------------------------------------------- |
| `--dry-run` | `boolean` | `false` | Safe preview mode — calculates space to be freed without deleting anything. |
| `--force`   | `boolean` | `false` | Skip the interactive confirmation prompt before purging.                    |
| `--json`    | `boolean` | `false` | Emit the purge results as structured JSON.                                  |

<Tip>
  **Always run `--dry-run` first.** Use `toolkit clean purge --dry-run` to see exactly which directories will be removed and how much space you will recover before committing to deletion. This is especially useful in CI or on shared machines.
</Tip>

<Warning>
  **Purge is permanent.** Deleted `node_modules` and virtual-environment folders cannot be recovered from the trash. You can recreate them with `npm install` or `pip install -r requirements.txt`, but the operation itself is irreversible. Always preview with `--dry-run` before purging.
</Warning>

***

## Orphan Detection

During a scan, Toolkit checks each discovered environment for a corresponding project manifest in its parent directory:

* **Node.js** — looks for `package.json`
* **Python** — looks for `pyproject.toml` or `requirements.txt`

If no manifest is found, the environment is flagged as an **orphan** (`isOrphan: true`). Orphans are safe cleanup candidates — they belong to projects that have been moved, deleted, or archived — and they are highlighted in both the scan output and the JSON report.

***

## `--json` Output

```bash theme={null}
toolkit clean scan --json
```

```json theme={null}
{
  "scannedRoot": "/home/alice/projects",
  "totalTargets": 5,
  "totalSizeBytes": 3328548864,
  "totalSizeFormatted": "3.1 GB",
  "nodeModulesCount": 3,
  "nodeModulesSizeBytes": 1659174912,
  "venvCount": 2,
  "venvSizeBytes": 1669373952,
  "orphansCount": 2,
  "targets": [
    {
      "id": "a1b2c3d4",
      "path": "/home/alice/projects/dashboard/node_modules",
      "type": "node_modules",
      "name": "node_modules",
      "sizeBytes": 863272960,
      "sizeFormatted": "823 MB",
      "lastModified": "2024-11-03T14:22:00.000Z",
      "isOrphan": false,
      "details": {
        "projectName": "dashboard",
        "parentDirectory": "/home/alice/projects/dashboard"
      }
    },
    {
      "id": "e5f6g7h8",
      "path": "/home/alice/projects/data-pipeline/.venv",
      "type": "python_venv",
      "name": ".venv",
      "sizeBytes": 327155712,
      "sizeFormatted": "312 MB",
      "lastModified": "2024-09-30T09:11:00.000Z",
      "isOrphan": true,
      "details": {
        "pythonVersion": "3.11.4",
        "parentDirectory": "/home/alice/projects/data-pipeline"
      }
    }
  ]
}
```

The `CleanOperationResult` shape returned per directory by `toolkit clean purge --json`:

```json theme={null}
{
  "path": "/home/alice/projects/dashboard/node_modules",
  "success": true,
  "reclaimedBytes": 863272960,
  "reclaimedFormatted": "823 MB",
  "dryRun": false
}
```