diskguts

Cross-platform terminal disk usage explorer.

diskguts is a CLI utility for understanding disk space usage through categorization and terminal-native visualization. It helps you answer practical questions: Where did my space go? Which directories are consuming the most storage? What kinds of files dominate this path?

The default mode is a navigable TUI built on Ink — richer than plain du output while remaining recognizably a CLI tool. A structured report mode (--report) is available for scripting and piping.

Installation

npm install -g diskguts

Usage

diskguts [path...] [flags]

When no path is given in TUI mode, diskguts defaults to the current working directory. Multiple paths are supported in report mode only; passing more than one path in TUI mode is a fatal error.

Flags

| Flag | Description | |---|---| | --report[=format] | Emit non-interactive output. Format: json (default), md, or txt. Must use = (e.g. --report=md). | | --allocated | Use allocated (on-disk) size instead of apparent size. | | --cross-device | Cross filesystem/volume boundaries during scan. | | --max-depth=N | Limit report tree depth to N levels. No effect in TUI mode. | | --version | Print version string and exit. | | --help, -h | Print usage summary and exit. |

Exit Codes

| Code | Meaning | |---|---| | 0 | Success | | 1 | Fatal error (bad arguments, unreadable path, scan failure) | | 2 | Usage error (invalid flag or unrecognised argument) |

TUI

The TUI has two surfaces — a tree view and a detail view — with three layout modes cycled via \:

| Mode | Description | |---|---| | Single | One pane at a time; Tab swaps between tree and detail. | | Split Horizontal | Tree on the left, detail on the right. | | Split Vertical | Tree on top, detail below. |

Starting State

| Invocation | Starting state | |---|---| | No path | Single layout, tree view, root = cwd | | Single path | Single layout, detail view of the given path | | Multiple paths | Fatal error — use --report instead |

Keybindings

| Key(s) | Action | |---|---| | ↑ / k | Move selection up | | ↓ / j | Move selection down | | → / l / Enter | Enter directory or focus detail view | | ← / h / Backspace | Go to parent directory | | g / Home | Jump to top of list | | G / End | Jump to bottom of list | | Ctrl+U / Page Up | Scroll up half page | | Ctrl+D / Page Down | Scroll down half page | | Tab | Toggle tree/detail (single layout) or shift pane focus (split) | | \ | Cycle layout mode | | s | Cycle sort order | | w | Toggle warnings panel | | ? | Show help overlay | | q | Quit |

Report Output

JSON (--report or --report=json)

Emits a versioned JSON object (schema_version: "1") with scan metadata, category summary, and a fully recursive directory tree. Suitable for piping and scripting.

diskguts ~/projects --report=json | jq '.category_summary'
diskguts ~/projects ~/downloads --report > scan.json

Markdown (--report=md)

Human-readable report with a summary table, category breakdown, top-level directory listing, and warnings section.

Plain Text (--report=txt)

Same structure as the Markdown report but formatted for plain terminal output — column-aligned, no Markdown syntax. Suitable for logging and terminals without Markdown rendering.

Categorization

Files are grouped into categories based on their extension (applied immediately during scan) and optionally refined by MIME sniffing (applied asynchronously on inspection in TUI mode). MIME result always wins when it differs from the extension result.

| Family | Categories | |---|---| | Media | Video, Audio, Images | | Written | Text, Documents | | Storage | Archives, Disk Images, Installer | | Technical | Code, Data, Executable, Binary | | Standalone | Fonts | | Other | Unknown (dull grey) |

Files with no matching extension and no determinable MIME type fall into Unknown. Unknown is a first-class category — never silently discarded.

In report mode, categorization runs eagerly on all files before output is emitted using extension-based rules only (MIME sniffing is not performed in v1 report mode).

Scan Model

diskguts uses a split-eagerness scan strategy:

• Size data is scanned eagerly in the background from launch. The TUI reflects data as it arrives.
• Categorization is lazy in TUI mode — deferred until you inspect a specific file or directory.

The scan queue is viewport-priority: the current directory and its immediate children are always at the front. Navigation events re-prioritize the queue toward newly visible content, keeping the TUI responsive regardless of tree size.

Size totals are monotonically increasing — they never decrease as new content is discovered. Row ordering locks in once a directory's immediate scan completes and never changes thereafter, preventing visual jitter during exploration.

Measurement Modes

| Mode | Description | |---|---| | Apparent size (default) | Logical size of file contents. | | Allocated / on-disk size | Actual space consumed on disk. Use --allocated. |

The active measurement mode is always labeled in output.

Platform Support

Windows, macOS, and Linux are all first-class targets.

| Platform | Behavior | |---|---| | Windows | Reparse points (symlinks, junctions, mount points, other) are reported-but-not-traversed. Sparse files detected via FILE_ATTRIBUTE_SPARSE_FILE. Permissions shown as owner + simplified ACL summary. | | macOS / Linux | Symlinks reported-but-not-traversed. Sparse files inferred from stat comparison (labeled Potentially Sparse). Permissions shown as mode string + owner/group. |

diskguts does not cross filesystem/volume boundaries by default. Use --cross-device to unlock mount point traversal. This flag does not affect symlinks, junctions, or other reparse point types.

Guarantees & Invariants

• Read-only. diskguts never modifies files, directories, or metadata.
• No silent partial reporting. Skipped, inaccessible, and unknown content is always surfaced explicitly.
• Deterministic categorization. A given file always produces the same category for a given ruleset.
• No silent redirect traversal. Symlinks, junctions, mount points, and reparse points are always reported in place and never traversed.
• Fatal failures exit non-zero with a message to stderr in the form: diskguts: <message>.

Development

npm install
npm run build       # production build via tsup
npm run dev         # watch mode
npm run test        # run tests via vitest
npm run typecheck   # type-check without emitting

License

See LICENSE.