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/kamiyaa/joshuto 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.

WAIT — Mixed signals — read the receipts

• Last commit 3w ago
• 20 active contributors
• LGPL-3.0 licensed
• CI configured
• ⚠ Concentrated ownership — top contributor handles 63% of recent commits
• ⚠ LGPL-3.0 is copyleft — check downstream compatibility
• ⚠ No test directory detected

_{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 kamiyaa/joshuto repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/kamiyaa/joshuto.

What it runs against: a local clone of kamiyaa/joshuto — 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 kamiyaa/joshuto | Confirms the artifact applies here, not a fork | | 2 | License is still LGPL-3.0 | Catches relicense before you depend on it | | 3 | Default branch main exists | Catches branch renames | | 4 | Last commit ≤ 54 days ago | Catches sudden abandonment since generation |

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

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

# 2. License matches what RepoPilot saw
(grep -qiE "^(LGPL-3\\.0)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"LGPL-3\\.0\"" package.json 2>/dev/null) \\
  && ok "license is LGPL-3.0" \\
  || miss "license drift — was LGPL-3.0 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"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 54 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~24d)"
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/kamiyaa/joshuto"
  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).

Joshuto is a Rust-based terminal file manager that replicates ranger's keyboard-driven workflow in a modern, compiled language. It provides single-pane file browsing with extensive configuration (keymaps, themes, custom commands, MIME-type handlers) and optional image preview support via ratatui-image/ueberzug integration. The core solve: a fast, configurable, ranger-compatible file manager without Python dependencies. Monolithic Rust binary structured as: src/commands/ contains action handlers (navigation, deletion, search), config/ has TOML schemas for keymaps/themes/mimetypes, docs/ provides configuration guides. UI rendering uses ratatui crate with termion backend; event handling via notify and signal-hook. No separable library vs. binary—it's a single application.

Linux/macOS power users and terminal enthusiasts who want ranger's modal navigation and customization but prefer a single compiled binary. Contributors are typically Rust developers who value TUI tooling and terminal UI design using ratatui.

Actively developed and production-ready. At v0.9.9 with stable CI/CD (multi-platform GitHub Actions workflows for Linux/macOS), comprehensive configuration documentation in docs/, and regular releases. The codebase shows ~532KB of Rust with Nix and Docker packaging, indicating serious maintenance and multi-distribution support.

Low risk for a terminal tool, but maintained primarily by one author (kamiyaa). ~50 dependencies in Cargo.toml (ratatui, notify, image, regex, etc.) create moderate supply-chain surface. Breaking changes are possible since pre-1.0 semver (currently 0.9.9); users should pin versions if stability is critical.

Active development on v0.9.9 with recent GitHub Actions CI/CD improvements. Image preview support (docs/image_previews/) and syntax highlighting (ansi-to-tui feature) are recent additions. Likely ongoing ratatui ecosystem integration and cross-platform testing given multi-workflow setup.

git clone https://github.com/kamiyaa/joshuto.git
cd joshuto
cargo build --release
./target/release/joshuto

Or install system-wide: cargo install --path=. --force.

Daily commands:

cargo run --release

Debug build: cargo run. Binaries placed in target/release/joshuto. No dev server—single-window TUI app runs immediately in terminal.

• src/commands: Directory housing all user-actionable commands (navigation, file ops, search)—start here to understand how operations map to keybindings
• config/keymap.toml: User-facing keybinding configuration—defines how keyboard input routes to commands, critical for understanding UX flow
• config/joshuto.toml: Central configuration schema covering layout, preview, tabs, colors—shapes entire app behavior without code changes
• Cargo.toml: Declares all 50+ dependencies and feature flags (devicons, syntax_highlight, file_mimetype)—essential for understanding build variants
• docs/configuration/: Complete configuration reference in Markdown—users and contributors both rely on this to understand all TOML schemas
• .github/workflows/: CI/CD pipelines for Linux and macOS (rust-linux-main.yml, rust-macos-main.yml)—shows test/lint/build expectations

New commands: add handler in src/commands/. Keybindings: modify config/keymap.toml (no rebuild needed). UI appearance: config/theme.toml and config/icons.toml (TOML-driven, hot-reloadable). File preview: enhance config/preview_file.sh or docs/file_previews.md. Core logic: src/manager.rs likely contains state, src/ui/ contains rendering.

