# The Marionette > An optional quick pass before each prompt: a cheap model finds the files and line ranges your request is about and attaches that map for the main agent. [Video: The Marionette runs, the map fills in under the prompt, and the agent starts from it.](https://empryo.com/media/marionette-desktop.mp4) *The Marionette runs, the map fills in under the prompt, and the agent starts from it.* The **Marionette** is an optional step that runs before the main agent sees your prompt. A cheap model looks at your request, finds the files and line ranges it is about, and attaches that list to your message. The main agent then starts in the right place instead of spending expensive steps searching. It is marked **experimental** and is off by default. Every prompt already includes the [Genome](/docs/concepts/genome), a map of the whole repository. The Marionette adds a map of *this request*: which files matter, how they connect, and which past decisions apply. Your prompt is never rewritten. The map is attached underneath it. ## It finds code, it doesn't suggest fixes The Marionette only locates. Its output has no place for a guessed cause or a suggested fix. That is deliberate: a cheap model's guess can steer a stronger model the wrong way, while a list of relevant files only helps. Deciding what to change stays with the main agent. ## Using it In the terminal UI or the desktop composer: ``` /marionette fix the race in tab restore # run it for this one prompt /marionette fix it --steps 12 --time 90s # limit how long the survey runs /marionette on | off | status # run it on every prompt, or check ``` `on` and `off` apply to the current project. Add `global` to change it everywhere, for example `/marionette on global`. On desktop, the same switch is in the **Router** dialog under agent behavior. In headless runs, pass `--marionette`, and choose a mode with `--marionette-mode `. In config, the always-on switch is `agentFeatures.marionette`.  *The finished map, expanded: your asks, the relevant files with line ranges, how they connect, and related memories.* ## What the map contains While it runs, the map fills in under your prompt. Expand it to read: | Section | Contents | |---------|----------| | **asks** | Each separate thing you asked for, quoting your words | | **loci** | Relevant locations, like `file.ts:120-180 · symbol · role`, marked as primary or nearby | | **strands** | How those locations connect: callers, files that change together, what an edit could affect | | **memories** | Saved project decisions that apply | | **unmapped** | Anything the survey couldn't reach, stated plainly | Each connection names the tool that found it, so nothing in the map is a guess. [Video: The same map in the terminal UI, drawn in text.](https://empryo.com/media/marionette-tui.mp4) *The same map in the terminal UI, drawn in text.* ## Modes Choose a mode with `/marionette none|fast|assist|deep`, or set `marionetteMode` in config: | Mode | What runs | Speed and cost | |------|-----------|----------------| | `none` | Index lookup only, no model | About 0.2 seconds, no tokens | | `fast` *(default)* | Index lookup, then one model call to pick what belongs on the map | Quick and cheap | | `assist` | Index lookup, then a short read-only survey to confirm | Slower | | `deep` | A full read-only survey driven by the model | Slowest, most variable | The `--steps` and `--time` limits only apply to `assist` and `deep`, which run a survey loop. You can set defaults with `marionetteBudget.steps` and `marionetteBudget.timeMs`. ## Which model runs it Set the Marionette's model in `/router` (`taskRouter.marionette`). If you leave it unset, it uses the research model configured in the router. The Marionette only reads. It gets the same read-only tools as a research helper: language servers, the code map, impact analysis and memory search. If it fails, your prompt goes through unchanged, so it never costs you a turn. ## Why not ask the agent to explore first? The main agent can already send a research helper to explore. The difference is timing. The Marionette always runs before the turn starts, with a clean context, and returns a short structured map instead of a long report. It also brings in saved project memories. A research helper is still the right choice once the agent realizes mid-task that it needs to look at a whole subsystem. The Marionette covers the start of the task.