duwatch

  ____  _   _  ____   ___  ____   ___   __   ____
 |  _ \| \ | |/ ___| |_ _|/ ___| / _ \  \ \ / /_ |
 | |_) |  \| | |  _   | || |  _ | | | |  \ V / | |
 |  __/| |\  | |_| |  | || |_| || |_| |   | |  | |
 |_|   |_| \_|\____| |___|\____| \___/    |_|  |_|

Directory size time-series tracker -- record, trend, and alert on disk usage.

English | Japanese | Chinese

Overview

duwatch records directory sizes to a local SQLite database and displays historical trends with ASCII sparklines. Track what grows over time, get alerts when thresholds are exceeded, and understand where your disk space goes.

Zero external dependencies. Pure Python 3.9+.

Demo Output

$ duwatch history ~/projects
Path: /Users/john/projects
Records: 30 (2026-04-08 to 2026-04-15)

 2026-04-08 | 2.1 GB |
 2026-04-09 | 2.1 GB |
 2026-04-10 | 2.2 GB |
 2026-04-11 | 2.4 GB | |
 2026-04-12 | 2.5 GB | |
 2026-04-13 | 2.7 GB | | |
 2026-04-14 | 2.8 GB | | | |
 2026-04-15 | 3.1 GB | | | | |

Latest: 3.1 GB (+47% from 7 days ago)

Features

Command	Description
duwatch track <path>	Scan directory and record to database
duwatch history <path>	Show size trend with ASCII sparkline
duwatch diff <path> --days N	Compare current vs N days ago
duwatch report	Overview of all tracked directories
`duwatch top --by size	growth`
duwatch alert --threshold SIZE	Exit 1 if any tracked dir exceeds threshold

Installation

pip

pip install duwatch

pipx (recommended for isolation)

pipx install duwatch

From source

git clone https://github.com/izag8216/duwatch.git
cd duwatch
pip install -e .

Quick Start

Track a directory

duwatch track ~/projects
# Output:
# Tracked: /Users/john/projects
#   Size: 3,145,728,000 bytes
#   Files: 42,150
#   Dirs: 3,200
#   Record ID: 1

View history with sparkline

duwatch history ~/projects --limit 30

Compare with past snapshot

duwatch diff ~/projects --days 7
# Output:
# Comparison: /Users/john/projects
# Current: 3.1 GB (2026-04-15 10:30)
# Previous: 2.1 GB (2026-04-08 10:30)
# Change: +1.0 GB (+47%)

Alert on threshold

duwatch alert --threshold 5GB
# Output:
# OK: All directories within threshold.
# Exit code: 0

# If exceeded:
# ALERT: /Users/john/projects (6.2 GB > 5.0 GB threshold)
# Exit code: 1

See all tracked directories

duwatch report

Find largest directories

duwatch top --limit 10 --by size
duwatch top --limit 10 --by growth

Cron Setup

Automate tracking with cron:

# Edit crontab
crontab -e

# Add daily tracking at 9 AM
0 9 * * * /usr/local/bin/duwatch track ~/projects

# Add weekly alert check
0 10 * * 1 /usr/local/bin/duwatch alert --threshold 10GB || echo "Disk alert!" | mail -s "duwatch alert" admin@example.com

How It Works

                    duwatch track ~/projects
                                 |
                                 v
  +------------------+    +----------------+    +------------------+
  |   Scanner        | -> |   Database     | -> |   Display        |
  |                  |    |   (SQLite)     |    |   (Sparklines)   |
  |  - Walk tree     |    |  - scans table |    |  - Unicode bars  |
  |  - Count files   |    |  - Indexes     |    |  - Size formats  |
  |  - Skip hidden   |    |  - Timestamps  |    |  - Tables        |
  +------------------+    +----------------+    +------------------+
                                 |
                                 v
                         +------------------+
                         |   CLI            |
                         |   (argparse)     |
                         |                  |
                         |  - track          |
                         |  - history        |
                         |  - diff           |
                         |  - report         |
                         |  - top            |
                         |  - alert          |
                         +------------------+

Database Schema

CREATE TABLE scans (
    id INTEGER PRIMARY KEY AUTOINCREMENT,
    path TEXT NOT NULL,
    size_bytes INTEGER NOT NULL,
    file_count INTEGER NOT NULL,
    dir_count INTEGER NOT NULL,
    scanned_at TEXT NOT NULL
);

CREATE INDEX idx_scans_path ON scans(path);
CREATE INDEX idx_scans_scanned_at ON scans(scanned_at);

Hidden Directories

Scanner automatically skips these common directories:

• .git/
• .venv/
• venv/
• node_modules/
• __pycache__/
• .pytest_cache/
• Any directory starting with .

Contributing

Contributions are welcome! Please see CONTRIBUTING.md for guidelines.

License

MIT License - see LICENSE for details.

Repository

https://github.com/izag8216/duwatch

Author

izag8216