If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/Byron/dua-cli shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

GO — Healthy across the board

• Last commit 3mo ago
• 17 active contributors
• MIT licensed
• CI configured
• Tests present
• ⚠ Concentrated ownership — top contributor handles 73% of recent commits

_{Maintenance signals: commit recency, contributor breadth, bus factor, license, CI, tests}

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live Byron/dua-cli repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/Byron/dua-cli.

What it runs against: a local clone of Byron/dua-cli — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in Byron/dua-cli | Confirms the artifact applies here, not a fork | | 2 | License is still MIT | Catches relicense before you depend on it | | 3 | Default branch main exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 107 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of Byron/dua-cli. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/Byron/dua-cli.git
#   cd dua-cli
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of Byron/dua-cli and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "Byron/dua-cli(\\.git)?\\b" \\
  && ok "origin remote is Byron/dua-cli" \\
  || miss "origin remote is not Byron/dua-cli (artifact may be from a fork)"

# 2. License matches what RepoPilot saw
(grep -qiE "^(MIT)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"MIT\"" package.json 2>/dev/null) \\
  && ok "license is MIT" \\
  || miss "license drift — was MIT at generation time"

# 3. Default branch
git rev-parse --verify main >/dev/null 2>&1 \\
  && ok "default branch main exists" \\
  || miss "default branch main no longer exists"

# 4. Critical files exist
test -f "src/main.rs" \\
  && ok "src/main.rs" \\
  || miss "missing critical file: src/main.rs"
test -f "src/traverse.rs" \\
  && ok "src/traverse.rs" \\
  || miss "missing critical file: src/traverse.rs"
test -f "src/aggregate.rs" \\
  && ok "src/aggregate.rs" \\
  || miss "missing critical file: src/aggregate.rs"
test -f "src/interactive/app/mod.rs" \\
  && ok "src/interactive/app/mod.rs" \\
  || miss "missing critical file: src/interactive/app/mod.rs"
test -f "src/interactive/app/eventloop.rs" \\
  && ok "src/interactive/app/eventloop.rs" \\
  || miss "missing critical file: src/interactive/app/eventloop.rs"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 107 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~77d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/Byron/dua-cli"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

dua is a Rust-based disk usage analyzer that scans directories in parallel to identify and visualize large files/folders, with an optional terminal UI (TUI) built on Ratatui and the ability to rapidly delete unwanted data via trash integration. It solves the problem of slow, sequential disk analysis by leveraging concurrent traversal and provides both CLI and interactive modes for analyzing disk space consumption. Single-binary Rust project: src/main.rs and src/lib.rs form the entry points; src/interactive/ contains the TUI state machine (app/, widgets/) built on Ratatui with terminal handling (terminal.rs), event loop (eventloop.rs), and navigation logic (navigation.rs); src/ has core logic (traverse.rs for parallel directory walking, aggregate.rs for size computation, inodefilter.rs for deduplication, crossdev.rs for cross-filesystem handling). Tests live in src/interactive/app/tests/ and tests/ fixtures.

Systems administrators, developers, and Linux/macOS/Windows users who need to quickly identify disk space hogs on their machines and safely reclaim storage without learning complex find or du command syntax. Contributors are primarily Rust developers maintaining a cross-platform CLI tool with TUI capabilities.

Production-ready and actively maintained. The project is at v2.34.0 with comprehensive test coverage (src/interactive/app/tests/ includes journeys_readonly.rs, journeys_with_writes.rs, and unit tests), professional CI via GitHub Actions (rust.yml, release.yml), and multiple platform-specific installers. Regular releases and active dependency updates indicate ongoing stewardship.

Low risk overall, though watch for: the single-maintainer pattern (Byron as primary contributor visible in the repository), relatively large dependency tree (clap, ratatui, petgraph, jwalk, trash, gix-glob, etc.) that could introduce supply-chain concerns, and the nightly Rust requirement for Windows builds (noted in README). Breaking changes are documented in CHANGELOG.md, and the tui-crossplatform feature flag provides a fallback without TUI dependencies.

The project is in active maintenance mode. Current focus appears to be on: Rust edition 2024 adoption (in Cargo.toml), dependency updates (ratatui 0.26.1, clap 4.0.29, jiff 0.2.18 for date handling), and stability improvements across platforms. CI pipelines validate on multiple OSes and target architectures via GitHub Actions. No specific active development of major features is visible, but the codebase is healthy and responsive to changes.

git clone https://github.com/Byron/dua-cli.git
cd dua-cli
cargo build --release
./target/release/dua --help
# Run the interactive TUI
./target/release/dua /path/to/scan

For development with full TUI features: cargo build --features tui-crossplatform. Without TUI (most compatible): cargo build --no-default-features.