Build quirk: Requires Rust 1.90+; older toolchains will fail silently. Terminal requirement: Needs a terminal supporting termion (Linux/macOS; WSL on Windows works). Preview scripts: config/preview_file.sh is shell—must be executable and dependencies (fzf, zoxide) installed separately. Clipboard: xsel/xclip/wl-clipboard optional but copy/paste won't work without one. Image preview: Requires ueberzug or ueberzugpp installed separately; gracefully degrades if missing. Config path: Respects XDG standard (docs/) but also checks Cargo.toml embedded defaults in config/ folder.

• Terminal User Interface (TUI) with Ratatui — Joshuto's entire rendering pipeline uses ratatui's immediate-mode UI paradigm; understanding layout, widgets, and event loops is mandatory for UI work
• Event-driven architecture with signal-hook — File watching (notify crate) and Unix signal handling (SIGWINCH for resize) drive the main loop; crucial for understanding how UI redraws are triggered
• XDG Base Directory Specification — Joshuto respects ~/.config/joshuto/ for user config files; understanding XDG paths is essential for handling multi-user systems and config precedence
• ANSI color sequences and LS_COLORS — Joshuto uses lscolors to parse LS_COLORS env var for file colorization; understanding ANSI escape codes is needed for theme/icon customization
• Shell argument parsing with shell-words — Custom commands in keymap.toml are parsed as shell strings; shell-words handles quoting and escaping, critical for command composition
• Image rendering in terminals via ratatui-image — Optional image preview feature uses ratatui-image with ueberzug backend; understanding sixel/kitty protocols is helpful for extending preview capabilities
• TOML configuration as embedded schema — All user configuration (keymap.toml, joshuto.toml, theme.toml) is serde-driven TOML; modifying config parsing requires understanding serde derive patterns

• ranger/ranger — Joshuto's spiritual predecessor and design inspiration—the original Python ranger file manager that Joshuto reimplements in Rust
• ratatui-org/ratatui — The TUI framework powering Joshuto's UI rendering; understanding ratatui's architecture is essential for any UI modifications
• gokcehan/lf — Lightweight file manager written in Go with similar ranger-style design; alternative in the same ecosystem for comparison
• jarun/nnn — High-performance terminal file manager in C with heavy keybinding customization; common alternative users compare against Joshuto
• irixjx/joshuto-docker — Docker containerization of Joshuto; demonstrates packaging strategy and cross-platform deployment patterns

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 Windows CI/CD workflow for rust-windows-main.yml

The repo has automated builds for Linux and macOS (.github/workflows/rust-linux-main.yml, rust-macos-main.yml) but no Windows workflow despite Rust having strong Windows support. Windows users represent a significant portion of the potential user base. This would ensure joshuto builds and runs correctly on Windows, catch platform-specific bugs early, and improve cross-platform reliability.

• [ ] Create .github/workflows/rust-windows-main.yml following the pattern of rust-linux-main.yml
• [ ] Test on windows-latest runner with appropriate terminal handling (Windows Terminal or similar)
• [ ] Ensure termion dependency or platform-specific terminal backend works on Windows (may need investigation)
• [ ] Add Windows build badge to README.md next to Linux/MacOS badges
• [ ] Document any Windows-specific build steps in docs/contributing.md

Add comprehensive unit tests for src/commands/file_ops.rs

The file_ops.rs module handles critical file operations (copy, move, delete, rename) but there are no visible unit tests in the repo structure. This is high-risk code that could lose user data. Adding tests would prevent regressions, document expected behavior, and catch edge cases (special characters in filenames, permission errors, symlinks).

• [ ] Review src/commands/file_ops.rs to understand all public functions and their edge cases
• [ ] Create tests/file_ops_test.rs with unit tests for copy, move, delete, and rename operations
• [ ] Add tests for error handling scenarios (permission denied, file not found, disk full simulation)
• [ ] Add tests for edge cases (empty directories, symbolic links, special characters in names)
• [ ] Integrate tests into CI pipeline by running 'cargo test' in GitHub workflows

Document custom_commands with example implementations in docs/configuration/custom_commands/README.md

The custom_commands directory contains 4 example shell scripts (git_ignored, git_untracked, joshuto_git_conflicts, joshuto_git_root, joshuto_rg, joshuto_rgfzf) but there's no README explaining what they do, how to use them, or how to create new ones. This blocks users from leveraging extensibility. A comprehensive guide would improve discoverability and reduce support burden.

