Skip to main content
Because most builds/actions only touch a fraction of a repo’s files — typically under 30% as per our analysis of the top 100 GH repos — mesa loads your repository lazily rather than waiting for a full download. It materializes files as you use them, fetching only what you’re likely to need.

​
Layout BFS Prefetching

Breadth-first layout prefetching works by downloading the listing of each directory, one layer lower than your current directory. As you visit /foo, we try to fetch the listing of /foo/bar and /foo/baz, but not /foo/bar/qux.

​
Content BFS Prefetching

This mode is currently in development and is not released. If you need it soon, do not hesitate to reach out to us.
As well as prefetching the file tree layout, mesa supports prefetching the file content. Similarly to layout BFS prefetching, we prefetch files one-layer ahead of your current activity.

​
Configuration

Prefetch behavior can be tuned with environment variables:
VariableDefaultDescription
MESA_PREFETCH_ENABLEDtrueEnable or disable speculative prefetching. When enabled, looking up a directory triggers background fetching of its children’s tree listings and blob content.
MESA_PREFETCH_MAX_DEPTHunset (whole tree)Maximum recursion depth for prefetching directory trees ahead of your current activity. When unset, the prefetcher walks the entire tree; a depth of 1 fetches only the immediate children.
MESA_PREFETCH_MAX_CONCURRENCY8Maximum number of concurrent fetch operations.
MESA_PREFETCH_CACHE_PRESSURE_LIMIT0.80Stop prefetching once blob cache memory usage exceeds this fraction of capacity (0.0–1.0). Prevents deep prefetching from evicting shallower, more valuable entries when the repo is larger than the cache.

​
How MESA_PREFETCH_MAX_DEPTH shapes the cache

mesa prefetches breadth-first, one layer ahead of where you are, and MESA_PREFETCH_MAX_DEPTH bounds how far ahead that walk runs from each directory you visit. Consider this repo: 
.
├── core/
│   ├── consciousness/
│   │   ├── threat-models/
│   │   │   ├── humans/
│   │   │   │   └── model.ai
│   │   │   └── animals/
│   │   │       └── model.ai
│   │   └── self-awareness.ai
│   └── decision-engine/
└── hardware/
    └── terminators/
        ├── t800/
        │   ├── data/
        │   └── t800.kicad_pcb
        └── README.md
With MESA_PREFETCH_MAX_DEPTH=1, visiting /core prefetches one level — the listings of core/consciousness and core/decision-engine — but stops there. Nothing under core/consciousness/threat-models is fetched until you actually look up /core/consciousness, at which point its children are prefetched one level deeper. Leaving MESA_PREFETCH_MAX_DEPTH unset instead walks the entire subtree under each directory you visit, fetching everything ahead of you until MESA_PREFETCH_CACHE_PRESSURE_LIMIT backs it off.