OrgFs: Org-Mode as a Virtual Filesystem

OrgFs is a high-performance, FUSE-based, read-only virtual filesystem that exposes your Emacs Org-mode headings as standard Unix files. It provides a structured way to browse and query your Org-mode data from any tool or programming language without risking corruption to your original .org files.

The project uses a C++ core for performance, delegating Org-mode's complex parsing logic to a headless Emacs instance via a binary Protobuf bridge.

🚀 Features

• Semantic Routing: Browse your tasks intuitively through specialized virtual directories:
  • /tags/{tag_name}/ -> Lists all headings with a specific tag.
  • /states/{TODO_keyword}/ -> Lists headings matching a specific state (e.g., TODO, DONE).
  • /scheduled/YYYY/MM/DD/ -> Navigate tasks by their scheduled date.
  • /deadlines/YYYY/MM/DD/ -> Navigate tasks by their deadline.
  • /timeline/YYYY/MM/DD/ -> Aggregated view of all entries mentioning a specific date.
  • /tree/ -> A hierarchical reflection of your physical Org files, where folders represent files and .children/ sub-directories represent heading nesting.
• Smart Queries: Create dynamic, session-persistent folders using a powerful query syntax via mkdir in the /queries/ directory.
• Unique, Human-Readable Filenames: Headings are exposed as source_file_LX_heading.org (e.g., tasks_L42_Fix_server_bug.org) to ensure they are both unique and easy to identify.
• Read-Only Safety: Your original Org files are never modified by the FUSE daemon.
• Live Updates: Uses inotify to automatically reload and re-index your data when physical .org files change.

🔍 Query Syntax

You can create dynamic search folders by using mkdir inside the /queries/ directory.

Operators

• + : AND operator.
• , : OR operator.
• .ne. : NOT operator (infix, e.g., state.ne.DONE).
• () : Parentheses for grouping.

Keywords

• tag.VALUE or just VALUE (e.g., tag.work or work)
• state.VALUE or st.VALUE (e.g., state.TODO)
• scheduled.VALUE or s.VALUE (VALUE can be today, past, future, or YYYY-MM-DD)
• deadline.VALUE or d.VALUE (VALUE can be today, past, future, or YYYY-MM-DD)
• priority.VALUE or p.VALUE (e.g., priority.A)
• heading.VALUE or h.VALUE (substring match in the heading title)

Query Examples

• tag.work+state.TODO : Active work tasks.
• (scheduled.today,scheduled.past).ne.state.DONE : All overdue or today's tasks that aren't finished.
• deadline.future+tag.urgent : Upcoming urgent deadlines.

🛠️ Prerequisites

• Linux (FUSE support).
• Dependencies: Install via apt:

  sudo apt-get install cmake g++ libfuse3-dev libprotobuf-dev protobuf-compiler libsqlite3-dev

• Emacs: With the org-ql package installed.

🏗️ Building

1. Generate Protobuf Code (Optional)

While CMake handles this automatically during the build process, you can generate the C++ classes manually using:

protoc --cpp_out=. orgfs.proto

2. Compile

mkdir -p build && cd build
cmake ..
make -j$(nproc)
cp orgfs-bin ..

📖 Usage

1. Mount OrgFs: Use the provided wrapper script to handle path resolution and temporary directory setup.

./orgfs-mount --src ~/path/to/org/files --mount /mnt/orgfs

2. Access Data:

# Browse by tag
ls /mnt/orgfs/tags/project_alpha/

# Check your schedule for today
ls /mnt/orgfs/scheduled/2026/04/19/

# Run a custom query
mkdir -p "/mnt/orgfs/queries/work+state.NEXT"
ls "/mnt/orgfs/queries/work+state.NEXT/"

# Read a heading's content
cat "/mnt/orgfs/tree/tasks.org/tasks_L142_Update_documentation.org"

⚙️ Architecture

1. C++ FUSE Daemon: Handles low-level VFS syscalls and maintains an in-memory SQLite cache of heading metadata.
2. Emacs Bridge: An Elisp backend (orgfs-export.el) that runs in a headless Emacs instance, extracting data into a Protobuf-encoded format.
3. Protobuf Interface: Defines the OrgHeading message for structured data exchange between Lisp and C++.

⚖️ License

This project is licensed under the terms of the GNU General Public License v3.0 (GPLv3). See the LICENSE file for the full text.

Credits

Assisted by Gemini 3 Pro via Gemini CLI for boilerplate and logic structure.