10. Configuration, Themes, and Terminals

Disk usage

See what the Matcha home is using on disk. This is a read of ~/.matcha (or MATCHA_HOME). It does not start the TUI and it does not create a home directory if none exists.

Run it

matcha du
matcha disk-usage

disk-usage is a visible alias of du. Add --json for a machine-readable report (schema_version 1).

If the home is missing, human output is:

Nothing on disk yet at ~/.matcha.

(or $MATCHA_HOME / the path you overrode). JSON then emits an empty report for that path.

If ~/.matcha is absent but a leftover ~/.grok exists, du measures the legacy tree without migrating or creating ~/.matcha.

Read the report

Human output starts with Disk usage for …, then every top-level directory in the home, largest first, then (top-level files) if any, then total.

Typical names: sessions, memory, logs, plugins, worktrees, worktree_pool. Sizes are physical bytes on this volume. Directories on another filesystem are shown as - and are omitted from the total.

A Worktrees table lists clones under worktrees/ and worktree_pool/ with size, type, age, label, and path. Untracked rows are ones the worktree registry does not know. Rows outside the managed worktree directories are counted in a note, not listed.

Unix clones can share blocks with their source, so the printed total can exceed “real” extra disk use. du does not follow a top-level symlink to another directory; those contents are missing from the total.

The command sizes the tree before it opens the worktree registry, so a read-only SQLite open does not inflate the total with -wal / -shm sidecars.

Reclaim space

matcha du never deletes anything.

When worktrees dominate the total, the report suggests:

matcha worktree gc --max-age 7d --dry-run

then the same command without --dry-run. Without --max-age, gc expires nothing. It only visits worktrees the registry tracks; untracked directories you saw in du need a manual delete after you confirm they are unused.

Check your work

  1. matcha du and matcha disk-usage print the same report.
  2. matcha du --json includes grok_home (the resolved home path), total_bytes, and top_level_dirs.
  3. After creating a git worktree from Matcha, du shows it under Worktrees; gc --dry-run lists only registry-tracked entries.