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/imsnif/diskonaut 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 all four use cases

• 20 active contributors
• MIT licensed
• CI configured
• Tests present
• ⚠ Stale — last commit 2y ago
• ⚠ Concentrated ownership — top contributor handles 72% 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 imsnif/diskonaut repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/imsnif/diskonaut.

What it runs against: a local clone of imsnif/diskonaut — 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 imsnif/diskonaut | 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 ≤ 821 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of imsnif/diskonaut. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/imsnif/diskonaut.git
#   cd diskonaut
#
# 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 imsnif/diskonaut and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "imsnif/diskonaut(\\.git)?\\b" \\
  && ok "origin remote is imsnif/diskonaut" \\
  || miss "origin remote is not imsnif/diskonaut (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/app.rs" \\
  && ok "src/app.rs" \\
  || miss "missing critical file: src/app.rs"
test -f "src/state/files/file_tree.rs" \\
  && ok "src/state/files/file_tree.rs" \\
  || miss "missing critical file: src/state/files/file_tree.rs"
test -f "src/state/tiles/treemap.rs" \\
  && ok "src/state/tiles/treemap.rs" \\
  || miss "missing critical file: src/state/tiles/treemap.rs"
test -f "src/input/controls.rs" \\
  && ok "src/input/controls.rs" \\
  || miss "missing critical file: src/input/controls.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 821 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~791d)"
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/imsnif/diskonaut"
  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).

diskonaut is a terminal-based disk space navigator written in Rust that scans a directory tree, builds an in-memory index of file metadata, and displays it as an interactive treemap visualization. Users can explore subdirectories, see what's consuming disk space, and delete files/folders while tracking freed space in real time—solving the common problem of finding large files hidden deep in nested folder structures without leaving the terminal. Modular architecture split into functional layers: src/main.rs and src/app.rs form the event loop; src/input/ handles keyboard controls; src/state/ manages the file tree (src/state/files/file_tree.rs) and treemap layout (src/state/tiles/treemap.rs); src/messages/ defines the instruction/event flow; src/os/ abstracts Unix/Windows syscalls. The treemap rendering lives in src/state/tiles/board.rs, and deletion logic in src/state/file_to_delete.rs.

System administrators and developers who need to quickly audit and free up disk space on Linux, macOS, or Windows machines. Users who prefer command-line tools and want visual feedback on storage usage without installing heavyweight GUI applications.

Actively maintained and production-ready. The project is at v0.11.0 with snapshot tests in place (insta), CI via Travis CI, and broad platform support (Linux/macOS/Windows/FreeBSD). Multi-distribution packaging (Fedora, Arch, Homebrew, nixpkgs) indicates real-world adoption. Last activity appears recent based on changelog and active issue resolution.

Low risk for core functionality—it's a small, focused Rust binary with minimal dependencies (tui, crossterm, jwalk, filesize, nix). Single maintainer (aram@poor.dev) is the primary risk. The nix crate (v0.17.0) and tui (v0.11) are somewhat dated versions, though they remain stable. Windows support via winapi adds platform-specific complexity that could harbor bugs.

No specific PR or milestone data visible, but the repo shows active distribution packaging and cross-platform support. The presence of comprehensive snapshot tests (src/tests/cases/snapshots/) indicates ongoing quality work. Contributors are encouraged to tackle 'help wanted' and 'good first issue' labels per CONTRIBUTING.md.

Clone the repo and build with Rust: git clone https://github.com/imsnif/diskonaut.git && cd diskonaut && cargo build --release. Then run it: ./target/release/diskonaut /path/to/scan or simply cargo run -- /path/to/scan for debug builds.

Daily commands: cargo run -- <path> scans and starts the interactive TUI. Exit with q. Navigate with arrow keys. Press d to delete (if deletion works on your platform). No server or external service needed—purely local file I/O.

• src/main.rs — Application entry point that initializes the TUI event loop and orchestrates the main application flow.
• src/app.rs — Core application state machine that handles user input, updates state, and manages the render lifecycle.
• src/state/files/file_tree.rs — Abstract representation of the file system directory tree; critical for all navigation and deletion operations.
• src/state/tiles/treemap.rs — Treemap layout algorithm that converts file sizes into visual rectangle coordinates; visual core of the navigator.
• src/input/controls.rs — Maps user keyboard input to application instructions; foundation for all interactive features.
• src/state/mod.rs — State module aggregator defining the global application state structure passed through event handling.
• src/os/mod.rs — Platform abstraction for OS-specific file operations (scanning, deletion); enables cross-platform compatibility.

