Quickstart

Disk Analyzer - Agent Quickstart

Purpose

Advanced disk usage analysis for local systems with file type aggregation, large file detection, and cleanup recommendations.

When to Use

• When agents need to analyze disk usage patterns
• When identifying large files for cleanup
• When generating storage optimization reports
• When monitoring file type distributions

Basic Usage

Analyze directory usage

disk-analyzer analyze /path/to/directory
disk-analyzer analyze /home/user --depth 3
disk-analyzer analyze /var/log --json

Find large files

disk-analyzer large-files /home/user --min-size 100M
disk-analyzer large-files /var --top 20 --json

Analyze file types

disk-analyzer file-types /home/user/projects
disk-analyzer file-types /var/lib --json

Generate cleanup recommendations

disk-analyzer cleanup-report /home/user
disk-analyzer cleanup-report /var/log --aggressive --json

Machine-Readable Output

JSON format for parsing

disk-analyzer analyze /path --json

Returns structured JSON with version field:

{
  "version": "1.0",
  "path": "/path/to/directory",
  "depth": 2,
  "directories": [
    {"size": "1.2G", "path": "/path/to/large/dir"},
    {"size": "500M", "path": "/path/to/other/dir"}
  ]
}

Options

• --json - Output in JSON format
• --min-size SIZE - Minimum file size (e.g., 100M, 1G)
• --depth N - Directory depth for analysis
• --top N - Show top N results
• --aggressive - More aggressive cleanup recommendations

Common Agent Patterns

Check if directory exceeds size threshold

disk-analyzer analyze /path --json | jq '.directories[] | select(.size | endswith("G"))'

Find files larger than specific size

disk-analyzer large-files /path --min-size 1G --json | jq -r '.files[].path'

Get file type distribution

disk-analyzer file-types /path --json | jq '.file_types'

Generate cleanup report and extract recommendations

disk-analyzer cleanup-report /path --json | jq '.recommendations[] | select(.count > 0)'

Exit Codes

• 0 - Success
• 1 - Error (invalid arguments, directory not found)

Notes

• Uses standard Unix commands (du, find, sort, etc.)
• Works on Linux/macOS systems
• No external dependencies required
• JSON output follows stable schema with version field