• [ ] Create docs/configuration/custom_commands/README.md with overview of custom commands feature
• [ ] Document each existing script's purpose, usage, and expected output format
• [ ] Add a 'How to Write Custom Commands' section with step-by-step tutorial
• [ ] Include examples of common use cases (ripgrep integration, git operations, batch processing)
• [ ] Link to this guide from docs/configuration/README.md and main README.md

• Add tests for src/commands/ directory: currently no unit tests visible in file structure; start with a single command module to establish test patterns.
• Expand docs/configuration/README.md with a 'troubleshooting' section covering common setup errors (terminal compatibility, clipboard tool selection, preview script permissions).
• Create examples/ directory with sample custom-command scripts (joshuto_git_root already exists in docs/configuration/custom_commands/; extract and document these as runnable examples).

Joshuto is a well-maintained Rust file manager with a reasonably secure foundation due to Rust's memory safety guarantees. However, several security concerns exist around command execution, file operations, and input validation. The primary risks are command injection from external tool integration (fzf, zoxide), potential symlink/TOCTOU vulnerabilities in file operations, and insufficient validation of configuration and user input. The codebase demonstrates good security practices with dependency management and use of modern Rust dependencies, but would benefit from explicit security auditing of command execution paths and file operation atomicity. No hardcoded secrets or obvious critical vulnerabilities were identified in the visible structure.

• Medium · Unrestricted External Command Execution — src/commands/open_file.rs, src/commands/fzf.rs, src/commands/search_fzf.rs, src/commands/select_fzf.rs, shell-words and shellexpand dependencies. The codebase contains multiple command execution patterns (fzf, zoxide, custom commands) that could be vulnerable to command injection if user input is not properly sanitized. The 'open' crate dependency and shell-words/shellexpand usage suggest file paths and arguments are passed to external programs. Fix: Ensure all user-controlled input (file paths, filter strings, search terms) is properly escaped before passing to external commands. Use structured argument passing instead of shell string expansion where possible. Validate file paths against directory traversal attacks.
• Medium · Arbitrary File Operations Without Validation — src/commands/delete_files.rs, src/commands/file_ops.rs, src/commands/rename_file.rs, src/commands/bulk_rename.rs. The file manager performs bulk operations (rename, delete, copy) on files and directories. While this is expected functionality, there's risk of TOCTOU (Time-of-Check-Time-of-Use) vulnerabilities and symlink attacks if file operations don't verify file properties at execution time. Fix: Implement atomic file operations where possible. Follow symlinks carefully and validate they point to expected locations. Add confirmations for destructive operations. Use file descriptors or inode-based verification to prevent TOCTOU attacks.
• Low · Potential Path Traversal in File Preview/Access — src/commands/, config/preview_file.sh, file handling in core UI components. The application handles file previewing and display of file contents. Without proper path canonicalization, attackers could craft symlinks to read sensitive files outside intended directories. Fix: Canonicalize all file paths before operations. Validate resolved paths are within expected bounds. Use std::fs::canonicalize() and verify results. For symbolic links, decide policy: follow or reject.
• Low · Configuration File Parsing Without Validation — config/joshuto.toml, config/keymap.toml, config/mimetype.toml, and their parsing implementations. TOML configuration files are parsed without apparent schema validation. Malformed or malicious configurations could cause crashes or unexpected behavior. The custom command execution system could be misused. Fix: Implement strict schema validation for all configuration files. Sanitize custom command definitions. Set reasonable limits on configuration complexity. Validate regex patterns at load time, not runtime. Document security implications of custom commands.
• Low · Dependency Version Pinning — Cargo.toml - multiple dependencies. Many dependencies use caret (^) version constraints, allowing minor and patch updates automatically. While patch updates should be safe, minor versions could introduce breaking changes or vulnerabilities. Examples: chrono ^0, colors-transform ^0, image ^0.25. Fix: Consider using more restrictive version constraints (= or ~) for security-critical dependencies. Regularly audit and update dependencies. Monitor security advisories via cargo-audit.
• Low · Incomplete Input Validation in Bulk Operations — src/commands/bulk_rename.rs, src/commands/filter_regex.rs, src/commands/filter_glob.rs, src/commands/select_regex.rs. Bulk rename and delete operations process user input (file selection, filter patterns) which could contain special characters or patterns causing unintended behavior. Fix: Implement comprehensive input validation. Test regex patterns for ReDoS (Regular Expression Denial of Service) vulnerabilities. Set reasonable limits on regex complexity and string lengths. Validate glob patterns.

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.