• File Tree (file_tree.rs) (Rust recursive structs, Arc<Mutex<>> for shared ownership) — Loads and maintains the in-memory file system hierarchy; responds to queries about folder contents and size calculations.
  • Failure mode: Memory exhaustion on very large directories; silent truncation if metadata unavailable.
• Treemap Layout Engine (treemap.rs) (Floating-point geometry, recursive partitioning) — Converts a sorted list of file sizes into visual tile positions using rectangle subdivision algorithm.
  • Failure mode: Rounding errors causing visual gaps; sub-pixel clipping on tiny files.
• App State Machine (app.rs) (Pattern matching, mutable state with interior mutability) — Central hub: ingests Instructions, mutates state, and commands re-renders. Enforces invariants (e.g., cannot navigate into files).
  • Failure mode: Stale cursor position if file tree mutates unexpectedly; panic on invalid state transitions.
• Input Handler (input/controls.rs) (crossterm events, enum dispatch) — Maps raw key events to typed Instructions; buffers and debounces repeated keys.
  • Failure mode: Missed keys if event queue saturates; platform-specific key codes misaligned.
• OS Abstraction (os/mod.rs, unix.rs, windows.rs) (nix crate) — Provides safe deletion and metadata retrieval with platform-specific syscalls (unlinkat, DeleteFileW).

Add a new keyboard shortcut

1. Define the new key event in the control mapping (src/input/controls.rs)
2. Create corresponding Instruction variant in the message enum (src/messages/instruction.rs)
3. Handle the instruction in the app state machine (src/app.rs)

Add platform-specific file operation

1. Define the operation signature in the abstraction module (src/os/mod.rs)
2. Implement Unix version using nix crate (src/os/unix.rs)
3. Implement Windows version using winapi crate (src/os/windows.rs)

Add a UI state visualization feature

1. Add state field to track feature state (src/state/ui_effects.rs)
2. Update state transitions in app state machine (src/app.rs)
3. Add snapshot test cases for rendering (src/tests/cases/mod.rs)

Improve treemap layout algorithm

1. Modify the layout computation logic (src/state/tiles/treemap.rs)
2. Update tile rectangle calculations if needed (src/state/tiles/rect_float.rs)
3. Add snapshot tests verifying layout changes (src/tests/cases/mod.rs)

• Rust + crossterm — Memory-safe systems language with zero-cost cross-platform terminal abstraction; ideal for efficient disk I/O scanning.
• tui-rs (TUI framework) — Provides immediate-mode UI rendering with retained widget state; simplifies complex terminal layouts without managing escape sequences.
• jwalk (parallel file traversal) — Concurrent recursive directory scanning via Rayon; enables fast indexing of large file systems while remaining responsive.
• nix/winapi (OS abstraction) — Direct system calls for platform-specific deletion and metadata; avoids reliance on shell or third-party tools for reliability.
• insta (snapshot testing) — Captures entire TUI render output as snapshots; catches visual regressions across state transitions automatically.

• Scan entire directory tree into memory before rendering

  • Why: Allows interactive exploration and sorting without repeated disk I/O; simplifies cursor movement and deletion tracking.
  • Consequence: Memory usage scales with total files scanned; impractical for 10M+ file systems. Mitigated by early-exit filtering.

• Treemap layout via floating-point rectangle subdivision

  • Why: Produces visually appealing size-proportional layout with minimal computation overhead.
  • Consequence: Floating-point rounding artifacts possible; requires careful boundary handling to avoid visual gaps.

• Platform-specific OS module (Unix vs Windows)

  • Why: Direct system calls provide the most reliable deletion and metadata; no shell escaping vulnerabilities.
  • Consequence: Code duplication; requires testing on both platforms and maintenance of separate implementations.

• Immediate-mode event loop with full re-render per keystroke

  • Why: Simplifies state machine logic; no event coalescing or partial update complexity.
  • Consequence: Higher CPU usage during idle periods; mitigated by crossterm's efficient terminal diffing.

