Ytree is a keyboard-first file manager for Linux and BSD with fast multi-volume logging and navigation.
Important
STATUS: ALPHA (v3.0.0-alpha)
ytree is in active alpha development. It is stable and usable, but expect rough edges, incomplete behaviour, and occasional regressions. Interfaces, key bindings, and configuration details may change before the first stable release.
Before opening an issue or suggesting a feature, please check BUGS.md and ROADMAP.md first, so as not to create a duplicate if it is already listed.
Ytree logs filesystem hierarchies into memory, so you can work across whole volumes, not just one directory at a time. Use tree + file-list views, Showall/Global views, tagging, fast filtering, split-screen workflows, preview, and archive-as-directory operations (including in-archive copy/move/rename/delete/mkdir where supported).
Born from the lineage of XTree™ (DOS), ytree was intended to be the definitive tree-based logger for Unix. While it has been maintained for compatibility over the decades, its feature set remained largely frozen in the late 1990s, leaving Unix power users without a true equivalent to the powerful "log and tag" workflow.
Many file managers today function as "browsers"—they look at one directory at a time and rely on the OS to fetch files on demand. Ytree is different: it is a Logger. It scans ("logs") entire drive hierarchies into memory. This treats the filesystem as a database, allowing you to Show All files in a flat view, filter across thousands of subdirectories instantly, and perform bulk operations on tagged files regardless of their location.
Forked in October 2025 from Ytree v2.10, created by Werner Bregulla and others. This v3.0 project focuses on feature completeness for Unix power users, including split-screen and integrated autoview. The move to a modular C99/POSIX architecture is a practical side effect of delivering those capabilities safely and maintainably.
This refactor is an experiment in AI-assisted systems engineering. The codebase was not simply "ported"; it was systematically disassembled and re-architected toward feature completeness and maintainability.
In practice, the human maintains design ownership and quality control, while AI is used as an implementation assistant. This requires substantial iteration, verification, and architectural guardrails for each meaningful change. The goal is to show that LLM-assisted development can still meet normal project standards when the process is disciplined, specification-driven, and strongly validated.
Quality claims are backed by repository-visible gates and documentation:
- AUDIT.md: required QA/audit loop and merge gates.
- TRUST.md: safety posture, limits, and code-level evidence pointers.
- PR_GATE.md: governance and merge-readiness checks.
v3.0.0-alpha is being published early so people can use the program, inspect the code, and evaluate the direction before beta. It is usable today, but still in active development: expect rough edges, occasional UX/workflow bugs, and ongoing refinement of some features.
- Classic XTree™ Interface: Directory Tree + File List layout.
- Split Screen Mode (F8): Manage two independent file panels side-by-side.
- File Preview (F7): Instant view of file contents without launching external tools.
- Multi-Volume Support: Log multiple drives or archives simultaneously and switch instantly.
- Archives as Directories: Browse ZIP, TAR, GZ, and ISO files transparently using
libarchive. - Advanced Filtering: Filter by RegEx, Attribute, Date, and Size.
- Modern Architecture: Clean C99, strict context-passing design — no global mutable state. See ARCHITECTURE.md.
- Auto-Refresh: Inotify integration for live directory updates.
- External Viewers: Associate specific file extensions with external programs (images, PDFs, etc.).
- User Commands: Bind keys to custom shell commands/scripts for infinite extensibility.
- C Compiler (GCC or Clang; Clang is required for fuzz targets)
- ncurses (libncurses-dev / ncurses-devel)
- readline (libreadline-dev / readline-devel)
- libarchive (libarchive-dev / libarchive-devel)
- lcov (for baseline coverage reports)
- llvm-symbolizer (recommended for sanitizer/fuzz stack traces)
# Clone the repository
git clone https://github.com/robkam/ytree.git
cd ytree
# Compile (Optimized Release Build)
make
# Install
sudo make install
# Uninstall
sudo make uninstallNote: Developers can compile with AddressSanitizer enabled by running make DEBUG=1.
The project documentation is split into several focused files.
| Document | Purpose |
|---|---|
| USAGE.md | User Guide: How to navigate, tag, and use command keys. (Generated from ytree.1.md). |
| BUGS.md | Known Issues: Current defects, reproductions, and fix status. |
| CONTRIBUTING.md | Developer Setup: How to set up the environment, run tests, and submit code. |
| PR_GATE.md | PR Governance: Required PR gate checks and triage rules needed for merge readiness. |
| AUDIT.md | QA Workflow: The mandatory safety/integrity checks for every PR (Valgrind, ASan, etc). |
| SPECIFICATION.md | Behavioral Contract: UI layout, navigation protocols, and design philosophy. |
| ARCHITECTURE.md | System Design: Core technical principles (DRY, SRP, Context-passing) and data hierarchy. |
| TRUST.md | Trust & Safety: Safety claims and where to verify them in the codebase. |
| ROADMAP.md | Future Plans: Pending milestones and prioritized delivery backlog. |
| CHANGES.md | Changelog: Detailed history of v3.0 feature delivery, architecture work, and updates. |
ytree/
├── src/ C source files
├── include/ C headers
├── tests/ pytest/pexpect test suite
├── scripts/ helper scripts (build and tooling)
├── docs/ user, developer, and process documentation
├── etc/ manpage source and related assets
├── build/ build artifacts
├── obj/ object files
├── coverage/ coverage outputs
├── Makefile primary build/test targets
├── README.md project overview
└── AGENTS.md Codex/agent discovery stub
If you find anything amiss, you can report it using GitHub Issues.
For security-sensitive bugs, report privately via SECURITY.md.
Feature requests and enhancement ideas are welcome too. Suggestions are appreciated, but not every request can be implemented.
It will help us to address the issue if you include the following:
- OS & Configuration: (Distro, Terminal type, etc.)
- Ytree version:
- Steps to Reproduce:
- Expected Behavior:
- Actual Behavior:
Contributions are welcome! Please read CONTRIBUTING.md for guidelines. See SPECIFICATION.md for behavioral requirements, and ARCHITECTURE.md to understand the system design before submitting code. Contributions do not need to be low-level C internals: bug reports, documentation updates, typo fixes, wording/UX clarifications, and translations are all valuable.
Ytree is free software distributed under the GPL. See the LICENSE.md file for details.
For detailed authorship, see AUTHORS.md.
