Introduction

mado is a lazy, content-addressed FUSE virtual filesystem working copy for jj (Jujutsu). It mounts a jj working copy through the kernel, serves committed file content on demand over a content-addressed object store — local or networked — and folds edits made through the mount back into jj history. It is the open-source analog of Google Piper + CitC and Meta Mononoke + EdenFS, built on the released jj-lib (no forks).

A 50k-file repository mounts instantly because nothing is checked out up front: a file’s bytes are fetched the first time something reads them, cached on local disk, and never re-fetched. Edits land in an overlay that is journaled durably and auto-snapshotted into the working-copy commit (@) after a brief idle period — so an agent’s work is captured in jj history without it running a single command.

What mado is

• A jj working copy over FUSE. mado mount runs a daemon that serves @ through a mountpoint. Ordinary jj commands (log, describe, new, rebase, undo, …) work and reflect through the mount live.
• Content-addressed and lazy. Every object is keyed by its BLAKE3 hash. Reads fault content in on demand; the on-disk blob cache is never invalidated (a content-addressed blob is never stale) and never evicted by default.
• Networked or local. With MADO_REMOTE_ADDR set, object reads/writes go to a mado serve server over gRPC through a local caching client. Unset, mado works entirely against an on-disk store under .jj/repo/store.
• Built for portable agent workspaces. A workspace can be paused on one machine and resumed on another (mado ws pause / mado ws resume), guarded by a server-side lease so two machines never fight over one working copy. A running mount auto-checkpoints on a cadence, so a crashed machine is resumable elsewhere up to the last checkpoint.

What mado is not

• Not a git-interop layer. mado import-git / mado export-git are a one-way boundary conversion at the edges of the system (with a memoized, resumable, round-trippable mapping), not live bidirectional git syncing. The online interop tasks on mado serve are opt-in mirroring, not a merge protocol.
• Not a checkout. mado deliberately does not materialize the whole tree. The first read of an un-cached file pays a fetch; the design surfaces that cost honestly (see Performance) rather than hiding it behind an eager copy.
• Not cross-platform. mado is Linux-only (it depends on /dev/fuse or virtiofs / vhost-user).

How the pieces fit

  jj CLI  ──►  mado backend  ──►  content-addressed blob store
                                     │
  FUSE mount  ◄── mado daemon ──────┤   (local .jj/repo/store, or
   (reads fault content in,          │    a remote `mado serve` over gRPC,
    edits fold into @)               │    fronted by a local disk cache)
                                     │
  locality packs (MDLP) ◄───────────┘   one ranged GET hydrates a whole
                                          small-file subtree

The rest of this book is task-oriented:

• Getting started — init, mount, and daily jj use.
• Workspaces — pause / resume / checkpoint, and leases.
• Performance — locality packs, the disk cache, and honest cold-vs-warm expectations with the measured numbers.
• Operations — running a server, GC, recovery, and benchmarking.
• Reference — CLI verbs, environment variables, and on-disk file formats.