Daily commands: Dev build: cargo build (debug). Release build: cargo build --release. Run CLI mode (no TUI): ./target/release/dua /path. Run interactive TUI: ./target/release/dua -i /path or just ./target/release/dua /path. Run tests: cargo test (includes both unit tests in src/interactive/app/tests/ and integration tests in tests/).

• src/main.rs — Entry point for the CLI application; defines command-line interface and orchestrates the main program flow.
• src/traverse.rs — Core file system traversal logic using parallel walks; foundational to disk usage analysis performance.
• src/aggregate.rs — Aggregates traversal results into size calculations; critical data transformation pipeline.
• src/interactive/app/mod.rs — Main interactive TUI application state and lifecycle; controls the interactive deletion and navigation experience.
• src/interactive/app/eventloop.rs — Event handling and state mutation loop; drives user interactions and terminal updates in real-time.
• Cargo.toml — Dependency manifest; defines feature flags (tui-crossplatform, trash-move) critical to platform support.
• src/lib.rs — Library root exposing public API for aggregation and traversal functions used by CLI and tests.

Add a new CLI subcommand or flag

1. Define new argument struct or add field to existing one in src/options.rs using clap attributes (src/options.rs)
2. Add handling logic in src/main.rs to branch on the new option and call appropriate core function (src/main.rs)
3. Implement or call the core logic (e.g., src/aggregate.rs or src/interactive/mod.rs depending on feature) (src/aggregate.rs)

Add a new interactive TUI widget or pane

1. Create new widget module in src/interactive/widgets/ with rendering function (src/interactive/widgets/mod.rs)
2. Update src/interactive/widgets/main.rs layout to include the new widget in the overall grid (src/interactive/widgets/main.rs)
3. Add state field to AppState in src/interactive/app/state.rs to track widget data (src/interactive/app/state.rs)
4. Add event handlers in src/interactive/app/handlers.rs to respond to user input targeting the widget (src/interactive/app/handlers.rs)

Modify the file traversal or aggregation logic

1. Review src/traverse.rs to understand the current parallel walk strategy and jwalk integration (src/traverse.rs)
2. Modify aggregation rules or filtering in src/aggregate.rs if changing how sizes are computed (src/aggregate.rs)
3. Update src/inodefilter.rs if hard-link or cross-device detection logic needs adjustment (src/inodefilter.rs)
4. Add or update integration tests in tests/ or src/interactive/app/tests/ to verify correctness (src/interactive/app/tests/unit.rs)

• jwalk (parallel directory traversal) — Maximizes I/O parallelism to saturate SSDs; essential for fast disk usage analysis on large trees.
• petgraph (directed acyclic graph) — Efficiently models hierarchical directory structure for O(1) parent lookups and tree traversal during interactive navigation.
• crossterm (terminal abstraction) — Cross-platform terminal control (Windows, Linux, macOS) without external dependencies; enables interactive TUI on all platforms.
• tui-rs (terminal UI framework) — Declarative widget-based rendering for complex layouts; handles buffer management and incremental screen updates.
• trash crate (safe deletion) — Moves files to OS trash/recycle bin instead of permanent deletion; safer than rm for interactive workflows.
• clap (command-line parsing) — Declarative arg parsing with derive macros; enables complex subcommands and flags with minimal boilerplate.

• Parallel traversal by default with no sequential option

  • Why: Maximizes throughput for the primary use case (analyzing large disks) and aligns with product vision 'parallel by default.'
  • Consequence: Higher CPU usage during analysis; less suitable for resource-constrained environments or measuring exact I/O patterns.

• In-memory petgraph tree of entire directory structure

  • Why: Enables instant navigation without re-traversal; smooth interactive experience.
  • Consequence: Memory usage scales linearly with file count (can be GBs for trees with millions of files); no streaming or lazy-load option.

• Trash-move as default deletion instead of permanent rm

  • Why: Safer for interactive workflows; users can recover deleted items.
  • Consequence: Trash bin fills up; requires user to empty trash manually; slower than permanent deletion.

• TUI uses raw mode with blocking event loop

  • Why: Simplest event handling model; synchronous terminal updates.
  • Consequence: Cannot multiplex other async operations; no built-in support for background tasks or streaming deletions.

• Does not provide real-time monitoring or watch mode for continuous disk usage updates.
• Does not support network file systems (NFS, SMB) as primary targets; optimized for local file systems.
• Not a replacement for advanced forensics tools (e.g., file recovery, secure deletion patterns).
• Does not implement compression or deduplication analysis—only reports actual disk usage.
• Not designed for scripting or machine-readable output in interactive mode (only non-interactive aggregate mode supports JSON/structured output).