• Does not provide real-time file system monitoring or automatic refresh of external changes
• Does not support remote file systems (NFS, SMB) or cloud storage backends
• Not a file manager: cannot move, copy, or rename files; deletion only
• Does not support multi-threaded user sessions or persistent database of scan results
• Not a replacement for du/ncdu; lacks historical tracking or report generation

The nix crate (v0.17.0) is Unix-only and used for low-level file operations; deletions on Windows use winapi instead. Terminal size detection via crossterm can be unreliable on some terminal emulators. The treemap algorithm may not tile perfectly if the terminal is too small (see snapshot test cannot_move_into_small_files). Scanning very large directory trees (100k+ files) may cause UI lockup during indexing. File permissions must allow deletion for the delete feature to work; no graceful fallback if permissions are denied.

• Treemap layout algorithm — The core visualization technique in this app; understanding how file sizes map to tile positions and dimensions is essential to modify the visual output or add features like sorting/filtering.
• State machine architecture — diskonaut uses an instruction/event-driven state machine pattern (see src/messages/); understanding this is key to adding new features or fixing state-related bugs.
• Memory-mapped directory traversal (jwalk) — The jwalk crate enables concurrent, streaming directory scanning; knowing when and why it's used helps optimize performance on large filesystems.
• Terminal control abstraction (crossterm) — crossterm abstracts raw terminal control; understanding how it handles input events and rendering is crucial for any UI modifications or platform-specific fixes.
• Snapshot testing (insta) — The test suite uses insta snapshots for UI regression testing; familiarize yourself with how these work if you modify the rendering layer.
• Unix syscalls for file deletion (nix crate) — The nix crate wraps low-level Unix syscalls (unlink, rmdir); understanding these is critical when modifying deletion logic or adding platform support.
• Windows file API (winapi) — Windows deletion uses winapi directly; understanding HANDLE, FILE_SHARE_READ, and other WIN32 concepts is necessary for debugging or extending Windows support.

• bootandy/dust — Alternative disk space analyzer written in Rust; similar problem domain but different UI (uses a tree format instead of treemap).
• dundee666/dua-cli — Another Rust-based disk usage analyzer with interactive TUI; more feature-rich but heavier than diskonaut.
• sharkdp/fd — Rust CLI tool for fast filesystem traversal; diskonaut could benefit from its patterns if file discovery becomes a bottleneck.
• imsnif/jumpseat — Same author's other Rust TUI project; shares crossterm/tui patterns and state management approaches with diskonaut.
• fdehau/tui-rs — The upstream TUI library (tui-rs) that diskonaut depends on; understanding its widgets and event model is essential for UI modifications.

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 snapshot tests for Windows-specific file deletion behavior (src/os/windows.rs)

The repo has extensive snapshot tests for UI behavior (src/tests/cases/snapshots/) but lacks OS-specific tests for the Windows implementation. The windows.rs file handles file deletion with winapi calls that differ significantly from Unix. Adding snapshot tests would ensure cross-platform parity and prevent regressions in Windows-specific permission/deletion edge cases.

• [ ] Create src/tests/cases/windows_deletion_tests.rs with test cases for Windows file deletion
• [ ] Add snapshot tests covering: successful deletion, permission denied errors, file-in-use errors, and directory deletion
• [ ] Ensure tests mock winapi calls appropriately (consider using mockall or similar)
• [ ] Run tests on Windows CI to validate behavior

Add GitHub Actions CI workflow for cross-platform builds and tests

The repo has .travis.yml for CI but lacks GitHub Actions workflows. Given the project targets Windows, macOS, and Linux (evident from src/os/ directory structure and installation docs), a GitHub Actions workflow would: test on all three platforms simultaneously, build release artifacts, and catch platform-specific issues earlier. This is especially valuable for maintaining the Windows binary.

• [ ] Create .github/workflows/ci.yml with matrix testing for ubuntu-latest, macos-latest, and windows-latest
• [ ] Add steps: cargo build, cargo test, cargo clippy, and cargo fmt --check
• [ ] Create .github/workflows/release.yml to build and upload binaries for tagged releases
• [ ] Update CONTRIBUTING.md to reference the new CI workflows

Add integration tests for treemap rendering edge cases (src/state/tiles/)

The treemap module (treemap.rs, rect_float.rs, board.rs, tile.rs) handles complex spatial calculations for rendering disk usage visualization. Currently, only UI snapshot tests exist at high level. Low-level treemap calculation tests would catch rounding errors, zero-size folder handling, and extreme aspect ratio edge cases before they affect user experience.

