FUSE Architecture

Document status — initial design research (pre-v0.1, 2026-04-13). Chapter of Initial Report. Features discussed here are prospective designs from the v0.1-era FUSE pivot, not the current git-remote-reposix implementation.

To abstract web-based project management and knowledge graph systems into a local filesystem, the underlying operating system must intercept standard file operations and redirect them to custom user-space logic. In Linux and Unix-like operating systems, this is accomplished via the Filesystem in Userspace (FUSE) framework. Traditional filesystems reside entirely within the kernel space, which introduces high implementation complexity and stringent security risks. FUSE circumvents these limitations by establishing a bridge between the kernel's Virtual File System (VFS) and an unprivileged user-space daemon.

The VFS Interception Mechanism

When an AI agent executes a command to inspect a remote issue, such as invoking cat /mnt/jira_workspace/PROJ-101.md, the request initiates a standard POSIX read() system call. The kernel's Virtual File System receives this call and identifies the /mnt/jira_workspace mount point as a FUSE-managed directory. The VFS then forwards the request to the dedicated FUSE kernel module.

Instead of attempting to read physical blocks from a disk partition, the FUSE kernel module packages the request and places it into a specialized character device file, uniformly designated as /dev/fuse. Concurrently, a custom user-space program—often termed the FUSE daemon—continuously polls /dev/fuse. This daemon retrieves the queued request, processes the specified operation using custom application logic, and returns the resulting data payload back through /dev/fuse. The kernel module ultimately delivers this payload back to the originating process, completely abstracting the network calls and API formatting from the agent.

Implementation Frameworks and Precedents

Constructing a FUSE daemon no longer requires writing raw, low-level C code. Modern implementations leverage high-level language bindings that provide robust abstractions for the required filesystem operations. The fusepy library in Python enables rapid prototyping by allowing developers to subclass fuse.Operations and override specific methods like getattr, readdir, and read. For production environments demanding high throughput and memory safety, the Rust ecosystem offers the fuser crate for synchronous implementations and the fuse3 crate for asynchronous, multi-core optimized architectures. Go developers frequently utilize go-fuse or jacobsa/fuse to build cloud-native virtual filesystems.

The viability of this architecture is demonstrated by numerous mature, real-world implementations. Tools like SSHFS translate local file operations into Secure File Transfer Protocol (SFTP) commands, while GCSFuse and S3FS allow object storage buckets to be mounted locally. Within the specific domain of productivity and issue tracking, implementations like gkeep-fuse map Google Keep infrastructure to local files. In the gkeep-fuse implementation, notes possessing titles are mapped directly to filenames, whereas untitled notes utilize internal Google Keep identifiers for file naming. The interface natively supports listing, creating, reading, writing, renaming, and removing notes via standard terminal commands. Authentication is seamlessly handled by directing the FUSE daemon to a credentials file containing the user's authorization token or by utilizing environment variables such as GOOGLE_KEEP_USER and GOOGLE_KEEP_PASSWORD. When multi-factor authentication is enforced, the daemon is configured to utilize specific application passwords, effectively bypassing complex interactive login flows that would otherwise stall an autonomous agent.