> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mesa.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Prefetching

> How mesa loads your repository in the background to reduce sandbox startup time.

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

<Note>
  This mode is currently in development and is not released. If you need it soon, do not hesitate to reach out to us.
</Note>

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:

| Variable                             | Default            | Description                                                                                                                                                                                                     |
| ------------------------------------ | ------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `MESA_PREFETCH_ENABLED`              | `true`             | Enable 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_DEPTH`            | unset (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_CONCURRENCY`      | `8`                | Maximum number of concurrent fetch operations.                                                                                                                                                                  |
| `MESA_PREFETCH_CACHE_PRESSURE_LIMIT` | `0.80`             | Stop 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.