1. Edition 2024: Cargo.toml specifies edition = '2024', which may require a recent Rust nightly toolchain; stable users may hit compilation errors. 2. Windows nightly requirement: README notes cargo +nightly install dua-cli for Windows; worth testing locally before assuming stable works. 3. TUI feature coupling: Default features include tui-crossplatform which pulls in ratatui, crossterm, unicode deps; disabling via --no-default-features yields a simpler binary but loses the interactive mode. 4. Trash behavior: The trash-move feature depends on platform-specific trash handling (coinit_apartmentthreaded on Windows); may behave differently or be unavailable on some systems. 5. Inode deduplication: src/inodefilter.rs uses inode tracking to avoid double-counting hardlinks; requires POSIX-like metadata; behavior on NTFS or unusual filesystems is untested. 6. Cross-device handling: src/crossdev.rs prevents traversal across mount points by default; may surprise users expecting filesystem-wide scans.

• Parallel directory traversal with work-stealing — dua's core speed advantage comes from jwalk and crossbeam-based parallel traversal in src/traverse.rs; understanding work-stealing scheduling vs. sequential walking is key to why dua maxes out SSDs.
• Inode deduplication for hardlink-aware disk accounting — src/inodefilter.rs prevents double-counting hardlinks via inode tracking; essential for accurate size reporting on filesystems where multiple names map to the same data.
• Event-driven state machine for TUI applications — src/interactive/app/eventloop.rs and handlers.rs implement classic TUI pattern: event poll → state update → redraw; mastering this is crucial for extending interactive features without race conditions.
• Cross-device filesystem boundary detection — src/crossdev.rs prevents traversal across mount points (e.g., /proc, /sys, /mnt); important for avoiding infinite loops and respecting filesystem policy in disk scanning tools.
• Gitignore-style glob patterns for directory filtering — gix-glob (via src/config.rs) allows users to exclude paths with familiar syntax (target/, *.tmp); understanding pattern semantics is needed to extend filtering features.
• Terminal UI rendering with retained-mode graphics (Ratatui) — Unlike immediate-mode game engines, Ratatui uses a declarative widget model; src/interactive/widgets/ builds a scene each frame and Ratatui diffs it; understanding this prevents re-rendering pitfalls.
• Safe file deletion via system trash/recycle bin integration — The trash crate (enabled via trash-move feature) hooks into OS-specific APIs; understanding platform differences (trash on Linux/macOS, Recycle Bin on Windows) matters for testing deletion workflows.

• Aya0x/dust — Alternative Rust-based disk usage analyzer with similar goals; good reference for parallel traversal patterns and TUI implementation differences.
• bootandy/DirSizer — Another cross-platform disk analyzer written in Rust; provides comparison for feature parity (deletion, filtering, performance tuning).
• ratatui-org/ratatui — The TUI framework (formerly tui-rs) that dua depends on; essential for understanding widget rendering, event handling, and styling used throughout src/interactive/.
• Byron/gitoxide — Sibling project by the same author (Byron); shares Rust idioms, logging setup (fern, log), and glob pattern handling (gix-glob, gix-path modules).
• crossterm-rs/crossterm — Terminal abstraction layer that Ratatui uses; understanding its input/output handling (color, raw mode, events) is useful for debugging TUI behavior on different platforms.

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add integration tests for trash/delete functionality across platforms

The repo has src/interactive/app/tests/journeys_with_writes.rs for deletion testing, but coverage appears limited. The trash dependency is conditionally compiled with platform-specific features (coinit_apartmentthreaded for Windows, chrono for all). Add comprehensive integration tests validating delete operations on Linux, macOS, and Windows to catch platform-specific regressions before release.

• [ ] Expand tests/journeys_with_writes.rs with platform-specific test cases using #[cfg(target_os = ...)]
• [ ] Test trash restoration on Windows (coinit_apartmentthreaded feature)
• [ ] Test permanent deletion vs trash behavior based on configuration
• [ ] Add CI workflow step to run these tests on matrix of OS targets in .github/workflows/rust.yml

Add unit tests for glob pattern matching in src/interactive/widgets/glob.rs

The glob.rs widget handles user-provided glob patterns using gix-glob and gix-path dependencies, which are critical for filtering large directory trees. Currently src/interactive/app/tests/unit.rs exists but glob-specific pattern matching logic lacks dedicated test coverage, risking silent filtering bugs.

• [ ] Create comprehensive unit tests in src/interactive/widgets/glob.rs or add to tests/ for edge cases: glob patterns with emoji (test fixtures exist!), recursive patterns, negation patterns
• [ ] Test against existing emoji and grapheme fixtures in tests/fixtures/emoji/ and tests/fixtures/grapehemes/
• [ ] Verify performance with large pattern sets to ensure glob compilation doesn't regress
• [ ] Document expected glob syntax in a comment block referencing gix-glob behavior

