Agentdir

agentdir

**Rust-built virtual file tree infrastructure for agent-ready file layouts across macOS, Linux, and Windows**

[](https://crates.io/crates/agentdir) [](https://pypi.org/project/agentdir/) [](https://www.npmjs.com/package/@nomadamas/agentdir) [](LICENSE)

agentdir lets your tools present the same original files in purpose-built, read-only folder structures without moving the originals. AI agents, scripts, and humans can navigate documents, media, datasets, generated artifacts, plain text, binaries, or any other OS-visible files through a layout optimized for the task at hand.

Built in Rust, agentdir runs on macOS, Linux, and Windows. On CoW-capable filesystems such as APFS, Btrfs, and XFS, alternate layouts and snapshots use reflinks, so large files do not get duplicated just because the folder structure changes. When CoW is unavailable, agentdir falls back to byte-copy materialization.

The point is simple: keep the human-facing file layout stable, give agents a better working layout, and keep the two mapped together as original files change.

---

Why agentdir

• Better agent context — expose task-specific file layouts instead of forcing agents through whatever folder structure happened to grow over time
• Originals stay put — rearrange the virtual namespace with mv, cp, rename, mkdir, and rmdir without moving the source files
• No duplicate-data tax on CoW filesystems — big PDFs, images, media, and datasets can appear in multiple layouts without copying file data on supported filesystems
• General-purpose files, not just developer projects — works with documents, spreadsheets, presentations, PDFs, images, media, datasets, plain text, binaries, and more
• Cross-platform native core — Rust library, CLI