Proposal: read-only CLI storage footprint report

[uttamdeb]

CodeBurn warns users that local agent logs accumulate, but it has no CLI view of how much space those logs and CodeBurn's own cache occupy. I would like to add a read-only storage report.

Proposed first scope: a codeburn storage command that reports source file count and bytes by provider, the largest source files, CodeBurn cache bytes, and available disk space where the platform exposes it. It would use existing provider discovery paths and file metadata only, count a physical path once, and handle missing or unreadable paths without failing the whole report. It would not read prompt bodies, delete files, change retention, or claim that any file is safe to remove.

I would test duplicate discovery roots, symlinks, missing paths, and mixed file-backed/SQLite providers. The initial PR can stay focused on the sources the existing discovery API can identify reliably; other stores can be a later follow-up.

Would this be useful? In particular, should the first version include cache and disk-free figures, and should SQLite-backed stores be in the initial scope? I am asking before implementation because CONTRIBUTING.md requests maintainer confirmation for features, and new issue creation appears restricted here.

[UmeshCode1]

This would be a high-value addition to codeburn. Coding agents (especially Claude Code session logs, Cursor workspace storage, and Gemini CLI caches) produce massive JSONL and SQLite footprints that silently balloon to several gigabytes over long pair-programming sessions.

A few architectural and edge-case recommendations for the initial PR scope:

1. Scope & Provider Storage Types

• File-Backed Logs vs SQLite DBs: For file-backed providers (JSONL transcripts), standard directory traversal works well. For SQLite-backed stores (e.g. Cursor's state.vscdb), do not attach or query the DB—simply lstat the database file and its associated -wal / -shm files. This avoids locking conflicts while an agent session is actively running.
• Symlink & Cycle Handling: Use fs.lstat instead of fs.stat to avoid double-counting or infinite recursion on directory symlinks (especially on macOS/Linux developer setups where project roots or cache directories are linked).
• Graceful Degradation on Locked Files: On Windows, active agent processes often hold exclusive file locks. The reporter should trap EACCES / EBUSY / ENOENT on individual paths and increment an unreadable_paths count rather than crashing the overall command.

2. Cache & Disk-Free Metrics

• Include Cache & Disk Space: Having codeburn report its own internal cache footprint (~/.codeburn/cache or platform equivalent) alongside the source logs is essential so users see total ecosystem consumption.
• Relative Context: Providing free disk space (via statvfs on POSIX or native platform bindings) turns an abstract number like "12 GB of logs" into an actionable metric: "Agent logs consume 8.5% of remaining disk capacity".

3. CLI UX & Output

• Support --json output alongside human-readable tabular output (1.4 GB, 250 MB) so developers can pipe this into cron-based disk hygiene scripts or custom monitoring.

Keeping the first version strictly read-only and telemetry-free makes it safe to merge and run in CI/CD developer environments without security risk.

[uttamdeb]

Filed this as feature request #1626 now that issue creation is available. The proposal incorporates metadata-only SQLite/sidecar handling, symlink and access-error reporting, and human/JSON output from the feedback here. Please use the issue for maintainer scope confirmation; I will wait before implementation.