Add GitHub Actions workflow for dependency security audits and MSRV validation

The Cargo.toml specifies edition = "2024" and has many transitive dependencies. The existing .github/workflows/rust.yml likely lacks automated security scanning and Minimum Supported Rust Version (MSRV) checks. Add workflows to catch security vulnerabilities early and validate compatibility with stated MSRV.

• [ ] Create .github/workflows/security.yml using cargo-audit or cargo-deny to scan for known vulnerabilities in dependency tree
• [ ] Create .github/workflows/msrv.yml to test against minimum Rust version (add rust-version field to Cargo.toml if missing, e.g., 1.70)
• [ ] Configure both workflows to run on pull requests and scheduled weekly
• [ ] Document MSRV policy in README.md under Installation or Contributing section

• Add snapshot tests for TUI rendering: src/interactive/widgets/ renders Ratatui frames but lacks snapshot/golden tests. Create a test module in src/interactive/widgets/tests/ that captures rendered output for key screens (help, mark menu, main tree) and validates them against golden images using a crate like insta or similar. This improves regression detection.
• Extend unit test coverage for src/config.rs: Config file parsing logic exists but src/interactive/app/tests/unit.rs has minimal config tests. Add cases for: (1) parsing valid TOML with exclude globs, (2) missing config file graceful fallback, (3) malformed TOML error handling, (4) environment variable override of config paths (CLAP_ENV feature is already used).
• Add documentation for glob pattern syntax: src/common.rs and src/config.rs use gix-glob for pattern matching, but users lack guidance on which patterns are supported. Write a doc comment / help text in src/options.rs or a new docs/glob-patterns.md file explaining gitignore-style syntax with examples (e.g., *.log, target/, **/.git). Link it in the help output.

The dua-cli codebase demonstrates generally good security practices. The main concern is a configuration error (invalid edition) that will prevent compilation. Secondary concerns include disabled overflow checks in release builds and reliance on unverified installation scripts. Dependency versions appear reasonable and up-to-date. No obvious injection vulnerabilities, hardcoded credentials, or dangerous patterns were identified in the file structure. Recommended improvements include fixing the edition configuration, adding automated security scanning to CI/CD, and improving installation script integrity verification.

• Medium · Deprecated Rust Edition — Cargo.toml. Cargo.toml specifies edition = '2024' which does not exist. Valid editions are 2015, 2018, and 2021. This will cause compilation failures and may indicate a configuration error that could lead to unexpected behavior. Fix: Change 'edition = "2024"' to 'edition = "2021"' (or an appropriate valid edition)
• Low · Overflow Checks Disabled in Release Build — Cargo.toml [profile.release]. The release profile has 'overflow-checks = false', which disables integer overflow detection. While this improves performance, it can mask integer overflow bugs that could lead to unexpected behavior or security issues in arithmetic operations. Fix: Consider enabling overflow-checks or at least thoroughly test arithmetic operations. If performance is critical, document this decision and add explicit bounds checking where necessary.
• Low · Panic Set to Abort in Release — Cargo.toml [profile.release]. Release profile uses 'panic = abort' which terminates the process immediately on panic. While this can prevent information leakage, it may make debugging production issues more difficult. For a file deletion tool, this is less critical but worth monitoring. Fix: This is acceptable for a CLI tool, but ensure error handling prevents unexpected panics. Consider using panic hooks for logging critical information before abort.
• Low · Installation Script from GitHub Master Branch — README.md (Installation section). The README contains an installation script that curls and pipes directly to sh from the master branch. While this is common practice, it relies on GitHub availability and master branch stability. The script hash is not verified. Fix: Consider pinning to a specific release tag instead of master branch. Add integrity verification for the installation script (e.g., checksum validation).
• Low · Optional Trash Dependency Without Default Validation — Cargo.toml [dependencies.trash]. The 'trash-move' feature uses the 'trash' crate with 'coinit_apartmentthreaded' and 'chrono' features. The default feature behavior should be validated to ensure secure defaults when the feature is not explicitly enabled. Fix: Document the security implications of the trash feature. Ensure that when disabled, file deletion uses secure methods. Test both enabled and disabled states.
• Low · No SAST/Security Scanning in CI/CD — .github/workflows/rust.yml. The GitHub workflows (rust.yml) shown in the file structure do not explicitly indicate security scanning tools like 'cargo-audit' or 'cargo-deny' for vulnerability detection in dependencies. Fix: Add security scanning to CI/CD pipeline using tools like 'cargo-audit', 'cargo-deny', or 'cargo-supply-chain' to catch known vulnerabilities in dependencies automatically.

LLM-derived; treat as a starting point, not a security audit.

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.