• [ ] Create src/tests/treemap_tests.rs with unit tests for RectFloat calculations
• [ ] Add test cases: empty folders, single files, many files, extreme width/height ratios, floating point precision edge cases
• [ ] Create src/tests/tile_tests.rs to test Tile positioning and sizing logic
• [ ] Document expected behavior in test cases for future maintainers

• Add a human-readable size format display option (e.g., toggle between bytes, KB, MB, GB) in src/input/controls.rs and update src/state/ to track the preference. This improves UX without touching the core treemap logic.
• Write integration tests for src/os/windows.rs file deletion using WinAPI bindings; currently only Unix deletion has coverage. Set up a test fixture with temporary files to verify the delete path works correctly.
• Add a 'help' or 'usage' panel that displays keyboard shortcuts dynamically from src/input/controls.rs. Implement it as a toggleable overlay in src/state/tiles/board.rs; good way to learn the rendering pipeline.

The diskonaut project has a moderate security posture with significant concerns around outdated dependencies. The primary risk is the use of unmaintained or heavily outdated Rust crates (tui 0.11, crossterm 0.17, nix 0.17, deprecated failure crate), which may contain unpatched vulnerabilities. The tui-rs library in particular is no longer maintained and should be migrated to ratatui. The file deletion functionality should be carefully reviewed to ensure adequate safeguards are in place. No obvious injection vulnerabilities, hardcoded credentials, or infrastructure misconfigurations were detected in the provided file structure. Immediate action should be taken to upgrade dependencies, particularly tui/ratatui, crossterm, and the error handling crate.

• High · Outdated tui-rs Dependency — Cargo.toml - tui dependency. The project uses tui version 0.11 which was released in 2020 and is no longer actively maintained. This dependency may contain unpatched security vulnerabilities. The tui-rs project has been superseded by ratatui, and version 0.11 is significantly outdated. Fix: Migrate to the maintained ratatui crate (https://github.com/ratatui-org/ratatui) or update to a more recent version with security patches. Review the migration guide for tui to ratatui.
• High · Outdated crossterm Dependency — Cargo.toml - crossterm dependency. The project uses crossterm 0.17 released in 2020. While crossterm is still maintained, this version is significantly outdated and likely missing security patches and bug fixes from newer versions (currently 0.27+). Fix: Update crossterm to the latest stable version (0.27 or newer) to receive security patches and bug fixes.
• Medium · Deprecated 'failure' Crate — Cargo.toml - failure dependency. The project uses the 'failure' crate version 0.1 which is deprecated. The maintainer has recommended using 'anyhow' or 'eyre' instead. While not a direct security issue, deprecated crates may not receive security updates. Fix: Replace 'failure' with 'anyhow' (for Result types) or 'eyre' (for more detailed error handling) to use actively maintained error handling libraries.
• Medium · Outdated nix Crate — Cargo.toml - nix dependency. The project uses nix 0.17.0 released in 2020. This is a Unix/POSIX systems interface crate that may have had security-relevant updates in newer versions (currently 0.27+). Fix: Update nix to the latest stable version to ensure system interface bindings have the latest security patches and improvements.
• Medium · Outdated Development Dependency - insta — Cargo.toml - insta dev-dependency. The insta snapshot testing library version 0.16.0 is outdated. Current versions are 1.x+. While dev-dependencies are lower risk, outdated tools can have security issues. Fix: Update insta to the latest version (1.x or newer) for security patches and improvements.
• Medium · File Deletion Without Adequate Safeguards — src/state/file_to_delete.rs and related deletion logic. The codebase includes file deletion functionality (src/state/file_to_delete.rs). Without examining the implementation, TUI-based file deletion tools should have robust confirmation mechanisms and prevent accidental deletion of critical system files. Fix: Ensure robust deletion safeguards: (1) Require explicit user confirmation, (2) Prevent deletion of critical system directories, (3) Use secure deletion (shredding) if sensitive data may be involved, (4) Implement undo capability if possible, (5) Log all deletion actions.
• Low · Edition 2018 Usage — Cargo.toml - edition field. The project uses Rust edition 2018. While not a security issue, edition 2021 is the current recommended standard and may include security-related improvements. Fix: Consider upgrading to edition 2021 for access to newer language features and security improvements, though this requires testing compatibility.

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.